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:
- New feature: custom contexts
- New feature: transaction currencies
- New feature: specifying the tracking platform
- Project tidy-up
- Getting help
The most exciting new feature is the addition of custom contexts to all of our
track...() methods for event tracking.
1.1 What are custom contexts?
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.
Think “custom variables” but much more powerful and flexible!
1.2 When to use custom contexts?
Custom contexts are great for a couple of use cases:
- Whenever you want to augment a standard Snowplow event type with some additional data
- 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
add...() method. For example, here is the new signature for tracking a page view:
contexts argument is always optional on any event call. If set, it must be a JSON taking the form:
The format of the JSON properties for each individual context follows the exact same rules as our unstructured events’ JSON properties.
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.
currency argument is the penultimate argument (the last before
context, see above) to both the
addItem() methods. Use it like so:
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
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:
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:
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.