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:
|Tracks an event generated from a build functions|
|Track the user viewing a screen within the application|
|Track and record views of web pages.|
|Track a Snowplow custom self describing event|
|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
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:
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:
[ // Array of custom contexts ]);
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:
This is how to fire a page view event with the above custom context:
Note that even though there is only one custom context attached to the event, it still needs to be placed in an array.
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:
category: "game action",
}), , 1368725287000);
Timestamp is counted in milliseconds since the Unix epoch - the same format as generated by
Track screen views with
buildScreenView() to build a user viewing a screen (or equivalent) within your app. Arguments are:
|Human-readable name for this screen||No||Non-empty string|
|Unique identifier for this screen||No||String|
id are not individually required, but you must provide at least one of them.
name: "HUD > Save Game",
Track pageviews with
buildPageView() to track a user viewing a page within your app. Arguments are:
|The URL of the page||Yes||Non-empty string|
|The title of the page||No||String|
|The address which linked to the page||No||String|
Track self describing events with
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:
|The self describing event definition||Yes||JSON|
event property must be an object with two fields:
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() 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):
|The grouping of structured events which this ||Yes||Non-empty string|
|Defines the type of user interaction which this event involves||Yes||Non-empty string|
|A string to provide additional dimensions to the event data||No||String|
|A string describing the object or the action performed on it||No||String|
|A value to provide numerical data about the event||No||Number|