Tracking Events

caution

You are reading documentation for an outdated version. Here’s the latest one!

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:

Function	Description
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:

Argument	Description	Required?	Type
name	Human-readable name for this screen	No	Non-empty string
id	Unique identifier for this screen	No	String
context	Custom context	No	Array
tstamp	When the screen was viewed	No	Positive 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:

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
context	Custom context	No	Array
tstamp	When the screen was viewed	No	Positive 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:

Argument	Description	Required?	Type
orderId	ID of the eCommerce transaction	Yes	Non-empty string
affiliation	Transaction affiliation	No	String
totalValue	Total transaction value	Yes	Number
taxValue	Transaction tax value	No	Number
shipping	Delivery cost charged	No	Number
city	Delivery address city	No	String
state	Delivery address state	No	String
country	Delivery address country	No	String
currency	Currency	No	String
items	Array of items in the transaction	No	Array
context	Custom context	No	Array
tstamp	When the transaction event occurred	No	Positive 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:

Field	Description	Required?	Type
"sku"	Item SKU	Yes	Non-empty string
"price"	Item price	Yes	Number
"quantity"	Item quantity	Yes	Int
"name"	Item name	No	String
"category"	Item category	No	String
"context"	Custom context for the event	No	Array

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

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
context	Custom context for the event	No	Array
tstamp	When the structured event occurred	No	Positive 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:

Argument	Description	Required?	Type
properties	The properties of the event	Yes	JSON
context	Custom context for the event	No	Array
tstamp	When the unstructured event occurred	No	Positive 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 data. data is a flat dictionary containing the properties of the unstructured event. schema identifies the JSON schema against which data should be validated.