1. Home
  2. Docs
  3. Designing Your 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.

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 (also called unstructured events) or the more generic custom structured event.

Self-describing events

Self-describing events (also known as custom unstructured 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', <JSON>>);

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) } });

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.

Important

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