Measure single-page applications

Page Summary

outlined_flag

• This document provides guidance for developers on measuring page views for single-page applications (SPAs) using Google Analytics.

• SPAs load content dynamically, requiring a different approach to tracking page views for accurate user journey analysis.

• To measure SPA page views correctly, you need to count page views for each screen interaction and accurately track the referrer.

• Implementing SPA measurement involves triggering virtual page views through either browser history changes or custom events.

• Verifying your SPA measurement setup requires enabling debug mode and checking for page_view events in DebugView as you navigate the application.

This document is for developers who want to measure page views on their single-page application using Google Analytics.

Single-page applications (SPA) are websites that load an HTML document once and fetch any additional content using JavaScript APIs.

Example: Suppose you have a form to acquire some leads. The form has three screens:

• First screen to capture the customer information.
• Second screen where customers indicate interest in certain services.
• Third screen page to sign up for webinars related to the customer's interests.

The key to measuring page views from SPAs correctly is to count page views for each screen a user interacts with and get the page referrer right, so you can correctly trace the user journey.

Before you begin

This page assumes that you already have:

• A Google Analytics 4 account and property for your website. Learn how to Set up Google Analytics.

• A Google tag implemented on your website that fires when the page initially loads. Learn how to Set up the Google tag.

Implement single-page application measurement

To implement accurate SPA measurement, use one of these methods to trigger a new virtual page view:

• Browser history changes (recommended): If your SPA uses the History API, specifically the pushState() and replaceState() method to update screens, use this option.

• Custom events: If your website uses the DocumentFragment object to render different screens, use this option.

Browser history change implementation

If your SPA uses the History API, you can enable enhanced measurement in Google Analytics to automatically track page views based on browser history events.

Enable enhanced measurement in GA4

To measure page_views automatically based on browser history:

1. Open Google Analytics

2. In Admin, under Data collection and modification, click Data Streams > Web.

3. Under Enhanced measurement, slide the switch On to enable all options.

4. Click to edit individual options. Under Page Views, click Show advanced settings. Make sure to enable both Page loads and Page changes based on browser history events.

   

5. Save the changes.

Note: When Enhanced Measurement is enabled for "Page changes based on browser history events", Google Analytics automatically listens for history events (like those used in SPAs) and sends page_view events. You don't need to configure specific history variables or triggers in Google Tag Manager for the purpose of sending page views to GA4.

Use Google Tag Manager triggers for history events

If you need to fire other types of tags in Google Tag Manager based on browser history changes such as to send data to other marketing platforms, you can use the "History Change" trigger type.

When configuring tags or variables to work with the History Change trigger, make sure you use the correct Built-In Variables provided by Google Tag Manager:

• History New URL Fragment: The fragment of the URL after the history event.
• History Old URL Fragment: The fragment of the URL before the history event.
• History New State: The new history state object.
• History Old State: The old history state object.
• History Source: The source of the history event (such as popstate, pushState, replaceState).

These Built-In Variables may need to be enabled in Google Tag Manager first under Variables > Configure.

For more details on this trigger, see History change trigger.

Verify your measurement setup

To verify your single-page application measures page views correctly:

1. Enable debug mode for every tag in your SPA measurement setup. Learn how to Monitor events in DebugView.

2. Click through your single-page application. When you click to a new virtual screen, you should see a new page_view event in DebugView. Compare the page_view event parameters with the preceding page_view event to check if the page referrer and page location have been updated correctly.

Impact on automatic events

If you correctly implement virtual page view measurement in your SPA, then Google Analytics will handle other automatic events appropriately. If virtual page views are not recorded for screen changes, Google Analytics treats the SPA as a single page, leading to skewed metrics.

For example, the user_engagement event measures the time a user actively spends on a page. Without virtual page views, all engagement time is attributed to the initial page load, making it impossible to analyze time spent on individual screens.

When virtual page view measurement is correctly implemented:

• The user_engagement event is sent when the user navigates from one virtual page to another.
• The engagement time for the previous virtual page is calculated and sent along with the user_engagement event, typically just before the page_view event for the new virtual page is processed.
• Other events, such as clicks or scrolls, are associated with the page_location of the virtual page the user is currently viewing.

This lets you analyze user engagement and other metrics for individual screens or sections within your SPA, providing a more accurate understanding of the user journey.