Javascript Tracker Core - OXYGEN-MARKET/oxygen-market.github.io GitHub Wiki

HOME > SNOWPLOW TECHNICAL DOCUMENTATION > Trackers > JavaScript Tracker Core

Contents

1. Overview

The Snowplow JavaScript Tracker Core is an npm module providing functionality common to both the server-side Snowplow Node.js Tracker and the client-side Snowplow JavaScript Tracker. It supports all the Snowplow event types. Custom contexts and timestamps can be added to all events.

It has two main types of method: setter methods and tracking methods. Setter methods like setUserId store a name-value pair to be added to all future events, while tracking methods like trackPageView track a specific event.

There is a setup guide here.

2 Initialization

2.1 Requiring the module

Require the Snowplow Tracker Core module into your code like so:

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

2.2 Creating a tracker core instance

The tracker core constructor takes two parameters:

  • A boolean value indicating whether unstructured events and custom contexts should be base 64 encoded (which defaults to true)
  • An optional callback to be executed on every payload before it is returned
var t = snowplowTrackerCore(false, console.log);

The above example would create a tracker core instance which doesn't use base 64 encoding and which logs all payloads it creates to the console.

3. Setter methods

The core instance maintains a dictionary called payloadPairs containing persistent name-value pairs which are added to every payload. You can interact with these through the following methods:

3.1 addPayloadPair()

Adds a single name-value pair to payloadPairs.

t.addPayloadPair('myKey', 'myValue');

3.2 addPayloadDict()

Adds all the name-value pairs in a dictionary to payloadPairs.

t.addPayloadDict({
	key1: 'value1',
	key2: 'value2'
});

3.3 resetPayloadPairs()

Creates a new dictionary of payload pairs, removing all pre-existing name-value pairs. If no argument is provided, creates an empty dictionary.

t.resetPayloadPairs({
	key1: 'value1',
	key2: 'value2'
});

3.4 Other setter methods

For convenience, other setter methods are provided for certain fields. They all use addPayloadPair.

Method name Key added Example
setTrackerVersion tv t.setTrackerVersion('js-3.0.0');
setTrackerNamespace tna t.setTrackerNamespace('cloudfront-1');
setAppId aid t.setAppId('my-node-application');
setPlatform p t.setPlatform('web');
setUserId uid t.setUserId('user-427')
setScreenResolution res t.setScreenResolution(800, 600)
setViewport vp t.setViewport(307,250)
setColorDepth cd t.setColorDepth(24)
setTimezone tz t.setTimezone('Europe/London')
setIpAddress ip t.setIpAddress('37.347.12.457')

3.5 Example

Some calls to setter methds, along with comments indicating the current state of the payloadPairs dictionary:

var snowplowTrackerCore = require('snowplow-tracker-core');
var t = snowplowTrackerCore(); // {}
t.addPayloadPair('a', 'one');  // {a: 'one'}
t.addPayloadDict({
	b: 'two',
	c: 'three'
});                            // {a: 'one', b: 'two', c: 'three'}
t.resetPayloadPairs();         // {}
t.setPlatform('srv');          // {p: 'srv'}
t.setPlatform('pc');           // {p: 'pc'}
t.setViewport(600, 400);       // {p: 'pc', 'vp': 600x400}
t.resetPayloadPairs({
	d: 'four',
	e: 'five'
});                            // {d: 'four', e: 'five'}

4 Tracking methods

4.1 Common features

Any method whose name starts with "track..." is a tracking method which creates a payload for a single Snowplow event. The tracking methods have certain features in common.

4.1.1 Custom contexts

Each tracking method's penultimate argument is an optional array of custom context dictionaries.

Example:

var myContexts = [{
  'schema': 'iglu:com.acme/viewed_product/1-0-1',
  'data': {
    'price': 13,
    'name': 'cyan paint'
  }
},
{
  'schema': 'iglu:com.acme/page_type/1-0-1',
  'data': {
    'type': 'testPage'
  }
}];

t.trackScreenView('title screen', 's-1342', myContexts);

4.1.2 Timestamp argument

Each tracking method's final argument is an optional timestamp. It should be in milliseconds since the Unix epoch - the same format generated by new Date().getTime(). If you don't provide a timestamp for an event, the current time will be used.

4.1.3 Return values

When called, a tracker method will assemble a payload dictionary based on the arguments passed to it and the payloadPairs object, and will add a version 4 UUID. If you provided a callback function when constructing the core instance, that function will be passed the payload. (For example, the callback could be used to convert the payload to a querystring and send it to a Snowplow collector.) The payload will then be returned.

