evtrack

Event tracking on websites using plain old JavaScript. No third-party libraries or external dependencies. 😃

Usage

For web pages: Just add load.min.js to your page (e.g. inside <head> element or right before the closing </body> tag) and configure tracking options.
For browser extensions: Add tracklib.min.js and trackui.min.js (in this order) to your manifest.json (or similar) and configure tracking options.

Example 1

Default configuration. Capture any browser event whenever it happens.

<script src="/path/to/load.min.js"></script>
<script>
(function(){

  TrackUI.record({
    // Remember to point to save.php (or similar) to write the log files.
    postServer: "/path/to/save.php"
  });

})();
</script>

Example 2

Capture all mouse clicks whenever they happen. Also capture every mouse movement at 50 ms. All other browser events are ignored.

<script src="/path/to/load.min.js"></script>
<script>
(function(){

  TrackUI.record({
    postServer: "/path/to/save.php",
    regularEvents: "click",
    pollingEvents: "mousemove",
    pollingMs: 50,
  });

})();
</script>

Example 3

Capture any browser event every 500 ms.

<script src="/path/to/load.min.js"></script>
<script>
(function(){

  TrackUI.record({
    postServer: "/path/to/save.php",
    regularEvents: "",
    pollingEvents: "*",
    pollingMs: 500,
  });

})();
</script>

Example 4

Use the default settings within a Chrome extension:

Add the following snippet to your manifest.json file:

"content_scripts": [{
  "js": [
    "path/to/evtrack/tracklib.min.js",
    "path/to/evtrack/trackui.min.js",
    "main.js"
  ]
}],

Add TrackUI.record(settings) in main.js, where settings holds your tracking options.

Default tracking settings

The settings object has the following defaults:

TrackUI.record({
  // The server where logs will be stored.
  postServer: "//my.server.org/save.script",
  // The interval (in seconds) to post data to the server.
  postInterval: 30,
  // Events to be tracked whenever the browser fires them. Default:
  //      mouse-related: "mousedown mouseup mousemove mouseover mouseout mousewheel click dblclick"
  //      touch-related: "touchstart touchend touchmove"
  //   keyboard-related: "keydown keyup keypress"
  //     window-related: "load unload beforeunload blur focus resize error online offline"
  //             others: "scroll change select submit reset contextmenu cut copy paste"
  // If this property is empty, no events will be tracked.
  // Use space-separated values to indicate multiple events, e.g. "click mousemove touchmove".
  // The "*" wildcard can be used to specify all events.
  regularEvents: "*",
  // Events to be polled, because some events are not always needed (e.g. mousemove).
  // If this property is empty (default value), no events will be polled.
  // Use space-separated values to indicate multiple events, e.g. "mousemove touchmove".
  // The "*" wildcard can be used to specify all events.
  // Events in pollingEvents will override those specified in regularEvents.
  // You can leave regularEvents empty and use only pollingEvents, if need be.
  pollingEvents: "",
  // Sampling frequency (in ms) to register events.
  // If set to 0, every single event will be recorded.
  pollingMs: 150,
  // A name that identifies the current task.
  // Useful to filter logs by e.g. tracking campaign ID.
  taskName: "evtrack",
  // A custom function to execute on each recording tick.
  callback: null,
  // Whether to dump element attributes together with each recorded event.
  saveAttributes: true,
  // Enable this to display some debug information
  debug: false
})

Result

For each browsed page, you'll have in the logs directory the following files:

A space-delimited CSV-like file with 8 columns.
An XML file with some metadata.

CSV file example

cursor timestamp xpos ypos event xpath attrs extras
0 1405503114382 0 0 load / {}

Where:

The cursor column indicates the cursor ID. Will be 0 for a regular computer mouse, or an integer indicating the finger ID for touch-capable browsers.
The timestamp column indicates the timestamp of the event, with millisecond precision.
The xpos and ypos columns indicate the x and y position of the cursor, respectively. For events that do not relate to any mouse event (e.g. load or blur), these values will be 0.
The event column indicates the browser's event name.
The xpath column indicates the target element that relates to the event, in XPath notation.
The attrs column indicates the element attributes, if any.
The extras column is populated with the result of the callback setting you've set.

XML file example

<?xml version="1.0" encoding="UTF-8"?>
<data>
 <ip>127.0.0.1</ip>
 <date>Wed, 16 Jul 2014 11:32:24 +0200</date>
 <url>http://localhost/evtrack/test.html</url>
 <ua>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36</ua>
 <screen>1600x900</screen>
 <window>1551x548</window>
 <document>1551x548</document>
 <task>evtrack</task>
</data>

The <task /> element is the value you've set in the taskName setting. This is useful to annotate a particular tracking campaign's ID, an experimental user group, etc.

Citation

If you use this software in any academic project, please cite it as:

Leiva, L.A. and Vivó, R. Web Browsing Behavior Analysis and Interactive Hypervideo. ACM Transactions on the Web 7(4), 2013.

@Article{Leiva13-tweb,
 author   = {Luis A. Leiva and Roberto Viv\'o},
 title    = {Web Browsing Behavior Analysis and Interactive Hypervideo},
 journal  = {ACM Transactions on the Web},
 volume   = {7},
 number   = {4},
 year     = {2013},
}

License

This software is dual-licensed under the MIT and LGPL v3 licenses. See the license dir.

luileito/evtrack