This guide describes how to use analytics.js to measure page activity on sites whose content is loaded dynamically without traditional full page loads.
Overview
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 page
value:
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:
/about.html
/#about.html
/home.html#about.html
To avoid duplication in your reports, it's best to capture all of these pageviews as /about.html
.
Important considerations
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
Do not create new trackers in a single page app in an attempt to mimic what the JavaScript tracking snippet does for traditional websites. Doing so runs the risk of sending an incorrect referrer as well as incorrect campaign data as described above.