| 1 | ------------------------------------------------------------------------------- |
|---|
| 2 | dojox.analytics |
|---|
| 3 | ------------------------------------------------------------------------------- |
|---|
| 4 | Version 1.0 |
|---|
| 5 | Release date: 12/17/2007 |
|---|
| 6 | ------------------------------------------------------------------------------- |
|---|
| 7 | Project state: |
|---|
| 8 | [base]: alpha |
|---|
| 9 | [Urchin]: alpha |
|---|
| 10 | ------------------------------------------------------------------------------- |
|---|
| 11 | Project authors |
|---|
| 12 | Dustin Machi (dmachi) |
|---|
| 13 | Peter Higgins (dante) |
|---|
| 14 | ------------------------------------------------------------------------------- |
|---|
| 15 | Project description |
|---|
| 16 | analytics and client monitoring system. Including the base analytics |
|---|
| 17 | system and any number of plugins enables logging of different system data |
|---|
| 18 | back 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 | ------------------------------------------------------------------------------- |
|---|
| 32 | Dependencies: |
|---|
| 33 | |
|---|
| 34 | Dojo Core (package loader). |
|---|
| 35 | ------------------------------------------------------------------------------- |
|---|
| 36 | Documentation |
|---|
| 37 | |
|---|
| 38 | Usage: |
|---|
| 39 | |
|---|
| 40 | The primary intended usage will be to create a custom build layer that includes |
|---|
| 41 | the particular plugins you need for your project. However in practice you |
|---|
| 42 | can 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 | |
|---|
| 77 | When done using a build, none of the dojo.require() statement will be requires |
|---|
| 78 | would already be in the build. |
|---|
| 79 | |
|---|
| 80 | Most of the plugins and the base itself have a number of configurable params |
|---|
| 81 | that are passed in via the djConfig variable set. This approach is taken so that |
|---|
| 82 | the parameters can be easily provided in the case of a build or for a custom |
|---|
| 83 | dojo.js build with analytics built in. Examples for different build profiles |
|---|
| 84 | are in the profiles directory. |
|---|
| 85 | |
|---|
| 86 | Available 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 | |
|---|
| 125 | Note that the basic usage of this system simply serializes json with toJson() when passed |
|---|
| 126 | to the analytics addData() method. If data is passed that has circular references |
|---|
| 127 | it will die. Take care not to do that or be surprised when it doens't work |
|---|
| 128 | in those cases. |
|---|
| 129 | |
|---|
| 130 | ------------------------------------------------------------------------------- |
|---|
| 131 | Installation instructions |
|---|
| 132 | |
|---|
| 133 | Grab the following from the Dojo SVN Repository: |
|---|
| 134 | http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/analytics |
|---|
| 135 | |
|---|
| 136 | Install into the following directory structure: |
|---|
| 137 | /dojox/analytics/ |
|---|
| 138 | |
|---|
| 139 | ...which should be at the same level as your Dojo checkout. |
|---|
