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. We are constantly growing the range of functions available in order to capture that data more richly.

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

FunctionDescription
trackScreenView()Track the user viewing a screen within the application
trackPageView()Track and record views of web pages.
trackEcommerceTransactionWithItems()Track an ecommerce transaction with items
trackStructEvent()Track a Snowplow custom structured event
trackUnstructEvent()Track a Snowplow custom unstructured event

Details of other tracking methods are available in the documentation for the tracker core.

Common

All events are tracked with specific methods on the tracker instance, of the form trackXXX(), where XXX is the name of the event to track.

Optional arguments

Each tracker method has both default and optional arguments. If you don't want to provide a value for an optional argument, just 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.trackPageView('http://www.example.com', null, 'http://www.referer.com');

Custom contexts

In short, custom contexts let you add additional information about the circumstances surrounding an event in the form of a JavaScript dictionary object. Each tracking method accepts an additional optional contexts parameter after all the parameters specific to that method:

t.trackPageView('myUrl', 'myPage', 'myReferrer', myCustomContexts);

The context argument should consist of an array of one or more dictionaries. Each dictionary should be a self-describing JSON following the same pattern as an unstructured 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.trackPageView("http://www.films.com", "Homepage", null, [{
"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...() method 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. We can explicitly supply nulls for the intervening arguments which are empty:

t.trackStructEvent("game action", "save", null, null, null, 1368725287000);

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

Track screen views with trackScreenView()

Use trackScreenView() to track 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
contextCustom contextNoArray
tstampWhen the screen was viewedNoPositive integer

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

Example:

t.trackScreenView("HUD > Save Game", "screen23", null, 1368725287000);

Track pageviews with trackPageView()

Use trackPageView() 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
contextCustom contextNoArray
tstampWhen the screen was viewedNoPositive integer

Example:

t.trackPageView("www.example.com", "example", "www.referrer.com");

Track ecommerce transactions with trackEcommerceTransactionWithItems()

Use trackEcommerceTransactionWithItems() to track an ecommerce transaction on the transaction level. Arguments:

ArgumentDescriptionRequired?Type
orderIdID of the eCommerce transactionYesNon-empty string
affiliationTransaction affiliationNoString
totalValueTotal transaction valueYesNumber
taxValueTransaction tax valueNoNumber
shippingDelivery cost chargedNoNumber
cityDelivery address cityNoString
stateDelivery address stateNoString
countryDelivery address countryNoString
currencyCurrencyNoString
itemsArray of items in the transactionNoArray
contextCustom contextNoArray
tstampWhen the transaction event occurredNoPositive integer

The items argument is an array of dictionaries. Each dictionary represents one item in the transaction. These are the keys which may appear in the dictionary:

FieldDescriptionRequired?Type
"sku"Item SKUYesNon-empty string
"price"Item priceYesNumber
"quantity"Item quantityYesInt
"name"Item nameNoString
"category"Item categoryNoString
"context"Custom context for the eventNoArray

Example:

t.trackEcommerceTransaction("order-456", null, 142, 20, 12.99, "London", null, "United Kingdom", [{
"sku": "pbz0026",
"price": 20,
"quantity": 1
},
{
"sku": "pbz0038",
"price": 15,
"quantity": 1
}]);

Track structured events with trackStructEvent()

Use trackStructEvent() 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
contextCustom context for the eventNoArray
tstampWhen the structured event occurredNoPositive integer

Example:

t.trackStructEvent("shop", "add-to-basket", null, "pcs", 2);

Track unstructured events with trackUnstructEvent()

Use trackUnstructEvent() 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
propertiesThe properties of the eventYesJSON
contextCustom context for the eventNoArray
tstampWhen the unstructured event occurredNoPositive integer

Example:

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

The properties argument must be a dictionary with two fields: schema and datadata is a flat dictionary containing the properties of the unstructured event. schema identifies the JSON schema against which data should be validated.

Was this page helpful?