1. Home
  2. Docs
  3. Designing tracking
  4. Out-of-the-box vs custom events

Out-of-the-box vs custom events

Snowplow authored events

Snowplow supports a large number of events “out of the box”, most of which are fairly standard in a web analytics context.

Examples of events that we support include:

  • Page views
  • Page pings
  • Link clicks
  • Form fill-ins (for the web)
  • Form submissions
  • Transactions

For events that Snowplow natively supports, there is generally a specific API for tracking that event type in Snowplow. For example, if you want to track a page view using the Javascript tracker, you do so with the following Javascript:

Code language: JavaScript (javascript)

Whereas if you were tracking a pageview in an iOS app using the objective-c tracker, you’d do so like this:

[t1 trackPageView:@"www.example.com" title:@"example" referrer:@"www.referrer.com"];
Code language: CSS (css)

In general, each tracker will have a specific API call for tracking any events that have been defined by the Snowplow team, and you should refer to the tracker-specific documentation to make sure that this is set up correctly.

Custom events

If you wish to track an event that Snowplow does not recognise as a first class citizen (i.e. one of the events listed above), then you can track them using the strongly recommended approach of self-describing events or the more generic structured event.

Self-describing events

Self-describing events are customer defined events. A self-describing event consists of two elements:

  • The name of the self-describing event, e.g. “Game saved” or “returned-order”. This is case-sensitive; spaces etc are allowed
  • A set of key: value properties (also known as a hash, associative array or dictionary)

You might recognize what we call self-describing events (custom unstructured events) from other analytics tools including MixPanel, KISSmetrics and Keen.io, where they are the primary trackable event type.

Self-describing events are great:

  • Where you want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow)
  • Where you want to track events which have unpredictable or frequently changing properties

The set of key: value properties in self-describing events is represented with self-describing JSON which can have arbitrarily many fields.

For example, to track a self-describing event with Javascript tracker, you make use of the trackUnstructEvent method with the pattern shown below:

snowplow_name_here('trackSelfDescribingEvent', <<SELF-DESCRIBING EVENT JSON>>);
Code language: JavaScript (javascript)

More specific example using JavaScript tracker:

window.snowplow_name_here('trackUnstructEvent', { schema: 'iglu:com.acme_company/viewed_product/jsonschema/2-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) } });
Code language: JavaScript (javascript)

Note that with self-desribing events, however, the number of key:value pairs can vary and is determined by business model of the entity associated with the event.

Therefore, for Snowplow to be able to validate and extract the data self-describing JSON would have to be sent with the event. By its definition, self-describing JSON includes a reference to JSON schema which has to be in place by the time enrichment process takes place. It allows for maximum customisation of the unstructured events.

Knowing in advance what the expected structure and format of data should be as a necessity to be able to handle events and contexts.

See Structuring your data with schemas.

Structured events

When you track a structured event, you get five parameters:

  • Category: The name for the group of objects you want to track.
  • Action: A string that is used to define the user in action for the category of object.
  • Label: An optional string which identifies the specific object being actioned.
  • Property: An optional string describing the object or the action performed on it.
  • Value: An optional numeric data to quantify or further describe the user action.


We recommend using Self Describing events whenever possible as they give more control and semantic meaning to your data tracking.

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