git.pond.sub.org Git - eow/blob - static/dojo-release-1.1.1/dojox/analytics/README

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