Skip to main content

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:

FunctionDescription
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:

ArgumentDescriptionRequired?Type
nameHuman-readable name for this screenNoNon-empty string
idUnique identifier for this screenNoString

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:

ArgumentDescriptionRequired?Type
pageUrlThe URL of the pageYesNon-empty string
pageTitleThe title of the pageNoString
referrerThe address which linked to the pageNoString

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:

ArgumentDescriptionRequired?Type
eventThe self describing event definitionYesJSON

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):

ArgumentDescriptionRequired?Type
categoryThe grouping of structured events which this action belongs toYesNon-empty string
actionDefines the type of user interaction which this event involvesYesNon-empty string
labelA string to provide additional dimensions to the event dataNoString
propertyA string describing the object or the action performed on itNoString
valueA value to provide numerical data about the eventNoNumber

Example:

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