README
1-------------------------------------------------------------------------------
2dojox.analytics
3-------------------------------------------------------------------------------
4Version 1.0
5Release date: 12/17/2007
6-------------------------------------------------------------------------------
7Project state:
8[base]: alpha
9[Urchin]: alpha
10-------------------------------------------------------------------------------
11Project authors
12 Dustin Machi (dmachi)
13 Peter Higgins (dante)
14-------------------------------------------------------------------------------
15Project description
16 analytics and client monitoring system. Including the base analytics
17system and any number of plugins enables logging of different system data
18back to the server. Plugins included at this time:
19
20 dojo - reports dojo startup collected information
21 window - reports available window information to the server
22 mouseOver - allows periodic sampling of mouseOver
23 mouseClick - reports any mouse clicks to the server
24 idle - reports idle/activity
25 consoleMessages - reports console.* messages to the server
26
27 Additionally, a Google Analytics (Urchin tracker) helper is included
28 in this project, though is unrelated to the Core dojox.analytics
29 project code.
30
31-------------------------------------------------------------------------------
32Dependencies:
33
34Dojo Core (package loader).
35-------------------------------------------------------------------------------
36Documentation
37
38Usage:
39
40The primary intended usage will be to create a custom build layer that includes
41the particular plugins you need for your project. However in practice you
42can use the system as such:
43
44 <script type="text/javascript" src="../../../dojo/dojo.js"
45 djConfig="parseOnLoad: true, isDebug: false, usePlainJson: true, sendMethod: 'script', sendInterval: 5000"></script>
46
47 <script language="JavaScript" type="text/javascript">
48 // include the analytics system
49 dojo.require("dojox.analytics");
50
51 //tracks mouse clicks on the page
52 dojo.require("dojox.analytics.plugins.mouseClick");
53
54 // this plugin returns the informatin dojo collects when it launches
55 dojo.require("dojox.analytics.plugins.dojo");
56
57 // this plugin return the information the window has when it launches
58 // and it also ties to a few events such as window.option
59 dojo.require("dojox.analytics.plugins.window");
60
61 // this plugin tracks console. message, It logs console.error, warn, and
62 // info messages to the tracker. It also defines console.rlog() which
63 // can be used to log only to the server. Note that if isDebug() is disabled
64 // you will still see the console messages on the sever, but not in the actual
65 // browser console.
66 dojo.require("dojox.analytics.plugins.consoleMessages");
67
68 // tracks where a mouse is on a page an what it is over, periodically sampling
69 // and storing this data
70 dojo.require("dojox.analytics.plugins.mouseOver");
71
72 //tracks when the user has gone idle
73 dojo.require("dojox.analytics.plugins.idle");
74
75 </script>
76
77When done using a build, none of the dojo.require() statement will be requires
78would already be in the build.
79
80Most of the plugins and the base itself have a number of configurable params
81that are passed in via the djConfig variable set. This approach is taken so that
82the parameters can be easily provided in the case of a build or for a custom
83dojo.js build with analytics built in. Examples for different build profiles
84are in the profiles directory.
85
86Available Configuration Parameters:
87
88 Base Configs
89 sendInterval - Normal send interval. Default 5000
90 sendMethod - "script" || "xhrPost"
91 inTransitRetry - Delay before retrying an a send if it was in transit
92 or if there is still data to be sent after a post.
93 Default 1000
94 analyticsUrl - url to send logging data to. defaults to the test php
95 file for now
96 maxRequestSize - Maximum size of GET style requests. Capped at 2000 for
97 IE, and 4000 otherwise
98
99 consoleMessages Config:
100
101 consoleLogFuncs - functions from the console object that you will log to
102 the server. If the console object doesn't exist
103 or a particuarl method doesn't exist it will be
104 created as a remote logging only method. This provides
105 a quick and convient way to automatically define
106 a remote logging funciton that includes the functions
107 name in the log. The 'rlog' in the default paramerters
108 is an example of this. Defaults to ["error", "warn", "info", "rlog"]
109
110 idle Config:
111
112 idleTime - Number of ms to be idle before being reported to the server as idle
113
114 mouseOver config:
115 targetProps - the properties whose values will be reported for each target from
116 a mouse over sample. defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ]
117
118 sampleDelay - the delay in ms between mouseover samples. Defaults to 2500
119
120 window config:
121 windowConnects - methods on the window objec that will be attached to
122 have its data passed to the server when called.
123
124
125Note that the basic usage of this system simply serializes json with toJson() when passed
126to the analytics addData() method. If data is passed that has circular references
127it will die. Take care not to do that or be surprised when it doens't work
128in those cases.
129
130-------------------------------------------------------------------------------
131Installation instructions
132
133Grab the following from the Dojo SVN Repository:
134http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/analytics
135
136Install into the following directory structure:
137/dojox/analytics/
138
139...which should be at the same level as your Dojo checkout.
140