Snowplow JavaScript Tracker 2.10.0 released with global contexts

We are pleased to announce a new release of the Snowplow JavaScript Tracker. Version 2.10.0 introduces global contexts, a set of powerful tools for working with contexts. Contexts are one of the most important features in Snowplow: they enable companies running Snowplow to track rich, highly structured data that is easy to work with. In this post we’ll quickly review what contexts are, before explaining why the “global contexts” functionality released is so powerful for companies that want to collect rich event-level data.

Also included in this release are:

• More context features for link and form tracking,
• A new option to prevent exceptions from surfacing, and
• Many other under-the-hood improvements, updates, and bugfixes.

Read on below the fold for:

1. Global contexts
2. Error-handling
3. Dynamic contexts for link and form tracking
4. Updates and bug fixes
5. Upgrading
6. Documentation and help

1. Global contexts

This release introduces a set of powerful tracker features for controlling when contexts are added to events. Before we go in and describe those features it is worth having a quick recap on what contexts are and why they are so important.

1.1 A quick recap on contexts

1.1.1 What are contexts?

Snowplow is a data collection platform for recording events. Events can be very varied. To give just a handful of examples:

• Job seeker submits application for job
• Shopper adds item to basket
• Visitor shares video on Twitter

Each of these events involves multiple different contexts or entities, where each context or entity can be described by multiple data points. To take the first example: “Job seeker submits application for job”, this might involve the following contexts or entities:

• The job seeker
• The job applied for
• The application submitted
• The web page the application was submitted on
• The device that the user was on when he/ she submitted the application

Each of these contexts or entities might be described by multiple data points. For example, we might want to know the following about the job seeker:

• ID
• Gender
• Data of birth
• Qualification level
• Any specialisms
• Salary expectations
• Location

So when you record an event in Snowplow, you typically want to record data about all the entities or contexts involved in the event, and for each context, capture as much rich data as possible. Contexts make this possible: in the above example “job seeker submits application for job” you might track the following:

