Snowplow Node.js Tracker 0.1.0 released


We are delighted to announce the release of the first version of the Snowplow Node.js Tracker. This is an npm module designed to send Snowplow events to a Snowplow collector from a Node.js environment.

This post will cover installing and setting up the Node.js Tracker and introduce its main features.

  1. Background
  2. How to install the tracker
  3. How to use the tracker
  4. Features
  5. Getting help

1. Background

The Snowplow Node.js Tracker is our first release making use of the new JavaScript Tracker Core module. The JavaScript Tracker Core library is intended to reduce duplication between different JavaScript-based Snowplow trackers, and will soon be integrated into our client-side JavaScript Tracker.

2. How to install the tracker

You will need to have Node.js and npm installed – see this gist for help with this step.

Install the tracker like this:

cd my-project-root npm install snowplow-tracker

You can also of course add the Snowplow Node.js Tracker as a dependency in your own JavaScript apps, node-webkit projects and Node.js servers.

For more information, see the [setup page][setup].

3. How to use the tracker

Require the tracker module like this:

var tracker = require('snowplow-tracker'<span class="p">);

tracker is the function which constructs the tracker instance. This is its signature:

function tracker(endpoint, namespace, appId, encodeBase64<span class="p">);
  • endpoint is the collector to which events will be sent
  • namespace is a name for the tracker instance which will be attached to all events that it sends, making it easier to identify their source
  • appId is the application ID
  • encodeBase64 is whether unstructured events and custom contexts should be base 64 encoded. It defaults to true.

Create a new tracker instance like this:

var t = tracker('', 'tracker2', 'my-app', false<span class="p">);

You can set additional information which will be attached to every event:

t.setUserId('345723-046778-346346'<span class="p">); t.setPlatform('web'<span class="p">); t.setTimezone('Europe/London'<span class="p">); t.setColorDepth(24<span class="p">);

Send some events:

// A page view event t.trackPageView('', 'example page', ''<span class="p">); // An unstructured event t.trackUnstructEvent({ schema: 'iglu:com.acme/product_view/jsonschema/1-0-0', data: { productCategory: 'books', productName: 'Leviathan' } <span class="p">}); // A screen view with a custom context array attached t.trackScreenView('main screen', 'screen-43536ipt', [{ schema: 'iglu:com.acme/test_context/jsonschema/1-0-0', data: { pageType: 'test', userType: 'tester' } }]); // An ecommerce transaction event containing two items t.trackEcommerceTransaction( 'order-7', // order ID null, // affiliate 25, // total value 5, // tax 0, // shipping 'Dover', // city 'Delaware', // state 'US', // country 'USD', // currency [{ sku: '474657', name: 'red hat', quantity: 1', price: '15', category: 'clothing' }, { sku: '474658', name: 'cyan hat', quantity: 2', price: '10', category: 'clothing' }]);

For more information on using the Node.js Tracker, see the wiki page.

4. Features

The Node.js Tracker’s functionality is very similar to that of the Snowplow Ruby Tracker and Snowplow Python Tracker. It supports all the same events, as well as for unstructured events and custom contexts.

All events generated by the tracker are sent asynchronously, using the Request module. We have written an asynchronous test suite using Mocha.

5. Getting help

If you need help getting set up or want a new feature, please get in touch. This is only the first release of the Node.js Tracker and we’re keen to hear people’s opinions. Finally, raise an issue if you find any bugs!