Skip to main content

Track data out-of-the-box with the web trackers

To track an event, the API is slightly different depending if you're using the JavaScript or Browser version of our web tracker.

The main built-in events are page views and page pings. Here's how to track them:

javascript
import {
  newTracker,
  trackPageView,
  enableActivityTracking
} from '@snowplow/browser-tracker';

newTracker('sp', '{{collector_url_here}}', {
    appId: 'my-app-id',
});

enableActivityTracking({
  minimumVisitLength: 30,
  heartbeatDelay: 10
});

trackPageView();

As well as page views and activity tracking, you can track custom events, or use plugins to track a wide range of other events and entities.

Add contextual data with entities​

The tracker can be set up to automatically add entities to every event sent.

Most entity autotracking is specifically configured using plugins, which are imported, enabled, and configured individually. However, you can configure some entities directly when instrumenting the tracker, using the configuration object.

EntityUsageAdded by defaultJavaScript (tag) trackerBrowser (npm) tracker
webPageUUID for the page view✅contexts configcontexts config
sessionData about the current session❌contexts configcontexts config
browserProperties of the user's browser❌contexts configcontexts config
performanceTimingPerformance timing metrics❌contexts configPlugin
gaCookiesExtract GA cookie values❌contexts configPlugin
geolocationUser's geolocation❌contexts configPlugin

If you're using the sp.lite.js JavaScript tracker distribution, only the webPage, session, and browser entities are available out of the box, as the others require plugins that aren't included in that distribution.

You can also attach your own custom entities to events.

For example, here is a page view with an additional custom entity:

javascript
snowplow('trackPageView', {
  context: [{
    schema: "iglu:com.example_company/page/jsonschema/1-2-1",
    data: {
      pageType: 'test',
      lastUpdated: new Date(2021,04,01)
    }
  }]
});
note

Tracker methods available through plugins do not necessarily support adding custom entities. For those please refer to the corresponding plugin documentation for details.

Set event properties​

Certain event properties, including domain_userid or application_id, can be set as atomic properties in the raw event.

Application ID​

Set the application ID using the appId field of the tracker configuration object. This will be attached to every event the tracker fires. You can set different application IDs on different parts of your site. You can then distinguish events that occur on different applications by grouping results based on application_id.

Application version​

info

The option to track the application version was introduced in version 4.1 of the JavaScript tracker.

Set the application ID using the appVersion field of the tracker configuration object. This will be attached to every event the tracker fires using the application entity.

The version of can be a semver-like structure (e.g 1.1.0) or a Git commit SHA hash.

Application platform​

Set the application platform using the platform field of the tracker configuration object. This will be attached to every event the tracker fires. Its default value is web. For a list of supported platforms, please see the Snowplow Tracker Protocol.

Business user ID​

The JavaScript Tracker automatically sets a domain_userid based on a first party cookie. Read more about cookies here.

There are many situations, however, when you will want to identify a specific user using an ID generated by one of your business systems. To do this, you use one of the methods described in this section: setUserId, setUserIdFromLocation, setUserIdFromReferrer, and setUserIdFromCookie.

Typically, companies do this at points in the customer journey where users identify themselves e.g. if they log in.

note

This will only set the user ID on further events fired while the user is on this page; if you want events on another page to record this user ID too, you must call setUserId on the other page as well.

setUserId​

setUserId is the simplest of the four methods. It sets the business user ID to a string of your choice:

javascript
snowplow('setUserId', 'joe.blogs@email.com');
note

setUserId can also be called using the alias identifyUser.

setUserIdFromLocation​

setUserIdFromLocation lets you set the user ID based on a querystring field of your choice. For example, if the URL is http://www.mysite.com/home?id=user345, then the following code would set the user ID to “user345”:

javascript
snowplow('setUserIdFromLocation', 'id');

setUserIdFromReferrer​

setUserIdFromReferrer functions in the same way as setUserIdFromLocation, except that it uses the referrer querystring rather than the querystring of the current page.

javascript
snowplow('setUserIdFromReferrer', 'id');

setUserIdFromCookie​

Use setUserIdFromCookie to set the value of a cookie as the user ID. For example, if you have a cookie called “cookieid” whose value is “user123”, the following code would set the user ID to “user123”:

javascript
snowplow('setUserIdFromCookie', 'cookieid');

Custom page URL and referrer URL​

The Snowplow JavaScript Tracker automatically tracks the page URL and referrer URL on any event tracked. However, in certain situations, you may want to override the one or both of these URLs with a custom value. For example, this might be desirable if your CMS spits out particularly ugly URLs that are hard to unpick at analysis time.

