Version:

Autotrack Page View Metrics using JavaScript SDK

Use the JavaScript SDK to autotrack page view metrics like time spent by user on a page.

  •   2 minute read  

This guide explains the autotracking feature of the JavaScript SDK that helps you get visibility into various page view metrics, including the time spent by the user on a web page.

info
This feature is currently supported only by the SDK’s Beacon transport mechanism.

Overview

When you enable the autotracking feature, the JavaScript SDK automatically fires a track event called Page Unloaded whenever a page unloads, that is, when the browser or tab is closed, the page is reloaded, or the user navigates to a different tab.

Each Page Unloaded event contains:

  • A property indicating the page view with a unique pageViewId
  • The time spent on that page (properties.timeOnPage) calculated by the SDK

Enable autotracking

The autotracking feature is controlled by the autoTrack parameter in the SDK’s load API options. By default, it is set to false.

"autoTrack" : {
  "enabled": true, // Default false
  "options": {} // Optional track API options to pass custom context
  "pageLifecycle": {
    "enabled": true, // Default false; overrides the global value (autoTrack.enabled)
    "options": {} // Optional, overrides the global value (autoTrack.options)
  }
}

The nested pageLifecycle object provides granular and precise tracking configuration at the page level and overrides the global tracking settings.

autoTrack configuration options

The following table lists the various autoTrack configuration options in detail:

OptionData typeDescriptionDefault value
enabledBooleanEnables or disables the autotracking feature.false
optionsObjectOptional custom metadata to the track API.-
pageLifecycle.enabledBooleanOverrides the global autoTrack.enabled setting for tracking lifecycle of a specific page.false
pageLifecycle.optionsObjectOptional custom metadata to the track API specified at the page level.-

Workflow

When you set autoTrack.pageLifecycle.enabled or autoTrack.enabled (when autoTrack.pageLifecycle.enabled is not set) to true:

  1. RudderStack fires a track event called Page Unloaded with the property context.autoTrack.page.pageViewId when the current page unloads. Note that the pageViewId is a UUID.
  2. It also calculates the time spent on the page in milliseconds and includes it in the Page Unloaded event in the properties.timeOnPage field.

Example payload

A sample payload for the Page Unloaded event containing the timeOnPage and pageViewId fields is shown:

{
  "properties": {
    "timeOnPage": 25257
  },
  "event": "Page Unloaded",
  "type": "track",
  "channel": "web",
  "context": {
    "traits": {
      ...
    },
    "sessionId": 1747113325887,
    ...

    "autoTrack": {
      "page": {
        "pageViewId": "2d9abedf-a703-4c42-8e83-db6965fc1249"
      }
    }
  },
  ...

  "integrations": {
    "Google Analytics 4 (GA4)": {
      ...
      "sessionNumber": 131
    },
    "All": true
  },
  "sentAt": "2025-05-13T05:19:04.714Z"
}

Limitations

To deliver the Page Unloaded event reliably, the autotracking feature is currently supported only when Beacon transport mechanism is enabled. That means you must set useBeacon to true in the SDK load API options.


Questions? Contact us by Email or on Slack