This guide describes how to use analytics.js to measure page activity on sites whose content is loaded dynamically without traditional full page loads.
A Single Page Application (SPA) is a web application or website that loads all of the resources required to navigate throughout the site on the first page load. As the user clicks links and interacts with the page, subsequent content is loaded dynamically. The application will often update the URL in the address bar to emulate traditional page navigation, but another full page request is never made.
The default Google Analytics tag works well with traditional websites because the snippet code is run every single time the users load a new page. However, for a single page application where the site loads new page content dynamically rather than as full page loads, the analytics.js snippet code only runs once. This means subsequent (virtual) pageviews must be captured manually as new content is loaded.
Tracking virtual pageviews
When your application loads content dynamically and updates the URL in the address bar, the data stored on your tracker should be updated as well.
To update the tracker, use the
set command and supply the new
ga('set', 'page', '/new-page.html');
After you've set the new page value, all subsequents hits sent will use that new value. To record a pageview, send a pageview hit immediately after updating the tracker.
ga('set', 'page', '/new-page.html'); ga('send', 'pageview');
While technically the
send command for pageview hits accepts an optional
page field as the third parameter, passing the
page field that way is not recommended when measuring single page applications. This is because fields passed via the
send command are not set on the tracker—they apply to the current hit only. Not updating the tracker will cause problems if your application sends any non-pageview hits (e.g. events or social interactions), as those hits will be associated with whatever
page value the tracker had when it was created.
Handling multiple URLs for the same resource
Some SPAs only update the hash portion of the URL when loading content dynamically. This practice can lead to situations where many different page paths point to the same resource. In such cases, it's usually best to choose a canonical URL and only ever send that
page value to Google Analytics.
For example, consider a website whose "About Us" page can be reached via any of the following URLs:
To avoid duplication in your reports, it's best to capture all of these pageviews as
Do not update the document referrer
When you create a tracker object using the
create command, the value of
document.referrer is stored on the tracker's
referrer field. In the context of a single page application that doesn't use full page loads, the
referrer field will always stay the same.
Despite this, it is not necessary to update the referrer field manually prior to sending pageview hits. Google Analytics is able to automatically determine the correct navigation path.
Do not update the document location
In the same way that the tracker uses
document.referrer for the
referrer field, it uses
document.location for the
location field, which may contain campaign data or other meta data in the form of query parameters appended to the end of the URL.
Updating any of the campaign fields or other meta data that Google Analytics is checking for may cause the current session to end and a new session to begin. To avoid this problem, do not update the
location field when measuring virtual pageviews in a single page application. Use the
page field instead.
Do not create new trackers