Skip to main content

Page view tracking

Page view events are tracked using the trackPageView method. This is generally part of the first Snowplow tag to fire, or first method to be called, on a particular web page. As a result, the trackPageView method is usually deployed straight after the tag that also invokes the Snowplow JavaScript (sp.js).

Tracking a page view​

Page view events must be manually tracked.

import { trackPageView } from '@snowplow/browser-tracker';

trackPageView();

This method automatically captures the URL, referrer URL and page title (inferred from the <title> tag). The first page view tracked uses document.referrer for the referrer URL, while for subsequent page views it is the previous page URL.

It's possible to override the URL and referrer URL.

If you wish, you can also override the title with a custom value:

import { trackPageView } from '@snowplow/browser-tracker';

trackPageView({ title: 'my custom page title' });

Context callback​

As with all trackX methods, trackPageView can be passed an array of custom context entities as an additional parameter.

Additionally, you can pass a function which returns an array of zero or more context entities to trackPageView. For the page view and for all subsequent page pings, the function will be called and the context entities it returns will be added to the event.

For example:

// Turn on page pings every 10 seconds
snowplow('enableActivityTracking', {
  minimumVisitLength: 10,
  heartbeatDelay: 10
});

snowplow('trackPageView', {
  // The usual array of static context entities
  context: [{
    schema: 'iglu:com.acme/static_context/jsonschema/1-0-0',
    data: {
      staticValue: new Date().toString()
    }
  }],
  // Function which returns an array of custom context entities
  // Gets called once per page view / page ping
  contextCallback: function() {
    return [{
      schema: 'iglu:com.acme/dynamic_context/jsonschema/1-0-0',
      data: {
        dynamicValue: new Date().toString()
      }
    }];
  }
});

In this example, the tracked page view and every subsequent page ping will have both a static_context and a dynamic_context attached. The static_contexts will all have the same staticValue, but the dynamic_contexts will have different dynamicValues since a new context is created for every event.

WebPage (page view ID) context entity​

When the JavaScript Tracker loads on a page, it generates a new page view UUID. If the webPage context entity is enabled, then an entity containing this UUID is attached to all events.

From v3 of the web tracker, the webPage entity is enabled by default. We advise you leave this enabled so you can use the Snowplow Web Data Model.

To disable this entity, set "webPage": false in the "contexts" object within the tracker configuration object.

Web page entity properties

The web_page context entity consists of the following property:

AttributeDescriptionRequired?
idAn identifier (UUID) for the page view.Yes

Reset page ping on page view​

By default the tracker will reset the Page Ping timers, which were configured when enableActivityTracking is called, as well as reset the attached webPage context entities on all future Page Pings when a new trackPageView event occurs. This is enabled by default as of 2.13.0 and is particularly useful for Single Page Applications (SPA). If you previously relied on this behavior, you can disable this functionality by specifying resetActivityTrackingOnPageView: false in the configuration object on tracker initialisation.

Get page view ID​

When the JavaScript Tracker loads on a page, it generates a new page view UUID as mentioned above.

It's possible to retrieve certain properties for use in your code, including the page view UUID, user ID, and cookie values, using a tracker callback. This is an advanced usage of the tracker.

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

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

Or equivalently:

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

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

// 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 should not be a method:

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

This will not 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:

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

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

To get the page view ID, use the getPageViewId method:

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