Node.js Tracker - OXYGEN-MARKET/oxygen-market.github.io GitHub Wiki

HOME > SNOWPLOW TECHNICAL DOCUMENTATION > Trackers > Node.js tracker

*This page refers to version 0.3.0 of the Snowplow Node.js Tracker. Documentation for earlier versions is available:

Version 0.1.0
Version 0.2.0

• 1 Overview
• 2 Initialization
• 3 Configuration
  • 3.1 setPlatform()
  • 3.2 setUserId()
  • 3.3 setScreenResolution()
  • 3.4 setViewport()
  • 3.5 setColorDepth()
  • 3.6 setTimezone()
  • 3.7 setLang()
• 4 Tracking specific events
  • 4.1 Common
    • 4.1.1 Optional arguments
    • 4.1.2 Custom contexts
    • 4.1.3 Timestamps
  • 4.2 trackScreenView()
  • 4.3 trackPageView()
  • 4.4 trackEcommerceTransaction()
  • 4.5 trackStructEvent()
  • 4.6 trackUnstructEvent()

The Snowplow Node.js Tracker allows you to track Snowplow events from your Node.js apps.

The tracker should be straightforward to use if you are comfortable with JavaScript development; any prior experience with other Snowplow trackers, Google Analytics or Mixpanel (which have similar APIs to Snowplow) is helpful but not necessary.

Assuming you have completed the Node.js Tracker Setup for your project, you are now ready to initialize the Tracker.

Require the Node.js Tracker module into your code like so:

var snowplow = require('snowplow-tracker');
var emitter = snowplow.emitter;
var tracker = snowplow.tracker;

First, initialize an emitter instance. This object will be responsible for how and when events are sent to Snowplow.

var e = emitter(
  'myscalastreamcollector.net', // Collector endpoint
  'http', // Optionally specify a method - http is the default
  8080, // Optionally specify a port
  'POST', // Method - defaults to GET
  5, // Only send events once n are buffered. Defaults to 1 for GET requests and 10 for POST requests.
  function (error, body, response) { // Callback called for each request
    if (error) {
      console.log("Request to Scala Stream Collector failed!");
    }
  },
  { maxSockets: 6 } // Node.js agentOptions object to tune performance
);

Note that last emitter's argument agentOptions is default configuration object for Node.js HTTP module. It required to constrain maxSockets for bulk loads, which otherwise can lead to event loss.

Initialise a tracker instance like this:

var t = tracker([e], 'myTracker', 'myApp', false);

The tracker function takes four parameters:

• An array of emitters to which the tracker will hand Snowplow events
• An optional tracker namespace which will be attached to all events which the tracker fires, allowing you to identify their origin
• The appId, or application ID
• encodeBase64, which determines whether unstructured events and custom contexts will be base 64 encoded (by default they are).

Back to top

You may have additional information about your application"s environment, current user and so on, which you want to send to Snowplow with each event.

The tracker instance has a set of set...() methods to attach extra data to all tracked events:

• setPlatform()
• setUserId()
• setScreenResolution()
• setViewport
• setColorDepth()
• setTimezone()
• setLang()

We will discuss each of these in turn below:

You can set the platform:

t.setPlatform( "{{PLATFORM}}" );

Example:

t.setPlatform("mob");

If the platform is not set manually, it defaults to 'srv' (for server).

For a full list of supported platforms, please see the Snowplow Tracker Protocol.

Back to top

You can set the user ID to any string:

t.setUserId( "{{USER ID}}" );

Example:

t.setUserId("alexd");

Back to top

If your code has access to the device's screen resolution, then you can pass this in to Snowplow too:

t.setScreenResolution( {{WIDTH}}, {{HEIGHT}} );

Both numbers should be positive integers; note the order is width followed by height. Example:

t.setScreenResolution(1366, 768);

Back to top

If your code has access to the device's screen resolution, then you can pass this in to Snowplow too:

t.setViewport( {{WIDTH}}, {{HEIGHT}} );

Both numbers should be positive integers; note the order is width followed by height. Example:

t.setViewport(300, 200);

Back to top

If your code has access to the bit depth of the device's color palette for displaying images, then you can pass this in to Snowplow too:

t.setColorDepth( {{BITS PER PIXEL}} );

The number should be a positive integer, in bits per pixel. Example:

t.setColorDepth(32);

Back to top

This method lets you pass a user's language in to Snowplow:

t.setTimezone( {{TIMEZONE}} );

Example:

t.setTimezone('Europe/London');

Back to top

This method lets you pass a user's language in to Snowplow:

t.setLang( {{LANGUAGE}} );

The number should be a positive integer, in bits per pixel. Example:

t.setLang('en');

Back to top

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:

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

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.

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:

js t.trackPageView('http://www.example.com', null, 'http://www.referer.com');

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.

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().

Back to top

Use trackScreenView() to track a user viewing a screen (or equivalent) within your app. Arguments are:

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

Back to top

Use trackPageView() to track a user viewing a page within your app. Arguments are:

Example:

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

Back to top

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

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:

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
}]);

Back to top

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

Example:

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

Back to top

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:

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.

For more on JSON schema, see the blog post.

Back to top