Snowplow JavaScript Tracker 2.3.0 released

We are pleased to announce the release of version 2.3.0 of the Snowplow JavaScript Tracker! This release adds a number of new features including the ability to send events by POST rather than GET, some new contexts, and improved automatic form tracking.

This blog post will cover the changes in detail.

1. POST support
2. Customizable form tracking
3. Automatic contexts
4. Development quickstart
5. Other improvements
6. Upgrading
7. Documentation and getting help

1. POST support

Until now, the JavaScript Tracker has sent events to Snowplow using GET requests, with the event payload in the querystring. The recently released version 1.0.0 of the Clojure Collector added CORS support, so it can now accept POST requests from the browser. This has two advantages:

• Internet Explorer’s querystring limit means that a large event payload sent via GET could be truncated. There is no such size limit on POST requests
• It’s possible to batch multiple events into a single request

An example

window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { appId: 'my-application', platform: 'web', post: true, // Use POST rather than GET bufferSize: 3 // Batch size for POST requests - defaults to 1 <span class="p">});

This snippet configures a tracker to wait until 3 events have occurred, then batch them together in a single POST request.

The JavaScript Tracker stores events in localStorage and only deletes them once they have been sent successfully. When a user leaves the page, the tracker will try to send all buffered events, but even if it fails they will still be present in localStorage and will be sent the next time the user is on a page belonging to the same host.

Note that if localStorage is unavailable, the bufferSize will always be set to 1 (meaning that events are POSTed as soon as they occur) to minimise the risk of losing buffered events when the user leaves the page.

Internet Explorer versions 9 and earlier do not support cross-origin XMLHttpRequests so the Tracker will default to GET requests in those environments. Going forward, we intend to add support for sending cross-origin POST requests using the XDomainRequest object available in Internet Explorer 8 and 9.

2. Customizable form tracking

The enableFormTracking method turns on automatic form tracking – whenever a visitor edits a field of a form or submits a form, a change_form or submit_form unstructured event will automatically be generated.

This release adds an additional config argument to enableFormTracking, allowing you to choose which fields and which forms get tracked. This is invaluable for automatically tracking forms which contain PII, financial or otherwise sensitive data.

The configuration object should have two elements: “forms” and “fields”. The “forms” value specifies which forms on the page will be tracked; the “fields” value specifies which fields of the tracked forms will be tracked.

There are three possible ways to specify which elements should be tracked:

• A whitelist: only track those elements whose class (in the case of forms) or name (in the case of fields) is in a given array
• A blacklist: track every element whose class/name is not in a given array
• A filter: track every element for which a given function returns true

An example

This tracks only forms with the “signup” or “order” class, and tracks every field of those forms except for those named “password”.

var config = { forms: { whitelist: ['signup', 'order'] }, fields: { blacklist: ['password'] } <span class="p">};

This tracks every form (the default when a field is not specified) and tracks every field with id not equal to “private”.

var config = { fields: { filter: function (fieldElement) { return fieldElement.id !== 'private'
<span class="p">; } } <span class="p">};

3. Automatic contexts

Version 2.1.0 added the automatically generated PerformanceTiming context containing information from the Navigation Timing API, which could be attached to all page views and page pings. This was activated using a boolean argument to the trackPageView method.

This release adds two new optional generated contexts: the Google Analytics cookies context and the geolocation_context context. If enabled, these two contexts plus the PerformanceTiming context will be now added to every event, not just page views and page pings.

We strongly recommend using POST if you are attaching one or more of these contexts to your events.

gaCookies

If this context is enabled, the JavaScript Tracker will look for Google Analytics cookies (specifically the “__utma”, “__utmb”, “__utmc”, “__utmv”, “__utmz”, and “_ga” cookies) and combine their values into a context which gets sent with every event.

geolocation

This context is built from the Geolocation API. If you enable it and a user hasn’t already given permission to use their geolocation information, a prompt will appear asking if they wish to share their location. If they accept, the geolocation context will be added to all subsequent events.

performanceTiming

This context is unchanged, although the way it is enabled in the Tracker has been updated – see the next section for details.

Usage

These optional contexts are now configured in the argmap when creating a new tracker. Note that the performanceTracking boolean argument to the trackPageView method has been deprecated. You should remove it from your trackPageView calls.

Use the new contexts field in the tracker constructor to choose which contexts are set:

// Configuring a tracker to send all three contexts window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { appId: 'my-application', platform: 'web', contexts: { geolocation: true, performanceTiming: true, gaCookies: true } <span class="p">});

4. Development quickstart

We have added a Vagrantfile to the repository so that as long as you have VirtualBox and Vagrant installed, it is now trivial to get started contributing to the JavaScript Tracker:

 host$ git clone https://github.com/snowplow/snowplow-javascript-tracker.git host$ cd snowplow-javascript-tracker host$ vagrant up && vagrant ssh guest$ cd /vagrant guest$ sudo npm install

5. Other improvements

We have also:

• Prevented the tracker from sending NaN in the page ping offset fields #324
• Added tests for the detection of document size and browser features #270
• Added integration tests using the full tracker #154
• Moved the grunt-yui-compressor dependency into the Snowplow organization #172
• Renamed the “deploy” folder to “dist” #319

6. Upgrading

The upgraded minified tracker is available here:

http(s)://d1fc8wv8zag5ca.cloudfront.net/2.3.0/sp.js 

There is one backwards-incompatible change: the trackPageView method now takes only takes two arguments, customTitle and context, rather than three. Calls with three arguments will generate a deprecation warning in the user’s browser console, but will otherwise continue to work.

7. Documentation and getting help

You can find the full API documentation for the Snowplow JavaScript Tracker version 2.3.0 on the Snowplow wiki.

Check out the v2.3.0 release page on GitHub for the full list of changes made in this version.

Finally, if you run into any issues or have any questions, please [raise an issue] [issues] or get in touch with us via [the usual channels] [talk-to-us].