Tracking Events

Tracking specific events

Snowplow has been built to enable you to track a wide range of events that occur when users interact with your websites and apps.

Tracking methods supported by the Node.js Tracker at a glance:

Function	Description
track()	Tracks an event generated from a build functions
buildScreenView()	Track the user viewing a screen within the application
buildPageView()	Track and record views of web pages.
buildSelfDescribingEvent()	Track a Snowplow custom self describing event
buildStructEvent()	Track a Snowplow custom structured event

Track events with the track() function

All events are tracked through the track() function on the tracker instance. The type of event is determined by one of the event builder functions, which all begin as build*().

Optional arguments

Each build method which is passed to the track() function has both default and optional arguments. If you don't want to provide a value for an optional argument, just ignore it in the object or pass null and it will be ignored. For example, if you want to track a page view event with a referrer but without a title:

t.track(buildPageView({ 
  pageUrl: 'http://www.example.com', 
  referrer: 'http://www.referer.com'
});

Custom contexts

In short, custom contexts let you add additional information about the circumstances surrounding an event. Each call to track() accepts an additional optional context parameter:

t.track(buildPageView({ 
  pageUrl: 'http://www.example.com', 
  referrer: 'http://www.referer.com'
}),
[]); // Array of custom contexts

The context argument should consist of an array of zero or more context objects. Each object should be a self-describing JSON following the same pattern as an self describing event.

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

If a visitor arrives on a page advertising a movie, the context dictionary might look like this:

{
  "schema": "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
  "data": {
    "movie_name": "Solaris",
    "poster_country": "JP"
  }
}

This is how to fire a page view event with the above custom context:

t.track(buildPageView({ 
  pageUrl: 'http://www.example.com', 
  referrer: 'http://www.referer.com'
}), 
[{
  "schema": "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
  "data": {
    "movie_name": "Solaris",
    "poster_country": "JP"
  }
}]);

Note that even though there is only one custom context attached to the event, it still needs to be placed in an array.

Timestamps

Each track() call supports an optional timestamp as its final argument, after the context argument; this allows you to manually override the timestamp attached to this event.

If you do not pass this timestamp in as an argument, then the Tracker will use the current time to be the timestamp for the event.

Here is an example tracking a structured event and supplying the optional timestamp argument:

t.track(buildStructEvent({
  category: "game action", 
  action: "save"
}), [], 1368725287000);

Timestamp is counted in milliseconds since the Unix epoch - the same format as generated by new Date().getTime().

Track screen views with buildScreenView()

Use buildScreenView() to build a user viewing a screen (or equivalent) within your app. Arguments are:

Argument	Description	Required?	Type
name	Human-readable name for this screen	No	Non-empty string
id	Unique identifier for this screen	No	String

name and id are not individually required, but you must provide at least one of them.

Example:

t.track(buildScreenView({
  name: "HUD > Save Game", 
  id: "screen23"
}));

Track pageviews with buildPageView()

Use buildPageView() to track a user viewing a page within your app. Arguments are:

Argument	Description	Required?	Type
pageUrl	The URL of the page	Yes	Non-empty string
pageTitle	The title of the page	No	String
referrer	The address which linked to the page	No	String

Example:

t.track(buildPageView({
  pageUrl: "www.example.com", 
  url: "example",
  referrer: "www.referrer.com"
}));

Track self describing events with buildSelfDescribingEvent()

Use buildSelfDescribingEvent() to track a custom event which consists of a name and an unstructured set of properties. This is useful when you want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow).

The arguments are as follows:

Argument	Description	Required?	Type
event	The self describing event definition	Yes	JSON

Example:

t.track(buildSelfDescribingEvent({
  event: {
    schema: "iglu:com.example_company/save-game/jsonschema/1-0-2",
    data: {
      save_id: "4321",
      level: 23,
      difficultyLevel: "HARD",
      dl_content: true
    }
  }
}));

The event property must be an object with two fields: schema and data. data is an object containing the properties of the self describing event. schema identifies the JSON schema against which data should be validated.

Track structured events with buildStructEvent()

Use buildStructEvent() to track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required):

Argument	Description	Required?	Type
category	The grouping of structured events which this action belongs to	Yes	Non-empty string
action	Defines the type of user interaction which this event involves	Yes	Non-empty string
label	A string to provide additional dimensions to the event data	No	String
property	A string describing the object or the action performed on it	No	String
value	A value to provide numerical data about the event	No	Number

Example:

t.track(buildStructEvent({
  category: "shop", 
  action: "add-to-basket", 
  label: "product", 
  property: "pcs", 
  value: 2
}));