-------------------------------------------------------------------------------
dojox.analytics
-------------------------------------------------------------------------------
Version 1.0
Release date: 12/17/2007
-------------------------------------------------------------------------------
Project state:
[base]: alpha
[Urchin]: alpha
-------------------------------------------------------------------------------
Project authors
Dustin Machi (dmachi)
Peter Higgins (dante)
Ed Chatelain (edchat) added touch and gesture support 11/15/2011.
-------------------------------------------------------------------------------
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
touchPress - reports touch.press and touch.release
touchMove - allows periodic sampling during a touch.move
gestureEvents - reports swipe, tap, tap.doubletap, tap.taphold
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 information 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 touch press and touch release on the page
dojo.require("dojox.analytics.plugins.touchPress");
// tracks where a touch move is done on a page, what it is over, periodically sampling
// and storing this data
dojo.require("dojox.analytics.plugins.touchMove");
// tracks these gesture events tap, taphold, doubletap, and swipe using the dojox.gesture
// support. For swipe it will periodically sample and store the data
dojo.require("dojox.analytics.plugins.gestureEvents");
//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 particular method doesn't exist it will be
created as a remote logging only method. This provides
a quick and convenient way to automatically define
a remote logging function that includes the functions
name in the log. The 'rlog' in the default parameters
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
mouseClick config:
targetProps - the properties whose values will be reported for each target from
a mouse click sample.
defaults to ["id","className","nodeName", "localName","href", "spellcheck", "lang"]
textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50
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" ]
watchMouseOver - log mouseover and mouseout events defaults to true
sampleDelay - the delay in ms between mouseover samples. Defaults to 2500
textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50
window config:
windowConnects - methods on the window objec that will be attached to
have its data passed to the server when called.
touchPress config:
targetProps - the properties whose values will be reported for each target from
a touch.press or touch.release sample.
defaults to ["id","className","nodeName", "localName","href", "spellcheck", "lang"]
textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50
showTouchesDetails - include the details for the touches in the touches array, defaults to true
touchMove config:
targetProps - the properties whose values will be reported for each target from
a touch move sample.
defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ]
textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50
showTouchesDetails - include the details for the touches in the touches array, defaults to true
touchSampleDelay - the delay in ms between touch.move samples. Defaults to 1000
gestureEvents config:
targetProps - the properties whose values will be reported for each target from
a gesture event (tap, taphold, doubletap, swipe) sample.
defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ]
swipeSampleDelay - the delay in ms between swipe samples. Defaults to 1000
textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50
watchSwipe - log swipe events in addition to the tap events, defaults to true
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.
