Track screen views on web

Screen view tracking is the recommended way to track users opening a screen in mobile apps. They are the default option for tracking views in our mobile trackers. Check out the screen tracking overview page for more details and schemas.

On web, we recommend using page views to track users visiting a page. However, using the screen view tracking plugin is also an option on web.

Availability

The plugin is available from Version 4.2 of the tracker.

Screen tracking events must be manually tracked. The plugin will add the relevant entities automatically.

Install plugin

JavaScript (tag)

Tracker Distribution	Included
sp.js	❌
sp.lite.js	❌

Download:

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr (latest)
Available on unpkg	unpkg (latest)

Browser (npm)

• npm install @snowplow/browser-plugin-screen-tracking
• yarn add @snowplow/browser-plugin-screen-tracking
• pnpm add @snowplow/browser-plugin-screen-tracking

In order to make use of the plugin, you will need to register it with the tracker:

JavaScript (tag)

javascript

window.snowplow(
    'addPlugin',
    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-screen-tracking@latest/dist/index.umd.min.js',
    ['snowplowScreenTracking', 'ScreenTrackingPlugin']
);

Browser (npm)

javascript

import { ScreenTrackingPlugin } from '@snowplow/browser-plugin-screen-tracking';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [
    ScreenTrackingPlugin()
   ],
});

Track a screen view event

To track a screen view event, use the trackScreenView function.

JavaScript (tag)

This example shows the required properties only.

javascript

window.snowplow(
  'trackScreenView',
  {
    name: 'my-screen-name',
    id: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', // generated automatically if not provided
  }
);

Browser (npm)

This example shows the required properties only.

javascript

import { trackScreenView } from '@snowplow/browser-plugin-screen-tracking';

trackScreenView({
  name: 'my-screen-name',
  id: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', // generated automatically if not provided
});

Screen entity

By default, the tracker will automatically attach a screen entity to all events tracked.

However, if you haven't tracked any screen views, no screen entity will be attached. The screen entity contains information about the last screen viewed by the user, based on the last trackScreenView call.

JavaScript (tag)

javascript

window.snowplow(
    'addPlugin',
    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-screen-tracking@latest/dist/index.umd.min.js',
    ['snowplowScreenTracking', 'ScreenTrackingPlugin'],
    [
      {
        screenContext: true, // enabled by default
      }
    ]
);

Browser (npm)

javascript

import { ScreenTrackingPlugin } from '@snowplow/browser-plugin-screen-tracking';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [
    ScreenTrackingPlugin({
      screenContext: true, // enabled by default
    })
   ],
});

Screen engagement tracking

By default, the screen tracking plugin enables screen engagement tracking.

The tracker will automatically track a screen end event, with screen_summary entity, just before tracking a new screen view event.

Because this feature was designed for mobile platforms, not all the functionality is applicable to web. The page doesn't distinguish between foreground and background, so the foreground_sec time in the screen_summary entity will track the total time spent on the screen. The background_sec field will always be null.

JavaScript (tag)

javascript

window.snowplow(
    'addPlugin',
    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-screen-tracking@latest/dist/index.umd.min.js',
    ['snowplowScreenTracking', 'ScreenTrackingPlugin'],
    [
      {
        screenEngagementAutotracking: true, // enabled by default
      }
    ]
);

Browser (npm)

javascript

import { ScreenTrackingPlugin } from '@snowplow/browser-plugin-screen-tracking';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [
    ScreenTrackingPlugin({
      screenEngagementAutotracking: true, // enabled by default
    })
   ],
});

Updating list item view and scroll depth information

To update the list item viewed and scroll depth information tracked in the screen_summary entity, track the ListItemView and ScrollChanged events with this information.

Page pings and element visibility

We designed the screen summary entity to work with mobile platforms. On web, you can track scroll offsets automatically using page pings.

For fine-grained tracking of page element visibility, consider using the element visibility tracking plugin instead.

When tracked and screenEngagementAutotracking is enabled, the tracker won't send these events to the Collector, but will process the information into the next screen summary entity. This means that tracking these events by themselves has no effect if you don't also track screen views.

If you've set screenEngagementAutotracking: false, the list item view and scroll depth events are treated as regular events and sent to the Collector.

You may want to track the events every time a new list item is viewed on the screen, or whenever the scroll position changes.

To update the list items viewed information:

JavaScript (tag)

javascript

window.snowplow(
  'trackListItemView',
  {
    index: 1,
    itemsCount: 10,
  }
);

Browser (npm)

javascript

import { trackListItemView } from '@snowplow/browser-plugin-screen-tracking';

trackListItemView({
  index: 1,
  itemsCount: 10,
});

To update the scroll depth information:

JavaScript (tag)

javascript

window.snowplow(
  'trackScrollChanged',
  {
    yOffset: 10,
    xOffset: 20,
    viewHeight: 100,
    viewWidth: 200,
    contentHeight: 300,
    contentWidth: 400,
  }
);

Browser (npm)

javascript

import { trackScrollChanged } from '@snowplow/browser-plugin-screen-tracking';

trackScrollChanged({
  yOffset: 10,
  xOffset: 20,
  viewHeight: 100,
  viewWidth: 200,
  contentHeight: 300,
  contentWidth: 400,
});