Skip to main content

Custom event tracking

Self-describing (self-referential) JSON schemas are at the core of Snowplow tracking. Read more about them here. They allow you to track completely customised data, and are also used internally throughout Snowplow pipelines.

In all our trackers, self-describing JSON are used in two places. One is in the SelfDescribing event type that wraps custom self-describing JSONs for sending. The second use is to attach entities to any tracked event. The entities can describe the context in which the event happen or provide extra information to better describe the event.

Tracking self-describing events​

You may wish to track events which are not directly supported by Snowplow and which structured event tracking does not adequately capture. Your event may have more than the five fields offered by Structured events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a data structure based on JSON Schemas and can have arbitrarily many fields.

To define your own custom event, you will need to create a corresponding schema. Snowplow uses the schema to validate that the JSON containing the event properties is well-formed.

A Self Describing event is a self-describing JSON.

Required properties

  • schema: (string) – A valid Iglu schema path. This must point to the location of the custom event’s schema, of the format: iglu:{vendor}/{name}/{format}/{version}.
  • data: (object) – The custom data for your event. This data must conform to the schema specified in the schema argument, or the event will fail validation and become a failed event.

To track a custom self-describing event, use the trackSelfDescribingEvent method of the tracker.

For example, to track a link-click event, which is one whose schema is already published in Iglu Central:

tracker.trackSelfDescribingEvent({
    schema: 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
    data: {targetUrl: 'http://a-target-url.com'}
});

Tracking a custom entity​

Custom context can be used to augment any standard Snowplow event type, including self-describing events, with additional data. We refer to this custom context as entities.

The context is an array of entities. More than one entity (of either different or the same type) can be attached to an event. The context argument (if it is provided at all) should be a non-empty array.

As with self-describing events, if you want to create your own custom context, you will need to create a corresponding schema. Snowplow uses the schema to validate that the JSON containing the context properties is well-formed.

Custom contexts can be optionally added as an extra argument to any of the Tracker’s track..() methods.

Note: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array. Also an empty array is acceptable, which will attach no entities to the event.

For example, a custom context to describe a screen could be:

const myScreenContext: EventContext = {
    schema: 'iglu:com.example/screen/jsonschema/1-2-1',
    data: {
        screenType: 'test',
        lastUpdated: '2021-06-11'
    }
};

Another example custom context to describe a user on a screen could be:

const myUserEntity: EventContext = {
    schema: 'iglu:com.example/user/jsonschema/2-0-0',
    data: {
        userType: 'tester'
    }
};

Then, to track, for example, a screenViewEvent with both of these contexts attached:

tracker.trackScreenViewEvent(
   { name: 'myScreenName' },
   [ myScreenContext, myUserEntity ]
);

It is also possible to add custom contexts globally, so that they are applied to all events within an application. For more information, see the Global Contexts section below.

Global Contexts​

As mentioned in the GCConfiguration section, you can set global contexts when initializing the tracker.

However, as the user journey evolves, you may need to remove or add global contexts at runtime.

Removing Global Contexts​

A set of global contexts is identified by its tag, which was set when the global contexts was added, either as part of tracker initial configuration or manually (see below).

To remove the global contexts associated with a tag, you can use the removeGlobalContexts tracker method, which takes as argument the tag. For example:

tracker.removeGlobalContexts('my-old-tag');

Adding Global Contexts​

Similarly, you can add global contexts at runtime using the addGlobalContexts tracker method. This method takes as argument the GlobalContext to add.

For example:

tracker.addGlobalContexts({
    tag: 'my-new-tag',
    globalContexts: [
        {
            schema: 'iglu:com.snowplowanalytics.snowplow/ad_impression/jsonschema/1-0-0',
            data: {impressionId: 'my-ad-impression-id'},
        },
    ]
});