Sandy Tracking Pixel client

Provides an API for relaying data to the sandy analytics pieline.

Installing

npm install

Building

The following command will build index.js and index-instrumented.js. Please commit both of these artifacts when the source is updated.

npm run build

Running Tests

npm test

Running Tests in the browser

Install serve, a great little static file server:

npm install -g serve

Run serve in this directory

serve

In your browser, visit http://localhost:3000/tests/

You can then use browser based tools to debug.

Publishing to NPM

This package is available at:

https://www.npmjs.com/package/sandy-tracking-pixel-client

When merging to master, the latest version will be published. Please ensure that you have upgraded the version number in:

package.json
header in index.js

Testing with Saucelabs

It is recommended that you run the tests in Saucelabs before committing.

To run the test:

Obtain relevant keys in https://saucelabs.com/beta/user-settings

export SAUCE_USERNAME=mobify
export SAUCE_ACCESS_KEY=xxxxxx

Run grunt and it should directly send your tests to saucelab.

grunt

Developing in Docker

docker build --rm -t sandy-pixel-client-dev .
docker run -it --rm -v $(pwd):/sandy sandy-pixel-client-dev /bin/bash -l
export PATH="$PATH:/sandy/node_modules/.bin"
npm install

Using the Sandy Client

The Sandy client provides an API (similar to google analytics) to ferry data from the browser into the Sandy analytics pipeline.

The Snippet

Using the snippet, calls can be made to the reporting API before loading the client library. These calls will turn into events relayed to the backend once the client library loads.

The snippet will also "short-circuit" in the case that the client library has already loaded, and events will be relayed directly to the backend when sandy commands are called.

The below code uses the snippet to create a tracker and send a pageview event.

(function(s,a) {
    s['SandyAnalyticsObject'] = a;
    s[a] = s[a] || function() {
        (s[a].q = s[a].q || []).push(arguments)
    }
})(window, 'sandy');
 
sandy('create', 'example-slug', 'auto');
sandy('send', 'pageview');

The Tracker

Tracker Creation

Before sending events, a "tracker" must be created. Tracker creation requires two parameters, a slug and a cookie domain.

The slug is a unique, human readable identifer used by Mobify to identify customer web projects.

The cookie domain specifies what domain to set cookies on for persistent attributes kept by the client, such as the session and client identifier. Additionally, you can provide the string 'auto' to allow the sandy client to decide what domain to set cookies on (this will choose the actual hostname of the containing page).

Tracker creation example:

sandy('create', 'beyond-the-rack', 'auto');

Multiple Tracker creation

There might be cases when you would like to have multiple trackers on the same page.

Case 1: Sharing the global tracker

If you would like to check and use the global version of tracker, you can do:

// This can only be used assuming you have the Sandy object imported
if (!Sandy.isInitialised(window)) {
    Sandy.init(window);
    sandy('create', 'beyond-the-rack', 'auto');
}

Case 2: Creating your own namespace version

If you would like to create your own tracker (e.g. using different slug)

// This can only be used assuming you have the Sandy object imported
Sandy.init(window, {'name': 'sandy2'})
sandy2('create', 'beyond-the-rack-2', 'auto');

Setting Dimensions

Dimensions, which are generally metadata associated with events, can be specified persistently (at least over the lifetime of a page load) using the 'set' command.

// set one dimension at a time
sandy('set', 'volume', 11);
 
// or several at once
sandy('set', {
   'region': 'americas',
   'language': 'en-ca'
});

Dimension names can be any string, values can be any primitive(number, boolean or string).

Dimensions will be added to any event sent after they are set on that pageview, but will need to be reset on the next page.

Sending Events

Once the tracker has been created, there are a couple of default event types that can be sent easily, as well as a "generic" way to send events.

Sending a pageview

Sending a pageview is as simple as

sandy('send', 'pageview');

Default dimensions for a pageview, such as page title, page (url path) and location (full page url) will be added automatically at the time the event is sent. Optionally, the 'page' dimension can be specified as a parameter to the pageview or every dimension can be specified as a dictionary.

See https://developers.google.com/analytics/devguides/collection/analyticsjs/events#overview for further information on the API parameters.

// parameter is page (path), title and location will be read automatically
sandy('send', 'pageview', '/category/fragrances');
 
// or a dictionary
sandy('send', 'pageview', {
    page: '/category/shirts',
    title: 'Shirts!',
    location: 'http://www.myshirtco.co.uk/category/shirts'
});

Sending Timing Events

Send a timing event by

// send category, action, label amd value as parameter values
sandy('send', 'timing', 'timing', 'DOMContentLoaded', '', myTimerValue);
 
// or use a GA style dictionary
sandy('timing', {
    timingCategory: 'performance',
    timingVar: 'firstPaint',
    timingLabel: 'after adaptation',
    timingValue: 745
});

Send Generic Events

Generic events can be sent with the send event command.

// After command, takes category, action, label, value, dimension object
sandy('send', 'event', 'playerActions', 'pause', '', 95, {
    'trackName': 'Nowhere to Run',
    'trackArtist': 'Martha Reeves and the Vandellas'
});
 
// or with a big 'ole object
sandy('send', 'event', {
    // The channel defaults to 'web' if not specified
    'eventChannel': 'special',
    'eventCategory': 'playerActions',
    'eventAction': 'pause',
    'eventValue': 95,
    'trackName': 'Nowhere to Run',
    'trackArtist': 'Martha Reeves and the Vandellas'
});

Note that the data will only be sent with this event and that the extra dimensions will not be persisted in the tracker.