condor

Track what a user does on a site in csv-format

Example

See the example folder for examples of how to use condor.

Usage

var xhr = require('xhr')
  , track = require('../condor')({
        // default 500ms
        // set for how long time scroll & resize events should be
        // [debounced](https://www.npmjs.org/package/debounce)
        // The `duration`-attribute is the last of these events.

        debounceTime: 300
    })

  , noop = function () {}

track.onevent = function (csv) {
  // this callback is called everytime an event happens
  // the data is a line of csv, see below for information on the format of the
  // csv
  xhr({
      method: 'POST'
    , body: csv
    , uri: '/track'
  }, noop)
}

// this gets called by beforeunload - so anything in here must be synchronous
track.onend = function (csv) {
  // this will be an end-event - meaning that the visit on the page has ended
  xhr({
      method: 'POST'
    , body: csv
    , uri: '/track'
    , sync: true
  }, noop)
}

The callback to '/track' gets called everytime a trackable event occur. csv is the data about the event (see data-format for details).

Csv format

Track is done in csv that corresponds to the following headers:

clientName,clientVersion,eventName,windowWidth,windowHeight,scrollX,scrollY,location,duration,referrer,path,clickX,clickY,href,target,visibility,name,trackableType,trackableValue,visitor,session

If not explicitly written out, the columns are always included (when available). For example, there's always a column describing the width of the window and if a referrer exists that's also always included in the events.

• clientName Always set to 'condor' so you can easily identify condor logs
• clientVersion The version of condor that generated the CSV
• eventName Describes what event that has occured. Is one of the following:
  • load Emitted when the page has loaded (window.onload)
  • resize Emitted everytime a user resize the window (window.onresize). All resizing within 500ms are tracked as one resize-event.
  • scroll Emitted everytime a user scroll. All scrolling within 500ms is tracked as one scoll-event.
  • visibility Event describing if the page is visible or not. The initial visibility (when the script was loaded) will have duration 0.
  • change Emitted when a user changes a form (document.onchange)
  • click Emitted when a user clicks on the page
  • end Emitted when a user ends its session on a page, e.g. closes the window or click on a link.
  • trackable-load, trackable-visible, trackable-hover, trackable-click These events handles dom-elements with special data-trackable-type and data-trackable-value attributes.
    • trackable-load On load each trackable element is logged with this event
    • trackable-visible Event emitted when a trackable gets visible, e.g. when a user scroll enough to show a trackable element
    • trackable-hover Event emitted when a user hover over a trackable element.
    • trackable-click Event emitted when a user click on a trackable element.
• windowWidth The width of the users window (Number in px)
• windowHeight The height of the users window (Number in px)
• scrollX How far the user has scrolled (horizontally)
• scrollY How far the user has scrolled (vertically)
• location The page the user is on (window.location)
• duration Time (in ms) that has gone by since tracking was initiated
• timestamp The time when the event happened (date.toUTCString())
• timezone The timezone (in minutes) the user is in (date..getTimezoneOffset())
• referrer The referrer header (document.referrer)
• path The css-path describing the DOM-element (if available). For click events this is the element clicked, for change events this is the element changed. For trackable-* events this is the trackable element.
• clickX The x-coordinate on the page that was clicked (event.pageX). Only applicable for click events.
• clickY The y-coordinate on the page that was clicked (event.pageY). Only applicable for click events.
• href The href-attribute on the a DOM-element associated with the DOM-element that was clicked. Only applicable for click events.
• target The target-attribute on the a DOM-element associated with the DOM-element that was clicked. Only applicable for click events.
• visibility String describing if the page was visible or not. Can be one of visible or hidden. Only applicable for visibility events.
• name The name-attribute on the DOM-element that was changed. Only applicable for change events.
• trackableType For trackable-* events this is the string from the data-trackable-type attribute.
• trackableValue For trackable-* events this is the string from the data-trackable-value attribute
• visitor A string that uniquely identifies a visitor
• session The number of all-time sessions for this visitor. This value is incremented after 30 minutes of inactivity.