Snowplow Node.js Tracker 0.1.0 released

08 August 2014  •  Fred Blundun

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

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.

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].

Require the tracker module like this:

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

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

function tracker(endpoint, namespace, appId, encodeBase64);
  • 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('d3rkrsqld9gmqf.cloudfront.net', 'tracker2', 'my-app', false);

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

t.setUserId('345723-046778-346346');
t.setPlatform('web');
t.setTimezone('Europe/London');
t.setColorDepth(24);

Send some events:

// A page view event
t.trackPageView('http://www.example.com', 'example page', 'http://www.referrer.com');

// An unstructured event
t.trackUnstructEvent({
	schema: 'iglu:com.acme/product_view/jsonschema/1-0-0',
	data: {
		productCategory: 'books',
		productName: 'Leviathan'
	}
});

// 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.

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.

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!