window.snowplow("trackSelfDescribingEvent", { "schema": "iglu:com.jobsite/submit_application/jsonschema/1-0-0", "data": { "applicationId": "abc123" }, [{ "schema": "iglu:com.jobsite/job_seeker/jsonschema/1-0-0", "data": { "id": "jobseeker1", "gender": "female", "dateOfBirth": "2003-01-06", "qualification": "Masters", "specialisms": ["marketing", "digital"], "location": "London, UK" }, }, { "schema": "iglu:com.jobsite/job/jsonschema/1-0-0", "data": { "id": "job1", "title": "PPC Manager", "salary": 25000, "location": "London, UK", "employer": "The Big Cola Company" } },{ "schema": "iglu:com.jobsite/application/jsonschema/1-0-0", "data": { "cv_uploaded": true, "cv_location": "https://uploads.jobs
ite.com/cvs/cv123" } }] })

It is possible for the company recording the event to send as many self-describing contexts with each event that describe each of the contexts or entities involved in that event. (In the above example three contexts are sent with the event.) With each context it is possible to send as many data points as you wish. Typically, contexts will be common across multiple different event types. So the self-describing JSON describing the job seeker would be sent with every event performed by that job seeker, including:

• Searching for jobs
• Viewing particular jobs
• Favoriting particular jobs
• Putting together an application
• Submitting that application to a particular job
• Any downstream events associated with interacting with the recruiter during the application process

1.1.2 Predefined contexts

As the above example shows, with Snowplow it is possible to send as many contexts as you want with each event, with as many data points as you wish per context. In addition, Snowplow Trackers support sending “pre-defined” contexts with every event sent. For example, the Javascript Tracker supports automatically sending the following contexts:

• A web page context, that identifies the web page on which an event occurs. This is useful if someone has got multiple tabs on a web site open at the same time and is flicking between them, so you can identify on which browser tab each event occurs in, and understand how the visitor is using each tab
• A performance timing context, with data about how fast the web page loads
• A session context, that identifies which session an event occurred in, and what the cookie ID of the user is
• A GA Cookies context, that records the values in any Google Analytics cookies that have been set from the same domain
• A set of Optimizely contexts, that describe any experiments that are currently being run and if so, which

These are enabled when initializing the tracker. Once enabled, they are sent with every single event recorded.

1.2 Introducing Global Contexts

Up until now, Snowplow has offered users:

• The ability to send as many contexts as desired with each individual event
• The ability to automatically send some pre defined contexts with every single event

Global contexts provide the ability for end users to:

• Define their own contexts once (e.g. on tracker initialization) and then have this context sent with every single event subsequently recorded on the page. This saves developers having to manually build and send the context array with every single event fired.
• Define rules so that particular contexts are only sent with particular event types. This can be done in a number of ways:
  • based on the event schema URI
  • based on a user-supplied callback function that optionally accepts an argument containing the schema URI, event payload and event type

This puts an enormous amount of power in the hands of developers implementing Snowplow, to track a lot more rich data, conveniently, with each event.

1.3 Using the new Global context functionality

The following methods are added to the tracker:

1. addGlobalContexts
2. removeGlobalContexts
3. clearGlobalContexts

For a taste of the functionality, here we can define that a context is only sent for events with the schema vendor com.acme. Notice that addGlobalContexts must be supplied with an array of global contexts.

let user_context = { schema: 'iglu:com.acme/user_context/jsonschema/1-0-0' data: { userid: 1234, name: 'john doe' } <span class="p">}; // if a global context has a conditional component (in this case, a schema rule set) // our global context must be supplied as an array, where the first element is // the conditional part and the context is the second element let global_context = [ {accept: 'iglu:com.acme/*/jsonschema/*'}, user_context ] window.snowplow('addGlobalContexts', [global_context<span class="p">]);

Full documentation can be found here.

2. Error-handling

With this version, exceptions that are caused by calling tracker methods will not surface.

You can disable this by setting the following value:

window.snowplow('setDebug', true<span class="p">);

Full documentation can be found here.

3. Dynamic contexts for link and form tracking

The feature allows dynamic contexts to be passed in the context argument seen in the examples methods below for enabling link and form tracking. For form change events, context generators are passed (elt, type, value), and form submission events are passed (elt, innerEle
ments). Link tracking events pass the source element to the context generator.

window.snowplow('enableLinkClickTracking', criterion, pseudoClicks, trackContent, context<span class="p">); window.snowplow('enableFormTracking', config, context<span class="p">);

Full documentation can be found here for link tracking and here for form tracking.

Many thanks to Bernardo Srulzon for contributing this feature!

4. Beacon API for event sending

This release allows you to send events to a collector using the Beacon API, in addition to the traditional GET and POST options.

The Beacon API is an interface implemented by browsers that allows the tracker to schedule asynchronous, non-blocking requests. This interface is a reliable alternative to synchronous requests made on unload, a method used commonly by analytics and diagnostic code.

This feature can be enabled by setting the argmap value, beacon to true.

More documentation about the Beacon API can be found here.

window.snowplow("newTracker", "cf", "d3rkrsqld9gmqf.cloudfront.net", { ... beacon: true, ... <span class="p">});

Full documentation can be found here.

Many thanks to Adam Nagy for contributing this feature!

4. Updates and bug fixes

Other updates and fixes include:

• Transpile helpers.js and detectors.js (#693)
• Fix default configOptOutCookie value (#672)
• Remove outdated addClickListener method (#667)
• Tracking click events on forms (#579)
• Update tracker script banner (#684)
• Add new local testing workflow (#686)
• Clean up indentation of integration test template (#691)
• Update outdated dependencies (#685)
• Fix typo in sesname variable (#671)
• Add Babel to build process (#665)
• Replace YUI Compressor with UglifyJS (#687)
• Refresh npm authentication token (#688)
• Fix log output for failed integration tests (#689)
• Use modularized imports for lodash (#502)
• Update npm steps in .travis.yml (#690)

Many thanks to Michael Maletich and Sadhasivam for their contributions!

5. Upgrading

The tracker is available to use here:

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

As always, we encourage you to self-host your own copy of the tracker.

There are no breaking API changes introduced with this release.

6. Documentation and help

Check out the JavaScript Tracker’s documentation:

• The setup guide
• The full API documentation

The v2.10.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 our Discourse forums.