Andrej Cimperšek - diploma

-------------------------------------------------------------------------------

dojox.analytics

-------------------------------------------------------------------------------

Version 1.0

Release date: 12/17/2007

-------------------------------------------------------------------------------

Project state: 

[base]: alpha

[Urchin]: alpha

-------------------------------------------------------------------------------

Project authors

	Dustin Machi  (dmachi)

	Peter Higgins (dante)

-------------------------------------------------------------------------------

Project description

	analytics and client monitoring system.  Including the base analytics

system and any number of plugins enables logging of different system data

back to the server.  Plugins included at this time:

	dojo - reports dojo startup  collected information

	window - reports available window information to the server

	mouseOver - allows periodic sampling of mouseOver 

	mouseClick - reports any mouse clicks to the server

	idle - reports idle/activity 

	consoleMessages - reports console.* messages to the server	

	Additionally, a Google Analytics (Urchin tracker) helper is included

	in this project, though is unrelated to the Core dojox.analytics 

	project code. 

-------------------------------------------------------------------------------

Dependencies:

Dojo Core (package loader).

-------------------------------------------------------------------------------

Documentation

Usage:

The primary intended usage will be to create a custom build layer that includes 

the particular plugins you need for your project.   However in practice you

can use the system as such:

	<script type="text/javascript" src="../../../dojo/dojo.js"

                djConfig="parseOnLoad: true, isDebug: false, usePlainJson: true, sendMethod: 'script', sendInterval: 5000"></script>

        <script language="JavaScript" type="text/javascript">

                // include the analytics system

                dojo.require("dojox.analytics");

                //tracks mouse clicks on the page

                dojo.require("dojox.analytics.plugins.mouseClick");

                // this plugin returns the informatin dojo collects when it launches

                dojo.require("dojox.analytics.plugins.dojo");

                // this plugin return the information the window has when it launches

                // and it also ties to a few events such as window.option

                dojo.require("dojox.analytics.plugins.window");

                // this plugin tracks console. message, It logs console.error, warn, and

                // info messages to the tracker.  It also defines console.rlog() which

                // can be used to log only to the server.  Note that if isDebug() is disabled

                // you will still see the console messages on the sever, but not in the actual

                // browser console.

                dojo.require("dojox.analytics.plugins.consoleMessages");

                // tracks where a mouse is on a page an what it is over, periodically sampling

                // and storing this data

                dojo.require("dojox.analytics.plugins.mouseOver");

                //tracks when the user has gone idle

                dojo.require("dojox.analytics.plugins.idle");

	</script> 

When done using a build, none of the dojo.require() statement will be requires 

would already be in the build. 

Most of the plugins and the base itself have a number of configurable params

that are passed in via the djConfig variable set.  This approach is taken so that

the parameters can be easily provided in the case of a build or for a custom

dojo.js build with analytics built in. Examples for different build profiles 

are in the profiles directory.

Available Configuration Parameters:

	Base Configs

	sendInterval - Normal send interval. Default 5000 

	sendMethod - "script" || "xhrPost"

	inTransitRetry - Delay before retrying an a send if it was in transit

			or if there is still data to be sent after a post.

			Default 1000

	analyticsUrl - url to send logging data to. defaults to the test php 

			file for now

	maxRequestSize - Maximum size of GET style requests. Capped at 2000 for 

			IE, and 4000 otherwise	

	consoleMessages Config:

	consoleLogFuncs - functions from the console object that you will log to 

			the server. If the console object doesn't exist

			or a particuarl method doesn't exist it will be

			created as a remote logging only method. This provides

			a quick and convient way to automatically define

			a remote logging funciton that includes the functions

			name in the log.  The 'rlog' in the default paramerters

			is an example of this.  Defaults to ["error", "warn", "info", "rlog"]	

	idle Config:

		idleTime - Number of ms to be idle before being reported to the server as idle

	mouseOver config:

		targetProps - the properties whose values will be reported for each target from

				a mouse over sample.  defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ]

		sampleDelay - the delay in ms between mouseover samples. Defaults to 2500

	window config:

		windowConnects - methods on the window objec that will be attached to 

				have its data passed to the server when called.

Note that the basic usage of this system simply serializes json with toJson() when passed

to the analytics addData() method.  If data is passed that has circular references

it will die.  Take care not to do that or be surprised when it doens't work

in those cases.

-------------------------------------------------------------------------------

Installation instructions

Grab the following from the Dojo SVN Repository:

http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/analytics

Install into the following directory structure:

/dojox/analytics/

...which should be at the same level as your Dojo checkout.