Snowplow JavaScript Tracker 2.10.0 released with global contexts

Share

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:

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:

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:

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:

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:

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:

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:

Global contexts provide the ability for end users to:

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.

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:

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 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.

Learn more about our unique approach to data delivery with a Snowplow demo.

Share

Related articles