1. Home
  2. Docs
  3. Designing tracking
  4. Predefined vs custom entities

Predefined vs custom entities

Predefined contexts

Predefined contexts are Snowplow authored web contexts and are available with the JavaScript tracker. They are enabled at the tracker initialization step and thus the associated data will be added automatically to any Snowplow event fired on the page.

snowplow_name_here("newTracker", "cf", "d3rkrsqld9gmqf.cloudfront.net", { appId: "cfe23a" }, contexts: { webPage: true, performanceTiming: true, gaCookies: true, geolocation: false } });
Code language: CSS (css)

Custom contexts

Custom contexts let you add additional information about the circumstances surrounding an event by attaching context through entities represented with a self-describing JSON.

The contexts argument to any method is always optional. If set, it must be a self-describing JSON including at least one name: property pair in JSON provided as a value to data property of the self-describing JSON, where data is the name for an individual context entry.

It generally looks like the one below:

{ "schema": "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0", "data": { "bannerId": "4732ce23d345" } }
Code language: JSON / JSON with Comments (json)

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

If you want to create your own custom context, you must create a data structure for it. Since more than one can be attached to an event, the context argument (if it is provided at all) should be a non-empty array of self-describing JSONs.

Important: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

Here are two examples of custom context JSONs. One describes a page, and the other describes a user on that page.

{ schema: "iglu:com.example_company/page/jsonschema/1-2-1", data: { pageType: 'test', lastUpdated: new Date(2016,3,10) } }
Code language: CSS (css)
{ schema: "iglu:com.example_company/user/jsonschema/2-0-0", data: { userType: 'tester', } }
Code language: CSS (css)

Below is a JavaScript tracker example how the above custom contexts could be attached to a page view event:

window.snowplow_name_here( 'trackPageView', // Snowplow authored "page view" event null, // no custom title [ // array of custom contexts { schema: "iglu:com.example_company/page/jsonschema/1-2-1", data: { pageType: 'test', lastUpdated: new Date(2016,3,10) } }, { schema: "iglu:com.example_company/user/jsonschema/2-0-0", data: { userType: 'tester', } } ] );
Code language: JavaScript (javascript)

In this case an empty string has been provided to the optional customTitle argument in order to reach the context argument, which has to be the last argument of the functions.

If you’d like to learn more about Snowplow Insights you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.