Single Page Application Tracking

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 JavaScript tracking snippet 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 tracked manually as new content is loaded.

Note:
Developers creating Single Page Applications can use autotrack, which includes a urlChangeTracker plugin that handles all of the important considerations listed in this guide for you. See the autotrack documentation for usage and installation instructions.

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 tracking 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 track 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 tracking virtual pageviews in a single page application. Use the page field instead.

Note:
If you send a hit that includes both the location and page fields and the path values are different, Google Analytics will use the value specified for the page field.

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.