4.2 trackScreenView()

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

4.3 trackPageView()

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

4.4 trackEcommerceTransaction()

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
context Custom context No Array
tstamp When the transaction event occurred No Positive integer

Example:

t.trackEcommerceTransaction(
    "order-456",       // order ID
    null,              // affiliation
    142,               // total
    20,                // tax
    12.99,             // shipping
    "London",          // city
    null,              // state
    "United Kingdom",  // country
    "GBP"              // currency
);

4.5 trackEcommerceTransactionItem()

Field Description Required? Type
orderId ID of the eCommerce transaction Yes Non-empty string
sku Item SKU Yes Non-empty string
name Item name No String
category Item category No String
price Item price Yes Number
quantity Item quantity Yes Int
currency Currency No String
context Custom context for the event No Array
tstamp When the transaction event occurred No Positive integer

Example:

t.trackEcommerceTransactionItem(
    "order-456", // order ID
    "570634",    // SKU
    "red hat",   // name
    "headgear",  // category
    10,          // price
    1,           // quantity
    "GBP"        // currency
);

4.6 trackStructEvent()

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

4.7 trackUnstructEvent()

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": "com.example_company/save-game/jsonschema/1.0.2",
  "data": {
    "save_id": "4321",
    "level": 23,
    "difficultyLevel": "HARD",
    "dl_content": true
  }
})

4.8 trackLinkClick()

Field Description Required? Type
targetUrl URL of the link Yes Non-empty string
elementId HTML id of the link element No Non-empty string
elementClasses HTML classes of the link element No Array
elementTarget HTML target of the link element No String
context Custom context for the event No Array
tstamp Item price No Number 
t.trackLinkClick(
    'http://www.example.com',  // URL
    'first header',            // id
    ['header'],                // classes
    '_blank'                   // target
);

4.9 trackAdImpression()

Name Description Required? Type
impressionId Identifier for the particular impression instance No string
costModel The cost model for the campaign: 'cpc', 'cpm', or 'cpa' No string
cost Ad cost No number
targetUrl The destination URL No string
bannerId Adserver identifier for the ad banner (creative) being displayed No string
zoneId Adserver identifier for the zone where the ad banner is located No string
advertiserID Adserver identifier for the advertiser which the campaign belongs to No string
campaignId Adserver identifier for the ad campaign which the banner belongs to No string

Example:

t.trackAdImpression(
    '67965967893',             // impressionId
    'cpm',                     // costModel - 'cpa', 'cpc', or 'cpm'
     5.5,                      // cost
    'http://www.example.com',  // targetUrl
    '23',                      // bannerId
    '7',                       // zoneId
    '201',                     // advertiserId
    '12'                       // campaignId
);

4.10 trackAdClick()

Name Description Required? Type
targetUrl The destination URL Yes string
clickId Identifier for the particular click instance No string
costModel The cost model for the campaign: 'cpc', 'cpm', or 'cpa' No string
cost Ad cost No number
bannerId Adserver identifier for the ad banner (creative) being displayed No string
zoneId Adserver identifier for the zone where the ad banner is located No string
advertiserID Adserver identifier for the advertiser which the campaign belongs to No string
campaignId Adserver identifier for the ad campaign which the banner belongs No to

Example:

t.trackAdClick(
    'http://www.example.com',  // targetUrl
    '12243253',                // clickId
    'cpm',                     // costModel
     2.5,                      // cost
    '23',                      // bannerId
    '7',                       // zoneId
    '67965967893',             // impressionId - the same as in trackAdImpression
    '201',                     // advertiserId
    '12'                       // campaignId
);

4.11 trackAdConversion()

Name Description Required? Type
conversionId Identifier for the particular conversion instance No string
costModel The cost model for the campaign: 'cpc', 'cpm', or 'cpa' No string
cost Ad cost No number
category Conversion category No number
action The type of user interaction, e.g. 'purchase' No string
property Describes the object of the conversion No string
initialValue How much the conversion is initially worth No number
advertiserID Adserver identifier for the advertiser which the campaign belongs to No string
campaignId Adserver identifier for the ad campaign which the banner belongs to No string

Example:

t.trackAdConversion(
    '743560297', // conversionId
    10,          // cost
    'ecommerce', // category
    'purchase',  // action
    '',          // property
    99,          // initialValue - how much the conversion is initially worth
    '201',       // advertiserId
    'cpa',       // costModel
    '12'         // campaignId
);

Home | About | Project | Setup Guide | Technical Docs | Copyright © 2012-2017 Snowplow Analytics Ltd

⚠️ **GitHub.com Fallback** ⚠️