Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. JavaScript Trackers (Web and Node.js)
  6. Node.js Tracker
  7. Node.js Tracker v3
  8. Tracking Events

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

Details of other event building methods are available in the API Documentation.

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' });
Code language: CSS (css)

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 ]);
Code language: CSS (css)

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" } }
Code language: JSON / JSON with Comments (json)

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" } }]);
Code language: JavaScript (javascript)

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);
Code language: CSS (css)

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" }));
Code language: CSS (css)

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" }));
Code language: CSS (css)

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(buildUnstructEvent({ event: { schema: "iglu:com.example_company/save-game/jsonschema/1-0-2", data: { save_id: "4321", level: 23, difficultyLevel: "HARD", dl_content: true } } }));
Code language: CSS (css)

The event property must be an object with two fields: schema and datadata 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 }));
Code language: CSS (css)

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