Page URL Enrichment Plugin

The Page URL Enrichment plugin automatically adds page URL-related properties to all events tracked by the Browser SDK through amplitude.track(). This setting doesn't affect autocaptured events. The plugin enriches your event data with contextual information about the current page and previous page navigation, which helps you understand user journeys and page transitions.

Enabled by default

Starting with Browser SDK version 2.x, autocapture enables this plugin by default. Install it manually only if you want custom configuration or have disabled autocapture entirely.

When using the plugin, note the following:

The plugin starts tracking page changes when enabled.
Session storage maintains state, so previous page information persists across page refreshes within the same session.
The plugin works with both traditional multi-page applications and single-page applications.
If session storage isn't available, the plugin still functions, but previous page tracking may have limitations.

Installation

Install this package from the npm registry using npm or yarn.

bash

# npm
npm install @amplitude/plugin-page-url-enrichment-browser

# yarn
yarn add @amplitude/plugin-page-url-enrichment-browser

Usage

Enabled by default with autocapture

Autocapture in Browser SDK version 2.x enables this plugin automatically. Use the manual installation steps below only if you want custom configuration or have disabled autocapture entirely.

This plugin works on top of the Amplitude Browser SDK and adds page URL enrichment properties to all events. To use this plugin, you must use @amplitude/analytics-browser version v2.0.0 or later.

Disable page URL enrichment

To disable automatic page URL enrichment, set autocapture.pageUrlEnrichment to false:

typescript

import * as amplitude from "@amplitude/analytics-browser";

amplitude.init("YOUR_API_KEY", {
  autocapture: {
    pageUrlEnrichment: false,
  },
});

Manual plugin installation

If you need custom configuration or have disabled autocapture entirely, install the plugin manually.

1. Import Amplitude packages

typescript

import * as amplitude from "@amplitude/analytics-browser";
import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";

2. Instantiate page URL enrichment plugin

The plugin accepts an optional parameter of type Object to configure the plugin.

typescript

const pageUrlEnrichment = pageUrlEnrichmentPlugin();

3. Install plugin to Amplitude SDK

typescript

amplitude.add(pageUrlEnrichment);

4. Initialize Amplitude SDK

typescript

amplitude.init("API_KEY");

Event properties

This plugin adds the following properties to all events:

Property	Description
`[Amplitude] Page Domain`	The website's hostname (`location.hostname`).
`[Amplitude] Page Location`	The website's full URL (`location.href`).
`[Amplitude] Page Path`	The website's pathname (`location.pathname`).
`[Amplitude] Page Title`	The website's title (`document.title`). To mask the title, add the `data-amp-mask` attribute to the `<title>` element.
`[Amplitude] Page URL`	The website's URL excluding query parameters.
`[Amplitude] Previous Page Location`	The URL of the previous page the user visited.
`[Amplitude] Previous Page Type`	A classification of the previous page type.

Previous page type classification

The [Amplitude] Previous Page Type property classifies the previous page based on the following logic:

direct: no previous page or referrer (user came directly to the site).
internal: previous page came from the same domain (same hostname).
external: previous page came from a different domain.

How the plugin works

The Page URL Enrichment plugin:

Tracks page changes: monitors navigation events such as pushState, replaceState, and popstate to detect page changes in single-page applications.
Stores navigation history: uses session storage to maintain the current and previous page URLs across page navigation.
Enriches all events: adds page URL properties to every event the Browser SDK tracks.
Preserves existing properties: if an event already has any of the page URL properties, the plugin preserves the existing values.

Page title masking

The Page URL Enrichment plugin supports page title masking through the data-amp-mask attribute on your page's <title> element. This attribute tells the plugin that you've disguised the page title from users and want to use the masked value in the [Amplitude] Page Title property.

For example:

html

<head>
  <!-- Masked page title
  This page title is fully masked in the `[Amplitude] Page Title`
  of all events enriched by the Page URL Enrichment plugin on this page

  Page title: "*****"
  -->
  <title data-amp-mask>Private Dashboard For John Doe</title>
</head>

The Page URL Enrichment plugin replaces the actual page title with the masked value (*****) in all events that the plugin enriches.

Session storage

The plugin uses session storage to persist navigation information across page changes. The plugin stores data using these keys:

AMP_URL_INFO: stores the current and previous page URLs.

Session storage ensures that previous page information persists during single-page application navigation or page refreshes within the same session.

Example

A complete example of how to set up the Page URL Enrichment plugin:

typescript

import * as amplitude from "@amplitude/analytics-browser";
import { pageUrlEnrichmentPlugin } from "@amplitude/plugin-page-url-enrichment-browser";

// Create the plugin instance
const pageUrlEnrichment = pageUrlEnrichmentPlugin();

// Add the plugin to Amplitude
amplitude.add(pageUrlEnrichment);

// Initialize Amplitude
amplitude.init("YOUR_API_KEY");

// Track an event - it automatically includes page URL properties
amplitude.track("Button Clicked", {
  button_name: "Sign Up",
});

The tracked event includes properties like:

json

{
  "event_type": "Button Clicked",
  "event_properties": {
    "button_name": "Sign Up",
    "[Amplitude] Page Domain": "example.com",
    "[Amplitude] Page Location": "https://example.com/signup?utm_source=google",
    "[Amplitude] Page Path": "/signup",
    "[Amplitude] Page Title": "Sign Up - Example",
    "[Amplitude] Page URL": "https://example.com/signup",
    "[Amplitude] Previous Page Location": "https://example.com/home",
    "[Amplitude] Previous Page Type": "internal"
  }
}

Was this helpful?