To set a custom page URL, use the setCustomUrl method:

javascript
snowplow('setCustomUrl', 'http://mysite.com/checkout-page');

To set a custom referrer, use the setReferrerUrl method:

javascript
snowplow('setReferrerUrl', 'http://custom-referrer.com');
For Single Page Apps

On an SPA, the page URL might change without the page being reloaded. Whenever an event is fired, the Tracker checks whether the page URL has changed since the last event. If it has, the page URL is updated and the URL at the time of the last event is used as the referrer. If you use setCustomUrl, the page URL will no longer be updated in this way. Similarly if you use setReferrerUrl, the referrer URL will no longer be updated in this way.

To use setCustomUrl within an SPA, call it before all trackPageView calls.

If you want to ensure that the original referrer is preserved even though your page URL can change without the page being reloaded, use setReferrerUrl like this before sending any events:

javascript
snowplow('setReferrerUrl', document.referrer);

Custom timestamp​

Snowplow events have several timestamps.

Every trackX...() method in the tracker allows for a custom timestamp, called trueTimestamp to be set.

In certain circumstances you might want to set the timestamp yourself e.g. if the JS tracker is being used to process historical event data, rather than tracking the events live. In this case you can set the true_timestamp for the event.

To set the true timestamp add an extra argument to your track method: {type: 'ttm', value: unixTimestampInMs}.

This example shows how to set a true timestamp for a page view event:

javascript
snowplow('trackPageView', {
  timestamp: { type: 'ttm', value: 1361553733371 }
});

E.g. to set a true timestamp for a self-describing event:

javascript
snowplow('trackSelfDescribingEvent', {
  event: {
    schema: 'iglu:com.acme_company/viewed_product/jsonschema/2-0-0',
    data: {
        productId: 'ASO01043',
        category: 'Dresses',
        brand: 'ACME',
        returning: true,
        price: 49.95,
        sizes: ['xs', 's', 'l', 'xl', 'xxl'],
        availableSince: new Date(2013,3,7)
    }
  },
  timestamp: { type: 'ttm', value: 1361553733371 }
});

Get event properties​

It's possible to retrieve certain identifiers and properties for use in your code. You'll need to use a callback for the JavaScript tracker.

If you call snowplow with a function as the argument, the function will be executed when sp.js loads:

javascript
snowplow(function () {
  console.log("sp.js has loaded");
});

Or equivalently:

javascript
snowplow(function (x) {
  console.log(x);
}, "sp.js has loaded");

The callback you provide is executed as a method on the internal trackerDictionary object. You can access the trackerDictionary using this.

javascript
// Configure a tracker instance named "sp"
snowplow('newTracker', 'sp', '{{COLLECTOR_URL}', {
 appId: 'snowplowExampleApp'
});

// Access the tracker instance inside a callback
snowplow(function () {
 var sp = this.sp;
 var domainUserId = sp.getDomainUserId();
 console.log(domainUserId);
})

The callback function shouldn't be a method:

javascript
// TypeError: Illegal invocation
snowplow(console.log, "sp.js has loaded");

This won't work because the value of this in the console.log function will be the trackerDictionary, rather than console.

You can get around this problem using Function.prototoype.bind as follows:

javascript
snowplow(console.log.bind(console), "sp.js has loaded");

For more on execution context in JavaScript, see the MDN page.

You can retrieve cookie values using the getDomainUserInfo and other getters, or from the cookies directly.

Page view ID​

When the JavaScript Tracker loads on a page, it generates a new page view UUID. To get this page view ID, use the getPageViewId method:

javascript
// Access the tracker instance inside a callback
snowplow(function () {
 var sp = this.sp;
 var pageViewId = sp.getPageViewId();
 console.log(pageViewId);
})

Business user ID​

The getUserId method returns the user ID which you configured using setUserId():

javascript
// Access the tracker instance inside a callback
snowplow(function () {
 var sp = this.sp;
 var userId = sp.getUserId();
 console.log(userId);
})

Tab ID​

If you've enabled the browser entity, you can get the tab ID using the getTabId method. It's a UUID identifier for the specific browser tab the event is sent from.

javascript
// Access the tracker instance inside a callback
snowplow(function () {
 var sp = this.sp;
 var tabId = sp.getTabId();
 console.log(tabId);
})

On this page

Want to see a custom demo?

Our technical experts are here to help.

Book a demo