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.

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

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

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.