Measure single-page applications with Google Tag Manager

This tutorial shows you how to set up Google Analytics measurement for a single-page application (SPA) using Google Tag Manager. You will learn how to configure your Google Analytics property, enable the necessary GTM variables, and create tags that trigger on history changes.

Before you begin

This tutorial assumes that you have:

• A Google Analytics account and property.
• A Google Tag Manager container installed on your SPA.
• The Editor (or above) role for both Google Analytics and Google Tag Manager.

Step 1: Prepare the GA4 data stream

To manually track page_view events in a SPA, you must first disable automatic history-based page views in GA4 to avoid double-counting.

1. Open Google Analytics.
2. In Admin, under Data collection and modification, click Data streams.
3. Select your web data stream.
4. Under Enhanced measurement, click the settings icon .
5. Under Page views > Show advanced settings, clear Page changes based on browser history events.
6. Click Save.

Step 2: Enable built-in History variables in Tag Manager

To use history-based triggers or variables in GTM, you must first enable the built-in History variables.

1. Open Google Tag Manager.
2. In your workspace, navigate to Variables.
3. Under Built-In Variables, click Configure.
4. In the History section, enable the following variables:
   • History New URL Fragment
   • History Old URL Fragment
   • History New State
   • History Old State
   • History Source
5. Close the configuration panel.

Note: These variables are not strictly required for the basic page view setup. They are only used if you want to filter the trigger or implement custom logic, such as the previous page logic mentioned in the final note of this page.

Note: Some older documentation may refer to Old History URL or New History URL. These are not standard built-in variables. Use the listed variables instead.

Step 3: Create the History Change trigger

Next, create a trigger that fires whenever a history change event (like pushState or replaceState) occurs in your SPA.

1. In your Tag Manager workspace, navigate to the Triggers menu.
2. Click New.
3. In Trigger Configuration, choose the History Change trigger.
4. (Optional) If you only want to track certain screen changes, update the trigger to fire on Some History Changes.
5. Name the trigger (e.g., "History Change") and click Save.

Step 4: Create the Google tag

Now, create a Google tag that updates the page_location parameter whenever a history change occurs.

1. In the Tags menu, click New.
2. In Tag Configuration, choose the Google tag.
3. Enter your Tag ID (the same ID used for your initial Google tag).

4. Under Configuration settings, add the following parameters:

   • page_location: {{Page URL}}
   • page_title: {{Page Title}}
   • update: true
   Note: The update parameter merges the configuration values into the existing tag configuration and suppresses an immediate duplicate page_view event. page_referrer is not included here because Google Analytics automatically tracks the original external referrer on the initial page load, and omitting it allows Google Analytics to automatically populate the previous virtual page URL as the referrer for navigation pathing in your reports.

5. Name the tag (for example, "Google Tag - SPA Update") and click Save.

   Note: Don't add a trigger in the Triggering section for this Google tag. It is triggered as a setup tag using tag sequencing in Step 5.

Step 5: Send the virtual page_view event

Finally, create a GA4 Event tag to send the actual page_view event for each virtual page load.

1. Click New in the Tags menu.
2. In Tag Configuration, choose Google Analytics: GA4 Event.
3. Enter your Measurement ID.
4. Set the Event Name to page_view.
5. Under Advanced Settings > Tag Sequencing, select Fire a tag before GA4 Event - Virtual Page View fires and select the Google Tag - SPA Update tag that you created in Step 4.
6. Under Triggering, select the History Change trigger you created in Step 3.
7. Name the tag (for example, "GA4 Event - Virtual Page View") and click Save.

Step 6: Verify your setup

To ensure your virtual page views are being recorded correctly:

1. In Tag Manager, click Preview to enter the Preview mode.
2. Navigate through your SPA.
3. In Google Analytics DebugView, verify that a new page_view event appears for each screen change.
4. Check that the page_location values match your expectations.

Note: Using standard {{Referrer}} captures the initial source that led the user to your site. To track the previous virtual page within your SPA as the referrer, you would need to implement a custom GTM variable to store the previous page location.