This guide describes how to use analytics.js to track pages 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 analytics.js snippet code 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 you're loading 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 tracked manually as new content is loaded.
Tracking virtual pageviews
To track dynamically loaded content as distinct pageviews you can send a
pageview hit to Google Analytics and specify the
Document Path by setting the page field.
ga('send', 'pageview', '/new-page');
The page field represents the path portion of a URL and should
begin with a slash. Usually the page value is the same as the
path portion of the URL shown in the browser's address bar, but it doesn't
have to be. Since websites that load content dynamically often only update the
hash portion of the URL as the user navigates, several different URL paths may
point to the same resource. In these 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 track all of these
pageviews as /about.html.
Setting page data for multiple hits
Specifying a page value in a pageview hit will send that
page value to Google Analytics for that hit only; it will not
update the page value stored on the tracker object itself. This
can be problematic if you send other hits (e.g. events or social hits) and
don't explicitly include the current page value. In
such cases, Google Analytics will associate those hits with whatever URL was
present at the time of the initial page load.
To avoid this issue, it's usually best to update the tracker object with any new page information prior to sending hits. This will ensure that all hits are associated with the correct page data.
To update the tracker object, use the
set method:
ga('set', 'page', '/new-page');
If you want to update more than just the page field, you can
pass an object of key/value pairs to the set method.
ga('set', {
page: '/new-page',
title: 'New Page'
});
Once the tracker has been updated with the proper data for the new page, you can send a hit without overriding page related parameters. For example:
ga('send', 'pageview');
What not to do
Do not update the document referrer
When you create a tracker object via the
create method, 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 will often 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 tracking 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 analytics.js snippet code does for traditional websites. Doing so runs the risk of sending an incorrect referrer as well as incorrect campaign data as described above.