Snowplow JavaScript Tracker 2.2.0 released

15 December 2014  •  Fred Blundun

We are happy to announce the release of version 2.2.0 of the Snowplow JavaScript Tracker. This release improves the Tracker’s callback support, making it possible to use access previously internal variables such as the tracker-generated user fingerprint and user ID. It also adds the option to disable the Tracker’s use of localStorage and first-party cookies.

The rest of this blog post will cover the following topics:

  1. More powerful callbacks
  2. Disabling localStorage and cookies
  3. Non-integer offsets
  4. Upgrading
  5. Getting help

1. More powerful callbacks

Version 2.1.1 added support for custom callbacks to be executed when sp.js loads:

snowplow(function () {
	console.log("sp.js has loaded");
});

This release extends that support by calling the callback function as a method on an internal trackerDictionary object. This sets the value of this in the callback to the trackerDictionary, allowing you to call methods which return results on individual tracker instances.

An example which extracts all the available fields:

// Configure a tracker instance named "cf"
snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', {
	appId: 'snowplowExampleApp',
	platform: 'web'
});

// Set a callback to be executed once sp.js loads
snowplow(function () {

	// Get the fingerprint which the tracker
	// generates based on browser features
	var userFingerprint = this.cf.getUserFingerprint();

	// Get the ID stored in the first party cookie
	var domainUserId = this.cf.getDomainUserId();

	// Get all information stored in the first party cookie
	var domainUserInfo = this.cf.getDomainUserInfo();

	// Get the ID which you set for the user
	var businessUserId = this.cf.getUserId();

	doSomethingWith(userFingerprint, domainUserId);
});

Note that getDomainUserInfo() returns an array containing 6 elements:

  1. A string set to '1' if this is the user’s first session and '0' otherwise
  2. The domain user ID
  3. The timestamp at which the cookie was created
  4. The number of times the user has visited the site
  5. The timestamp for the current visit
  6. The timestamp of the last visit

This change is backward-compatible unless you were relying on your callback function being executed in the global context (meaning that this is set to window).

We would like to thank Snowplow community member Rob Murphy (@murphybob) for his help developing this feature!

2. Disabling localStorage and cookies

The Snowplow JavaScript Tracker maintains a queue of events that have failed to send. This means that if a visitor loses and later regains connectivity, no data will be lost. By default the tracker will use localStorage to store this queue so the events are recoverable even after the user leaves the site.

You can now disable this use of localStorage by setting a flag in the argmap used to create a new tracker instance. You can also disable the use of first-party cookies:

// Configure a tracker instance named "cf"
snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', {
	appId: 'snowplowExampleApp',
	platform: 'web',

	// disable localStorage
	useLocalStorage: false,

	// disable first-party cookies
	useCookies: false
});

Disabling first-party cookies can be useful if you are deploying the JavaScript Tracker in an environment where first-party cookies are forbidden (for example, in ad tags running on Google domains).

3. Non-integer offsets

Snowplow page ping events include the maximum and minimum scroll distances since the last page ping. We found that it is possible for the scroll values reported by the browser to not be whole numbers, causing the event to fail enrichment (which requires these fields to be integers). We have fixed this bug by rounding the relevant values to the nearest integer.

4. Upgrading

The new minified and gzipped JavaScript is available at

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

5. Getting help

Check out the documentation for more help and examples.

If you have any suggestions for new features or need help getting set up, please get in touch. And raise an issue if you spot a bug!