| 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 | Ed Chatelain (edchat) added touch and gesture support 11/15/2011. |
|---|
| 15 | ------------------------------------------------------------------------------- |
|---|
| 16 | Project description |
|---|
| 17 | analytics and client monitoring system. Including the base analytics |
|---|
| 18 | system and any number of plugins enables logging of different system data |
|---|
| 19 | back to the server. Plugins included at this time: |
|---|
| 20 | |
|---|
| 21 | dojo - reports dojo startup collected information |
|---|
| 22 | window - reports available window information to the server |
|---|
| 23 | mouseOver - allows periodic sampling of mouseOver |
|---|
| 24 | mouseClick - reports any mouse clicks to the server |
|---|
| 25 | idle - reports idle/activity |
|---|
| 26 | consoleMessages - reports console.* messages to the server |
|---|
| 27 | touchPress - reports touch.press and touch.release |
|---|
| 28 | touchMove - allows periodic sampling during a touch.move |
|---|
| 29 | gestureEvents - reports swipe, tap, tap.doubletap, tap.taphold |
|---|
| 30 | |
|---|
| 31 | Additionally, a Google Analytics (Urchin tracker) helper is included |
|---|
| 32 | in this project, though is unrelated to the Core dojox.analytics |
|---|
| 33 | project code. |
|---|
| 34 | |
|---|
| 35 | ------------------------------------------------------------------------------- |
|---|
| 36 | Dependencies: |
|---|
| 37 | |
|---|
| 38 | Dojo Core (package loader). |
|---|
| 39 | ------------------------------------------------------------------------------- |
|---|
| 40 | Documentation |
|---|
| 41 | |
|---|
| 42 | Usage: |
|---|
| 43 | |
|---|
| 44 | The primary intended usage will be to create a custom build layer that includes |
|---|
| 45 | the particular plugins you need for your project. However in practice you |
|---|
| 46 | can use the system as such: |
|---|
| 47 | |
|---|
| 48 | <script type="text/javascript" src="../../../dojo/dojo.js" |
|---|
| 49 | djConfig="parseOnLoad: true, isDebug: false, usePlainJson: true, sendMethod: 'script', sendInterval: 5000"></script> |
|---|
| 50 | |
|---|
| 51 | <script language="JavaScript" type="text/javascript"> |
|---|
| 52 | // include the analytics system |
|---|
| 53 | dojo.require("dojox.analytics"); |
|---|
| 54 | |
|---|
| 55 | //tracks mouse clicks on the page |
|---|
| 56 | dojo.require("dojox.analytics.plugins.mouseClick"); |
|---|
| 57 | |
|---|
| 58 | // this plugin returns the information dojo collects when it launches |
|---|
| 59 | dojo.require("dojox.analytics.plugins.dojo"); |
|---|
| 60 | |
|---|
| 61 | // this plugin return the information the window has when it launches |
|---|
| 62 | // and it also ties to a few events such as window.option |
|---|
| 63 | dojo.require("dojox.analytics.plugins.window"); |
|---|
| 64 | |
|---|
| 65 | // this plugin tracks console. message, It logs console.error, warn, and |
|---|
| 66 | // info messages to the tracker. It also defines console.rlog() which |
|---|
| 67 | // can be used to log only to the server. Note that if isDebug() is disabled |
|---|
| 68 | // you will still see the console messages on the sever, but not in the actual |
|---|
| 69 | // browser console. |
|---|
| 70 | dojo.require("dojox.analytics.plugins.consoleMessages"); |
|---|
| 71 | |
|---|
| 72 | // tracks where a mouse is on a page an what it is over, periodically sampling |
|---|
| 73 | // and storing this data |
|---|
| 74 | dojo.require("dojox.analytics.plugins.mouseOver"); |
|---|
| 75 | |
|---|
| 76 | //tracks touch press and touch release on the page |
|---|
| 77 | dojo.require("dojox.analytics.plugins.touchPress"); |
|---|
| 78 | |
|---|
| 79 | // tracks where a touch move is done on a page, what it is over, periodically sampling |
|---|
| 80 | // and storing this data |
|---|
| 81 | dojo.require("dojox.analytics.plugins.touchMove"); |
|---|
| 82 | |
|---|
| 83 | // tracks these gesture events tap, taphold, doubletap, and swipe using the dojox.gesture |
|---|
| 84 | // support. For swipe it will periodically sample and store the data |
|---|
| 85 | dojo.require("dojox.analytics.plugins.gestureEvents"); |
|---|
| 86 | |
|---|
| 87 | //tracks when the user has gone idle |
|---|
| 88 | dojo.require("dojox.analytics.plugins.idle"); |
|---|
| 89 | |
|---|
| 90 | </script> |
|---|
| 91 | |
|---|
| 92 | When done using a build, none of the dojo.require() statement will be requires |
|---|
| 93 | would already be in the build. |
|---|
| 94 | |
|---|
| 95 | Most of the plugins and the base itself have a number of configurable params |
|---|
| 96 | that are passed in via the djConfig variable set. This approach is taken so that |
|---|
| 97 | the parameters can be easily provided in the case of a build or for a custom |
|---|
| 98 | dojo.js build with analytics built in. Examples for different build profiles |
|---|
| 99 | are in the profiles directory. |
|---|
| 100 | |
|---|
| 101 | Available Configuration Parameters: |
|---|
| 102 | |
|---|
| 103 | Base Configs |
|---|
| 104 | sendInterval - Normal send interval. Default 5000 |
|---|
| 105 | sendMethod - "script" || "xhrPost" |
|---|
| 106 | inTransitRetry - Delay before retrying an a send if it was in transit |
|---|
| 107 | or if there is still data to be sent after a post. |
|---|
| 108 | Default 1000 |
|---|
| 109 | analyticsUrl - url to send logging data to. defaults to the test php |
|---|
| 110 | file for now |
|---|
| 111 | maxRequestSize - Maximum size of GET style requests. Capped at 2000 for |
|---|
| 112 | IE, and 4000 otherwise |
|---|
| 113 | |
|---|
| 114 | consoleMessages Config: |
|---|
| 115 | |
|---|
| 116 | consoleLogFuncs - functions from the console object that you will log to |
|---|
| 117 | the server. If the console object doesn't exist |
|---|
| 118 | or a particular method doesn't exist it will be |
|---|
| 119 | created as a remote logging only method. This provides |
|---|
| 120 | a quick and convenient way to automatically define |
|---|
| 121 | a remote logging function that includes the functions |
|---|
| 122 | name in the log. The 'rlog' in the default parameters |
|---|
| 123 | is an example of this. Defaults to ["error", "warn", "info", "rlog"] |
|---|
| 124 | |
|---|
| 125 | idle Config: |
|---|
| 126 | |
|---|
| 127 | idleTime - Number of ms to be idle before being reported to the server as idle |
|---|
| 128 | |
|---|
| 129 | mouseClick config: |
|---|
| 130 | targetProps - the properties whose values will be reported for each target from |
|---|
| 131 | a mouse click sample. |
|---|
| 132 | defaults to ["id","className","nodeName", "localName","href", "spellcheck", "lang"] |
|---|
| 133 | |
|---|
| 134 | textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50 |
|---|
| 135 | |
|---|
| 136 | mouseOver config: |
|---|
| 137 | targetProps - the properties whose values will be reported for each target from |
|---|
| 138 | a mouse over sample. |
|---|
| 139 | defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ] |
|---|
| 140 | |
|---|
| 141 | watchMouseOver - log mouseover and mouseout events defaults to true |
|---|
| 142 | |
|---|
| 143 | sampleDelay - the delay in ms between mouseover samples. Defaults to 2500 |
|---|
| 144 | |
|---|
| 145 | textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50 |
|---|
| 146 | |
|---|
| 147 | window config: |
|---|
| 148 | windowConnects - methods on the window objec that will be attached to |
|---|
| 149 | have its data passed to the server when called. |
|---|
| 150 | |
|---|
| 151 | touchPress config: |
|---|
| 152 | targetProps - the properties whose values will be reported for each target from |
|---|
| 153 | a touch.press or touch.release sample. |
|---|
| 154 | defaults to ["id","className","nodeName", "localName","href", "spellcheck", "lang"] |
|---|
| 155 | |
|---|
| 156 | textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50 |
|---|
| 157 | |
|---|
| 158 | showTouchesDetails - include the details for the touches in the touches array, defaults to true |
|---|
| 159 | |
|---|
| 160 | |
|---|
| 161 | touchMove config: |
|---|
| 162 | targetProps - the properties whose values will be reported for each target from |
|---|
| 163 | a touch move sample. |
|---|
| 164 | defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ] |
|---|
| 165 | |
|---|
| 166 | textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50 |
|---|
| 167 | |
|---|
| 168 | showTouchesDetails - include the details for the touches in the touches array, defaults to true |
|---|
| 169 | |
|---|
| 170 | touchSampleDelay - the delay in ms between touch.move samples. Defaults to 1000 |
|---|
| 171 | |
|---|
| 172 | gestureEvents config: |
|---|
| 173 | targetProps - the properties whose values will be reported for each target from |
|---|
| 174 | a gesture event (tap, taphold, doubletap, swipe) sample. |
|---|
| 175 | defaults to ["id","className","localName","href", "spellcheck", "lang", "textContent", "value" ] |
|---|
| 176 | |
|---|
| 177 | swipeSampleDelay - the delay in ms between swipe samples. Defaults to 1000 |
|---|
| 178 | |
|---|
| 179 | textContentMaxChars - the max number of characters to show for text or textContent, defaults to 50 |
|---|
| 180 | |
|---|
| 181 | watchSwipe - log swipe events in addition to the tap events, defaults to true |
|---|
| 182 | |
|---|
| 183 | |
|---|
| 184 | |
|---|
| 185 | Note that the basic usage of this system simply serializes json with toJson() when passed |
|---|
| 186 | to the analytics addData() method. If data is passed that has circular references |
|---|
| 187 | it will die. Take care not to do that or be surprised when it doens't work |
|---|
| 188 | in those cases. |
|---|
| 189 | |
|---|
| 190 | ------------------------------------------------------------------------------- |
|---|
| 191 | Installation instructions |
|---|
| 192 | |
|---|
| 193 | Grab the following from the Dojo SVN Repository: |
|---|
| 194 | http://svn.dojotoolkit.org/var/src/dojo/dojox/trunk/analytics |
|---|
| 195 | |
|---|
| 196 | Install into the following directory structure: |
|---|
| 197 | /dojox/analytics/ |
|---|
| 198 | |
|---|
| 199 | ...which should be at the same level as your Dojo checkout. |
|---|
