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 a custom event (self-describing)​

You may wish to track events in your app 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 track a self-describing event, you make use of the trackSelfDescribingEvent method:

snowplow('trackSelfDescribingEvent', {{SELF-DESCRIBING EVENT JSON}});

For example:

snowplow('trackSelfDescribingEvent', {
  event: {
    schema: 'iglu:com.acme_company/viewed_product/jsonschema/1-0-0',
    data: {
        productId: 'ASO01043',
        category: 'Dresses',
        brand: 'ACME',
        returning: true,
        price: 49.95,
        sizes: ['xs', 's', 'l', 'xl', 'xxl'],
        availableSince: new Date(2013,3,7)
    }
  }
});

The second argument or event property, depending on tracker, is a self-describing JSON. It has two fields:

  • A data field, containing the properties of the event
  • A schema field, containing the location of the JSON schema against which the data field should be validated.

Like all trackX methods, trackSelfDescribingEvent can also be passed an array of custom context entities as an additional parameter. See the next section for more information.

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.

tip

Custom context entities can be added as an extra argument to any of Snowplow's trackX() methods, e.g. trackPageView or trackLinkClick.

note

Tracker methods available through plugins do not necessarily support adding custom entities. For those please refer to the corresponding plugin documentation for details.

Here are two examples of schema for custom entities. One describes a screen:

{
    "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
    "self": {
        "vendor": "com.example",
        "name": "screen",
        "format": "jsonschema",
        "version": "1-0-1"
    },
    "type": "object",
    "properties": {
        "screenType": {
            "type": "string"
        },
        "lastUpdated": {
            "type": "string"
        }
    }
    "required": ["screenType", "lastUpdated"],
    "additionalProperties": false
}

and the other describes a user on that screen:

{
    "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
    "self": {
        "vendor": "com.example",
        "name": "user",
        "format": "jsonschema",
        "version": "2-0-0"
    },
    "type": "object",
    "properties": {
        "user": {
            "type": "string"
        }
    }
    "required": ["user"],
    "additionalProperties": false
}

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

Tracking a page view with both of these example entities attached:

snowplow('trackPageView', {
  context: [{
    schema: "iglu:com.example_company/page/jsonschema/1-2-1",
    data: {
      pageType: 'test',
      lastUpdated: new Date(2021,04,01)
    }
  },
  {
    schema: "iglu:com.example_company/user/jsonschema/2-0-0",
    data: {
      userType: 'tester'
    }
  }]
});

Tracking a self describing event with both of these context entities attached:

snowplow('trackSelfDescribingEvent', {
  event: {
    schema: 'iglu:com.example_company/product_viewed/jsonschema/1-0-1',
    data: {
      productId: '12345',
      price: 10.99
    }
  },
  context: [{
    schema: 'iglu:com.example_company/page/jsonschema/1-2-1',
    data: {
      pageType: 'test',
      lastUpdated: new Date(2021,04,01)
    }
  },
  {
    schema: "iglu:com.example_company/user/jsonschema/2-0-0",
    data: {
      userType: 'tester'
    }
  }]
});

For more information on custom contexts, see here.