Measure single-page applications

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 implementation Custom event implementation

Custom event implementation

When you implement page_view events yourself, ensure the following website behavior when the screen changes:

• Set the page_referrer and page_location to the correct values for proper attribution

• Send a new page_view event

gtag.js

1. Store the old and new URL of your single page application so you can access the values when you manually send the page_view event.

2. Create a function that updates the page_referrer and page_location to the corresponding screens of your SPA.
   Optional: To update the previously set values without re-initializing the Google tag, supply the key-value pair 'update': true.

3. Optional: Custom dimensions: To update custom dimensions and metrics with the new virtual page view, include them in your config command. Learn more About custom dimensions and metrics.

4. Send a page_view event to count the screen change as a page view. For example:

    // Store current URL path and query in a variable.
       const oldUrl = window.location.href.split('#')[0];
    // Change to new URL.
       history.pushState({}, undefined, newUrl);
    // Measure page change.
       function OnPageChange(oldUrl, newUrl) {
          gtag('config', 'G-XXXXXX', {
           'send_page_view': false,
           'page_referrer': oldUrl,
           'page_location': newUrl,
           'update': true,
        });
          gtag('event', 'page_view');
        }
   

5. Fire the OnPageChange function when you need to trigger a new virtual page view.

Tag Manager

To measure a SPA with Tag Manager you need two Google tags with the same tag ID in your container. The first Google tag loads when the website loads and sets any parameters you need for your measurement. The second Google tag triggers whenever the URL of your website changes. Finally, you need to manually send a page view event to record the new virtual page.

1. Prepare the Google Analytics data stream for SPA measurement

To manually track page_view events:

1. Open Google Analytics

2. In Admin, under Data collection and modification, click Data streams.

3. Under Enhanced measurement, select the settings icon .

4. Under Page views > Show advanced settings, clear Page changes based on browser history events. You will manually record the browser history changes in Tag Manager.

5. Click Save.

2. Create a Google tag for SPA virtual page views

1. Open Google Tag Manager

2. In your workspace, open the Tags menu.

3. Create a New tag.

4. In Tag Configuration, choose the Google tag.

5. Enter the same Google tag ID as the ID for your first Google tag.

6. Under Configuration settings, supply the following parameters:

   • page_referrer : {{Old History URL}}
   • page_location : {{New History URL}}

   • update : true

     Note: The update parameter merges new or updated parameters into the existing Google tag configuration. It also suppresses sending a new page_view event.

   • Optional: Specify any custom dimensions and metrics to update with the new virtual page view.

7. Under Triggering, set the following:

   1. In Choose a Trigger, create a new trigger (+).
   2. In Trigger Configuration, choose the History Change trigger. Learn more about the History change trigger. Make sure to only trigger this tag when a new screen appears.
   3. Name and Save the trigger.

8. Name and Save your tag. Your Google tag should look like this:

3. Trigger a new page view event

1. In your Tag Manager workspace, create a New tag.

2. In Tag Configuration, choose the Google Analytics: GA4 Event tag.

3. Enter the measurement ID for the tag. This ID matches with the Google tag ID you used in the previous tag.

4. To send a new page view event, add page_view as the Event Name.

5. In Triggering, set the History change trigger. This should be the same trigger as for the Google tag you set up.

6. Name and Save your tag.

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.