Page URL Enrichment Plugin

The Page URL Enrichment plugin automatically adds page URL-related properties to all events tracked by the Browser SDK. This plugin enhances your event data with contextual information about the current page and previous page navigation. This lets you better understand user journeys and page transitions.

When using the plugin, remember:

• The plugin automatically starts tracking page changes when added to the SDK.
• 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

This package is available on the npm registry for installation using npm and yarn.

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

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

Usage

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

1. Import Amplitude packages

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.

const pageUrlEnrichment = pageUrlEnrichmentPlugin();

3. Install plugin to Amplitude SDK

amplitude.add(pageUrlEnrichment);

4. Initialize Amplitude SDK

amplitude.init('API_KEY');

Event properties

This plugin adds the following properties to all events:

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 was from the same domain (same hostname).
• external: Previous page was from a different domain.

How it works

The Page URL Enrichment plugin:

1. Tracks page changes: Monitors navigation events such as pushState, replaceState, and popstate events to detect page changes in single-page applications.
2. Stores navigation history: Uses session storage to maintain the current and previous page URLs across page navigation.
3. Enriches all events: Automatically adds page URL properties to every event tracked by the Browser SDK.
4. Preserves existing properties: If an event already has any of the page URL properties, the plugin preserves the existing values.

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.

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

Example

Here's a complete example of how to set up the Page URL Enrichment plugin:

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 will automatically include page URL properties
amplitude.track('Button Clicked', {
  button_name: 'Sign Up'
});

The tracked event includes properties like:

{
  "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"
  }
}