micnews / condor

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

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.

condor's Issues

Unite initial visibility with onfocus & onblur

We want to unite initial visibility, focus and blur events into a visibility event.

The initial visibility would then be a visibility that happens at the offset 0.

For this to work a polyfill for older browsers would need to be created.

visible time elapsed

I'm seeing quite large values for duration, i figure because people leave tabs open,
so what would be more meaningful is how long someone actually spends looking at a page,
therefore we should have visible-duration column, which is a timer that would be paused when the page is hidden.

test everything

Change example to a batched POST

We want to batch multiple events into one POST request, update the example to reflect this

create readme

custom columns

as discussed here: micnews/megafunnel#7

there needs to be some support for a custom column? maybe just pass a string option in when creating condor?

do we want to create uuid for users if they don't have one cookied?

that way if we need to track page views or actions tied to single user we can?

Secure tracking

We need to figure out a way to make sure that other people can't send in bogus data to our tracking stream.

log mouse movements

mouse movements can provide insight about what the user is looking at

For example:
https://www.luckyorange.com/heatmaps.php

lots of scroll data

I think we should reduce the amount of scroll data collected. Perhaps, we can send the max-Y that was scrolled to instead of every scroll action.

Also:

• 7,030 load events vs 7,141 end events -- why the discrepancy?

Track when window gets closed

Add a close event when the browser window gets closed

Some tests are failing sometimes

There's sometimes tests failing, even though they (sometimes) pass when ran manually.

add max-scroll column(s)

The ability to create a scroll distance heatmap would be much easier if the end event contained the max scroll distance.

Batching data & timestamp on server

In the example we're now batching up data and sendning multiple events in one POST request.
However, we also want to be able to set correct timestamps on each event in the sever, something that isn't duable when we batch data up like this.

Track href and target if someone clicks on an element within an a-element

Track arbitrary data

In some cases we will want to track arbitrary data, this could be contained in a data attribute (ie: data-trackable="...").

Track submit on forms

When a form is submitted we want to track that

Tests are faling

They're not only failing, they don't seem to be run correctly at all. I need to investigate what's up with that.

Ability to push trackable-custom events

Currently we can't push custom events.

My idea is to add a "trackable-custom" event type and expose a condor.log() method.

For example, after a Facebook share is completed:

function onShare() {
  // push trackable-custom event
  var trackableType = 'fb-share'
  var trackableValue = 'articleId:12345'
  condor.log(trackableType, trackableValue)
}

which would post:

trackable-custom,1280,855,0,4107,...,fb-share,articleId:12345