In a time where tracking everything that moves seems to be the norm, context is often overlooked.
Context provides information describing the circumstances that surround an event, which is critical to comprehend events fully, and this applies to real life situations too.
It's a goal! Who scored? Which teams were playing?
What are Snowplow Analytics Custom Contexts?
In Google Analytics and Adobe Analytics, the way to add additional context to an event is to map an event property to a custom dimension or traffic variable, usually referenced by a number, or letter and number.
The mapping can quickly become confusing with dictionaries and spreadsheets mapping numbers to properties scattered along the available slots. We’ve all been there.
Snowplow custom contexts are similar to what Google custom dimensions and Adobe traffic variables aim to do, but with a significant difference; they are a self-describing JSON.
With Snowplow you can send a custom context as an extra argument for any Snowplow event type.
There are several advantages to this approach:
- You will never run out of space for context
- Schemas are versioned and can expand/contract with business needs
- Schemas are reusable
- Schema variables are easy to read and understand
- The analysis is easier because each schema lives in a dedicated SQL table
Below is an example of a custom context that BestBuy could use to describe a laptop product detail pageview.
If your event doesn't fit the usual category, action, label model, you can create your own event with a self-describing unstructured event.
How to create a Snowplow Analytics Custom Context
Before you start sending custom contexts with events, you have to create a JSON schema, validate it, upload it to Iglu (schema repository in Snowplow), upload the jsonpaths to S3, and create the corresponding SQL tables.
The jsonpaths and SQL table definitions are generated automatically with igluctl, a tool to help you manage the schema registry.
Let's get ready to create our custom context.
A schema registry is a repository for schemas composed of three folders: jsonpaths, schemas, and sql. Don't edit any of the files inside the jsonpaths and sql folders; they will be generated automatically by igluctl from your defined schemas.
Note the schema file name 1-0-0, follows Snowplow SchemaVer which is defined as: MODEL-REVISION-ADDITION:
- MODEL - when you make a breaking schema change which will prevent interaction with any historical data
- REVISION - when you introduce a schema change which may prevent interaction with some historical data
- ADDITION - when you make a schema change that is compatible with all historical data
Open 1-0-0, the example_event schema file.
Edit the sample schema file with fields that help describe your event.
Validating Your JSON Schema
If an event has an invalid custom context, Snowplow will not know how to process the data, and the event will be sent to the bad rows folder.
As a side note, Snowplow stores both unprocessed and processed data. Processed data goes into one of two folders, good or bad, so you can reprocess data if needed.
You can validate your schemas using igluctl.
If the schema validated successfully, you will see "TOTAL: 1 Schemas were successfully validated."
Congratulations you've created your first custom context!.
Custom Contexts are one of the most powerful features in Snowplow Analytics, they provide you with the freedom to add context to your events, in any platform, and if the events don't fit your business model, you can always create your own.