Update time: June 26, 2025
What is a Single Page Application (SPA)
A Single Page Application (SPA) is a web application where all necessary HTML, JavaScript, and CSS code is fetched at once when first loaded, or content is loaded dynamically based on user interaction without reloading the entire page. SPA implements dynamic content updates through JavaScript frameworks (such as React, Angular, Vue.js, etc.), and usually relies on the browser History API or DocumentFragment to manage page state and URL changes.
In traditional websites, each page load triggers the page_view event of GA4, but in SPA, since the page does not refresh, GA4 requires additional configuration to correctly record “virtual page views” and other user interactions.
Challenges of GA4 tracking SPA
Common tracking issues faced by GA4 in SPA include:
- Page views not recorded: Since the page does not reload, GA4‘s default page_view event may only be triggered on the first load, and subsequent changes to the page content will not be automatically recorded.
- Inaccurate URLs and Page Titles: SPAs may update URLs through pushState, but GA4 uses document.location.pathname by default, which may not capture the full URL or correct page title.
- Rogue Referral: If not configured correctly, SPAs may cause session data to be broken or referrer data to be incorrect, affecting user journey analysis.
- Event duplication or omission: Automatic tracking (such as enhanced measurement) may cause page view events to be counted repeatedly or fail to trigger in some cases.
How to determine whether your website is SPA
You can click to visit page B from page A in the preview mode of GTM, and see whether Tag Assistant reloads the page during this process. If it reloads, then it is not a single-page application. If it does not reload and a lot of “History” appears, it is a single-page application.
Before previewing, you need to open this trigger condition first. In GTM , click「Triggers」——「New」——「Choose a trigger type to begin setup…」——「History Change」，Name it “History Change “, and make the following settings:
Then click Preview, click on any page, and see the Tag Assistant:
If “History” appears in Tag Assistant, it means it is a single-page application.
Tracking SPA with Delayed Send(History Change&dataLayer.push)
Delayed sending is an optimization of Tracking Single Page Applications (SPA) with History Change, which can solve the problem of inaccurate URL and page title.
The idea is to delay 500ms when loading the page/History Change, wait for the page to open, and then execute js to obtain the accurate Page URL and Page Title of the current page, and then send it out through dataLayer.push.
Configuration Steps
Step 1：Set Up the Trigger(History Change)
In GTM , click「Triggers」——「New」——「Choose a trigger type to begin setup…」——「History Change」，Name it “History Change “, and make the following settings:
Then click Preview, click on any page, and see the Tag Assistant:
Step 2：Set Up Delayed Send
In GTM , click「Tags」——「New」——「Choose a tags type to begin setup…」——「Custom HTML」，Name it “SPA-Delayed Send”, and make the following settings:
The purpose of this configuration is to delay when History Change occurs, ensure that the new page is opened, obtain the accurate webpage title, and then send the data through dataLayer.push.
Step 3：Set Up the Data Layer Variable
In GTM, click「 Variables」——「New」——「Choose a variable type to begin setup…」——「Data Layer Variable」, name it “dlv—pagePath”, and then set as follows:
Use the same method to set dlv-pageTitle and dlv-pageUrl.
Step 4：Set Up the Custom Event
In GTM , click「Triggers」——「New」——「Choose a trigger type to begin setup…」——「Custom Event」，Name it “Custom Event—Pageview “, and make the following settings:
Step 5：Set Up the Tag
We first need to set up a Google Tag. There is no need to set trigger conditions.
In GTM , click「Tags」——「New」——「Choose a tags type to begin setup…」——「Google Analytics」——「Google Tag」，Name it “GA4 update”, and make the following settings:
Note: This tag does not require a trigger condition.
In GTM , click「Tags」——「New」——「Choose a tags type to begin setup…」——「Google Analytics」——「Google Analytics: GA4 Event」，Name it “GA4-Page View Event”, and make the following settings:
GA4 update is triggered before GA4-Page View Event and is mainly used to update configuration parameters:
How to Track Normal Page Loads
If normal page loads do not trigger “History”, then you need to configure a separate Google Tag to track, just the normal GA4 page tracking, such as:
If a normal page load triggers “History”, then the normal page will be merged into the GA4-Page View Event to trigger tracking, but we still need to trigger the Google Tag, load the basic configuration, but do not send the page_view event, just set send_page_view to false:
Advantages
- More flexibility: allows custom page_location and page_referrer, suitable for complex SPA.
- No need for extensive development work: only need to configure GTM, no need to modify website code
Disadvantages
- Data loss: If the delay is too long, the user will leave during the delay and quickly access the next page, which may cause data loss; if the delay is too short, there will still be problems with inaccurate URLs and page titles.
Applicable scenarios
The History Change trigger condition is suitable for SPAs whose URLs change frequently and require custom page parameters, but still rely on the History API.
