WARNING: This blog contains outdated information. To review the current approach, please, refer to our wiki post Custom contexts. —
track...() methods to support a new argument for setting custom JSON contexts.
In our earlier blog post we introduced the idea of custom contexts only very briefly. In this blog post, we will take a detailed look at Snowplow’s custom contexts functionality, so you can understand how best to attach custom contexts to your existing Snowplow events.
In the rest of this post we will cover:
Let’s get started after the jump.
You can add custom contexts to any of the existing
track...() methods, and in the case of our transaction tracking, with the two
For completeness, here is the full list of updated tracking methods. Note that
contexts is always the last argument:
A few notes on this:
- If you set the
contextsargument on a
trackPageView, the same context will be attached to all page pings too (assuming you have
- Remember that transactions and their child items are processed as separate Snowplow events. Duplicate your transaction
contextsargument into your items’
contextsargument if you need the transaction context available to the transaction item events
- If you want to add custom context but don’t want to set all the prior arguments, just pad out your function call with empty arguments:
contexts argument to any
add...() method is always optional. If set, it must be a JSON taking the form:
contexts argument is set, it must be a JSON including at least one name: property pair, where:
- The name is the name for an individual context entry
- The property is a JSON holding name: property pairs for this context entry
A few dos and don’ts for context names:
- Do name each context entry however you like
- Do use a context name to identify a set of associated data points which make sense to your business
- Do use the same contexts across multiple different events and event types
- Don’t use multiple different context names to refer to the same set of data points
A few dos and don’ts for the JSONs inside each context entry JSONs:
- Do use any of the data types supported by custom unstructured events
- Do use Snowplow datatype suffixes if the data type would otherwise be unclear
- Don’t nest properties – as with custom unstructured events, the structure must be flat
A detailed example should make custom contexts a little more real.
Let’s take a retailer and Snowplow user who sells movie memorabilia online, particularly movie posters. For every movie poster, our retailer cares about the name of the movie, the country which printed the movie poster and the year the poster was printed. She has also done some work understanding her customer base, and can assign all of her visitors a propensity-to-buy score and a customer segment as soon as they add something to their basket.
Definition of custom contexts
Based on the above, our retailer will define two custom contexts. The first describes a given movie poster:
And then the second context describes the customer:
With her two custom contexts defined, our retailer is now ready to update her Snowplow installation to start collecting this additional data.
Definition of custom contexts
When a visitor arrives on a page advertising a movie poster, our retailer adds this context to the page view event:
When the visitor clicks the add to basket button on this poster, the website fires a custom unstructured event to track the add to basket. This time we send the “customer” context as well as the “movie_poster” context:
The visitor seems to be having doubts – they head to the contact page and fill out a form. This time we still track the “customer” context (with a reduced propensity-to-buy score), but it doesn’t make sense to record this event against any given “movie_poster”, so we don’t include that context:
And that completes our example. By defining and implementing these two custom contexts, our retailer has promoted some of her most business-critical data points to the level of first class entities in Snowplow.
This additional context has made standard Snowplow events such as page views much more valuable to her, and should later make it easy to analyze these business-critical data points across multiple event types.
As always, if you do run into any issues or don’t understand any of the above guide, please do get in touch with us via the usual channels.
If you have any ideas or feedback for Snowplow’s evolving approach to custom contexts, do please share them, either in the comments below or through the usual channels. And please keep an eye on our Roadmap wiki page to see how Snowplow’s support for custom contexts evolves!