evtrack
Event tracking on websites using plain old JavaScript.
No third-party libraries or external dependencies.
Usage
-
For web pages: Just add
load.min.jsto your page (e.g. inside<head>element or right before the closing</body>tag) and configure tracking options. -
For browser extensions: Add
tracklib.min.jsandtrackui.min.js(in this order) to yourmanifest.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.jsonfile:
"content_scripts": [{
"js": [
"path/to/evtrack/tracklib.min.js",
"path/to/evtrack/trackui.min.js",
"main.js"
]
}],- Add
TrackUI.record(settings)inmain.js, wheresettingsholds 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
cursorcolumn indicates the cursor ID. Will be0for a regular computer mouse, or an integer indicating the finger ID for touch-capable browsers. - The
timestampcolumn indicates the timestamp of the event, with millisecond precision. - The
xposandyposcolumns indicate thexandyposition of the cursor, respectively. For events that do not relate to any mouse event (e.g.loadorblur), these values will be0. - The
eventcolumn indicates the browser's event name. - The
xpathcolumn indicates the target element that relates to the event, in XPath notation. - The
attrscolumn indicates the element attributes, if any. - The
extrascolumn is populated with the result of thecallbacksetting 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.