Snowplow JavaScript Tracker 2.8.0 released

We are pleased to announce a new release of the Snowplow JavaScript Tracker. Version 2.8.0 gives you much more flexibility and control in the area of in-browser user privacy, as well as adding new integrations for Parrable and OptimizelyX.

Read on below the fold for:

1. State storage strategy
2. Opt-out cookie
3. Better form tracking for passwords
4. New OptimizelyX and Parrable contexts
5. Extracting valuable metadata from the tracker
6. Improved page activity handling
7. Upgrading
8. Documentation and help

1. State storage strategy

This release introduces the stateStorageStrategy property to the tracker configuration, taking one of four values: cookieAndLocalStorage, cookie, localStorage or none.

The cookieAndLocalStorage value (the default) will follow the same behavior than the previous versions of the tracker: the id and session data will be stored in cookies (similar to if you had set useCookies to true or left it unspecified) and outgoing events will be buffered in local storage (previously controlled using useLocalStorage).

The cookie value will store the id and session data in cookies. However, outgoing events won’t be buffered in local storage.

The localStorage value will store those two first-party cookies in local storage. This approach is recommended if you are reaching the maximum HTTP header size of 4kb present on most servers. The outgoing event buffer will continue to use local storage.

The last possible value is none. In this case, nothing will be stored, neither in cookies nor in local storage. This is equivalent to setting the old useCookies and useLocalStorage settings both to false.

This table recaps everything said so far:

Since the useLocalStorage and useCookies argmap parameters have been made redundant by the introduction of stateStorageStrategy, they’ve been deprecated.

As an example, we could get the JavaScript Tracker to use local storage with:

window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { appId: 'CFe23a', platform: 'web', stateStorageStrategy: 'localStorage' <span class="p">});

2. Opt-out cookie

Similar to the Do Not Track option, we’re introducing a way to set an opt out cookie. If this cookie is set, no tracking will be performed.

You can set this cookie with:

window.snowplow_name_here('setOptOutCookie', 'opt-out'<span class="p">);

where ‘opt-out’ is the name of your opt-out cookie.

3. Better form tracking for passwords

Previous versions of the JavaScript Tracker tracked changes to password fields in forms if you had form tracking enabled via:

snowplow_name_here('enableFormTracking'<span class="p">);

Thanks to the work of Snowflake Analytics’ Mike Robins, as of this release password fields in forms won’t be auto-tracked.

4. New OptimizelyX and Parrable contexts

4.1 Parrable context

Parrable is a device identification platform which lets you idenitfy devices across browser and apps without personally identifiable information. This release introduces support for a Parrable context which will keep track of this identifier.

You can enable this context when initializing the JavaScript Tracker:

windo
w.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { appId: 'CFe23a', platform: 'web', contexts: { ... 'parrable': true } <span class="p">});

You can also have a look at the JSON Schema for the Parrable context.

There are further setup steps required to make use of Parrable data in the Snowplow pipeline; we will provide a tutorial for this soon.

Many thanks to Parrable’s Chantal Galvez Omaña for contributing the Parrable support to the JavaScript Tracker!

4.2 OptimizelyX context

This release also brings support for OptimizelyX, which supplements the support for the original Optimizely service introduced in version 2.6.0 of the Tracker.

You can enable this context like any other:

window.snowplow('newTracker', 'cf', 'd3rkrsqld9gmqf.cloudfront.net', { appId: 'CFe23a', platform: 'web', contexts: { ... 'optimizelyXSummary': true } <span class="p">});

The schema for this context is available in Iglu Central.

If you are planning on leveraging the context’s variationNames, please untick ‘Mask descriptive names in project code and third-party integrations’ in the OptimizelyX menu -> Settings -> Privacy. Otherwise, all variation names will be null.

Thanks to Snowflake Analytics’ Mike Robins for adding the support for OptimizelyX.

5. Extracting valuable metadata from the tracker

In an effort to give you more control, we’ve exposed a few properties internal to the tracker such as cookie names, page view IDs and domain session indices.

The recommended way of retrieving these data points is via a tracker callback, which prevents problems if the tracker hasn’t finished loading.

The following examples assume you have configured a tracker in the following way:

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

For example, you can retrieve the complete cookie name for the domain cookie like so:

snowplow(function () { var cf = this.cf<span class="p">; var cookieName = cf.getCookieName('id'<span class="p">); doSomethingWithDomainCookieName(cookieName<span class="p">); <span class="p">});

Where ‘id’ is the basename of the cookie you want to retrieve. Here it is the basename of the domain cookie, the basename for the session cookie being ‘ses’. The returned value should be made of the cookie prefix (the ‘cookieName’ tracker configuration option, which defaults to ‘sp’), its basename as well as a suffix based on a hash of the cookie domain.

Same goes for the page view ID:

snowplow(function() { var cf = this.cf<span class="p">; var pageViewId = cf.getPageViewId<span class="p">(); doSomethingWithPageViewId(pageViewId<span class="p">); <span class="p">});

And the domain session index:

snowplow(function() { var cf = this.cf<span class="p">; var domainSessionIndex = cf.getDomainSessionIndex<span class="p">(); doSomethingWithDomainSessionIndex(domainSessionIndex<span class="p">); <span class="p">});

If you have any other suggestions for tracker data that we should expose via get() methods, please add these to issue 548 in GitHub.

6. Improved page activity handling

In this release, we are also allowing external triggering of the activityHandler. This was motivated by the fact that some events do not trigger the activity handler despite the user being engaged (e.g. while watching a video).

You can trigger the activity handler yourself with:

window.snowplow_name_here('updatePageActivity'<span class="p">);

This use case and the accompanying implementation was contributed by Dean Collins, many thanks Dean!

A few improvements have also been made “under the hood” to activity tracking in general.

Activity tracking is now disabled if you don’t supply integers to enableActivityTracking. This is a safety feature, as corrupt non-integer arguments could cause a relentless loop of back-to-back page pings (see issue #572 for more information).

We are also now keeping track of setInterval calls and clearing them as needed in order to avoid having multiple setInterval running at the same time (issue #571).

7. Upgrading

The tracker is available to use here:

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

There are no breaking API changes introduced with this release, but the following options in the configuration argmap have been deprecated and will fire warnings:

• useLocalStorage
• useCookies

Please migrate these to the new stateStorageStrategy parameter as detailed above.

If you enable the OptimizelyX context, you will need to deploy the following table to your Redshift cluster: com.optimizely.optimizelyx/summary_1.sql.

If you enable the Parrable context, you will also need to update the configuration of your Snowplow pipeline to make best use of this. A tutorial on doing this will follow soon.

8. Documentation and help

Check out the JavaScript Tracker’s documentation:

• The setup guide
• The full API documentation

The v2.8.0 release page on GitHub has the full list of changes made in this version.

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