Skip to main content

Track page views on web

Page view events are one of the most fundamental types of events to track on a website. They're tracked using trackPageView().

Page view events must be manually tracked.

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

trackPageView();

This method automatically captures the URL, referrer URL, and page title. The first page view tracked uses document.referrer for the referrer URL, while for subsequent page views the referrer is the previous page URL.

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

By default, the tracker infers the page title from the <title> tag. If you wish, you can also override the title with a custom value:

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

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

Page view ID and web_page entity​

When the tracker loads on a page, or when trackPageView() is called, it generates a new page view UUID. This page view ID is attached to all events tracked on that page, as a web_page entity, until the next page view event is tracked. At that point, a new page view ID is generated and used for all subsequent events.

From version 3, the web_page entity is enabled by default. We advise you leave this enabled so you can use the Snowplow Unified Digital dbt package.

By default, the tracker lazily generates the page view ID when it's needed for the first time. For example:

  1. The tracker is initialized when the page loads
  2. trackPageView() is called for the first time
  3. Tracker calls getPageViewId() to get the current page view ID
  4. Since there is no page view ID yet, it generates a new one
  5. The page view event is tracked with the generated page view ID
  6. Subsequent events use the same page view ID

The next time trackPageView() is called, the tracker generates a new page view ID.

If you track an event before the first page view, the tracker will generate the page view ID at that point:

  1. The tracker is initialized when the page loads
  2. A custom event is tracked
  3. Tracker calls getPageViewId() to get the current page view ID
  4. Since there is no page view ID yet, it generates a new one
  5. The custom event is tracked with the generated page view ID
  6. Subsequent events, including the first page view, use the same page view ID

The second page view will generate a new page view ID as usual.

You can get the current page view ID using the getPageViewId function.

Change ID behavior for SPAs​

In a single-page app (SPA), the tracker stays in memory as the user navigates between URLs. If you track events after navigating to a new URL but before calling trackPageView(), those events will use the existing page view ID from the previous page. The ID only resets when trackPageView() is called.

Use the preservePageViewIdForUrl configuration option to bind the page view ID generation to URL changes instead of page view events. The options are:

  • false (default): URL changes don't trigger a new ID when reading getPageViewId(). Only trackPageView() triggers a new ID (on second+ call).
  • true or 'full': generate a new ID when reading getPageViewId() if the full URL changed. trackPageView() still generates a new ID on second+ call even for the same URL.
  • 'pathname': generate a new ID when reading getPageViewId() if pathname changed. Search params or fragment changes don't trigger a new ID.
  • 'pathnameAndSearch': generate a new ID when reading getPageViewId() if pathname or search params changed. Fragment changes don't trigger a new ID.
  • preservePageViewId: never regenerate the ID at all. Ignores preservePageViewIdForUrl.

You can set these options at initialization or during runtime:

javascript
// At initialization
snowplow('newTracker', 'sp', 'collector.example.com', {
  appId: 'my-app',
  preservePageViewIdForUrl: 'pathname'
});

// At runtime
snowplow('preservePageViewIdForUrl', 'pathname');

Reset page activity on page view​

By default, tracking a page view using trackPageView()resets activity tracking.

Read more about this in the activity tracking documentation.

Add entities dynamically​

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

Additionally, you can add entities to page view and page ping events dynamically using the contextCallback option.

Pass it a function that returns an array of zero or more entities. The function will fire for the page view and for all subsequent page pings on the page. The returned entities will be added to the events.

For example:

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

snowplow('trackPageView', {
  // The usual array of static entities
  context: [{
    schema: 'iglu:com.acme/static_context/jsonschema/1-0-0',
    data: {
      staticValue: new Date().toString()
    }
  }],
  // Function which returns an array of custom 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_context will all have the same staticValue, but the dynamic_context will have different dynamicValue values.

On this page

Want to see a custom demo?

Our technical experts are here to help.

Book a demo