Snowplow JavaScript Tracker 0.13.0 released with custom contexts

We’re pleased to announce the immediate availability of the Snowplow JavaScript Tracker version 0.13.0. This is the first new release of the Snowplow JavaScript Tracker since separating it from the main Snowplow repository last year.

The primary objective of this release was to introduce some key new tracking capabilities, in preparation for adding these to our Enrichment process. Secondarily, we also wanted to perform some outstanding housekeeping and tidy-up of the newly-independent repository.

In the rest of this post, then, we will cover:

1. New feature: custom contexts
2. New feature: transaction currencies
3. New feature: specifying the tracking platform
4. Project tidy-up
5. Upgrading
6. Getting help

The most exciting new feature is the addition of custom contexts to all of our track...() methods for event tracking.

Please note that this release only adds custom contexts to the JavaScript Tracker. Adding custom contexts to our Enrichment process and Storage targets is on the roadmap – but rest assured we are working on it!

Context is what describes the circumstances surrounding an individual event – for example, when the event happened, where it happened, or how it happened. For the original blog post where we introduced our ideas around event context, see Towards universal event analytics – building an event grammar.

Our JavaScript Tracker already captures lots of standard web context by default: event time, user timezone, monitor color depth, browser features etc. This new feature will allow you to define and track your own custom contexts – ones which make sense to your business.

Think “custom variables” but much more powerful and flexible!

Custom contexts are great for a couple of use cases:

1. Whenever you want to augment a standard Snowplow event type with some additional data
2. If your business has a set of crosscutting data points/models which you want to record against multiple event types

You can attach custom contexts to any Snowplow event type – even custom unstructured events.

To support custom contexts, we have added a new argument, called contexts, onto the end of each track...() and add...() method. For example, here is the new signature for tracking a page view:

function trackPageView(customTitle, contexts)

The contexts argument is always optional on any event call. If set, it must be a JSON taking the form:

{ "context1_name": { ... }, "context2_name": { ... }, ... }

The format of the JSON properties for each individual context follows the exact same rules as our unstructured events’ JSON properties.

If you are interested in finding out more about custom contexts, we have written a follow-up blog post – please read this post for more information.

1.4 Roadmap

We are well aware that this release is only the start of adding custom contexts to Snowplow. We are working on a common solution to Enriching and Storing both unstructured events and custom contexts.

Please keep an eye on our Roadmap wiki page to see how Snowplow’s support for custom contexts (and unstructured events) evolves.

We have updated our ecommerce tracking methods to add support for setting the currency which the transaction took place in.

The new currency argument is the penultimate argument (the last before context, see above) to both the addTrans() and addItem() methods. Use it like so:

_snaq.push(['addTrans', '1234', // order ID - required 'Acme Clothing', // affiliation or store name '11.99', // total - required '1.29', // tax '5', // shipping 'San Jose', // city 'California', // state or province 'USA', // country 'USD' // currency <span class="p">]); _snaq.push(['addItem', '1234', // order ID - required 'DD44', // SKU/code - required 'T-Shirt
', // product name 'Green Medium', // category or variation '11.99', // unit price - required '1', // quantity - required 'USD' // currency <span class="p">]);

Please make sure to pass in the valid ISO 4217 code for your currency. This will ensure that your ecommerce transactions are compatible with the currency conversion enrichment we are currently developing (see this blog post for details).

Don’t forget to set the currency on both the parent transaction and its child items.

Many thanks to community member Ryan Sorensen for contributing the new setPlatform() method.

This allows you to override the default tracking platform (“web”) with another of the platform values supported in the Snowplow Tracker Protocol. For example, to set the platform to “mob” for mobile:

_snaq.push(['setPlatform', 'mob'<span class="p">]);

Thanks for your contribution Ryan!

We have taken advantage of the move to a separate repository to perform some much needed tidy-up of the tracker codebase:

• Added a complete historic CHANGELOG
• Back-filled git tags for all of the tracker’s releases
• Restructured the folders
• Added a package.json
• Added a node.js-friendly .gitignore
• Added some useful helper functions

As well as tidying up the repository, these updates should lay the groundwork for us replacing our custom snowpak.sh Bash build script with a Grunt-based build process in the next release.

UPDATED After an important post-release bug fix, the updated minified tracker is available here:

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

Please note that as of this release, we are moving the Snowplow JavaScript Tracker to true semantic versioning. This means that going forwards we are also making this tracker available as:

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

where 0 is the semantic MAJOR version. If you prefer, you can use this URI path and then get new features and bug fixes automatically as we roll-out MINOR and PATCH updates to the tracker. Any breaking changes will mean a new MAJOR version, which will be hosted on /1/sp.js, i.e. it won’t break your existing installation.

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

As always, if you run into any issues or don’t understand any of the above changes, please raise an issue or get in touch with us via the usual channels.