url-change-tracker.md

urlChangeTracker

This guide explains what the urlChangeTracker plugin is and how to integrate it into your analytics.js tracking implementation.

Overview

The urlChangeTracker plugin detects changes to the URL via the History API and automatically updates the tracker and sends additional pageviews. This allows single page applications to be tracked like traditional sites without any extra configuration.

Developers of single page applications should make sure their framework isn't already tracking URL changes to avoid collecting duplicate data.

Note: this plugin does not support tracking hash changes as most Google Analytics implementations do not capture the hash portion of the URL when tracking pageviews.

Usage

To enable the urlChangeTracker plugin, run the require command, specify the plugin name 'urlChangeTracker', and pass in the configuration options (if any) you want to set:

ga('require', 'urlChangeTracker', options);

Options

The following table outlines all possible configuration options for the urlChangeTracker plugin. If any of the options has a default value, the default is explicitly stated:

Name	Type	Description
shouldTrackUrlChange	Function	A function used to determine if a URL change should be tracked. The function is invoked with the string values newPath and oldPath which represent the pathname and search portion of the URL (not the hash portion). Note, the function is only invoked if the new path and old path are different. Default: function shouldTrackUrlChange(newPath, oldPath) { return newPath && oldPath; };
fieldsObj	Object	See the common options guide for the fieldsObj description.
hitFilter	Function	See the common options guide for the hitFilter description.

Default field values

The urlChangeTracker plugin sets the following default field values on all hits it sends. To customize these values, use one of the options described above.

Field	Value
hitType	'pageview'
page	newPath
title	document.title

Note: the reference to newPath in the table above refers to the same value passed to the shouldTrackUrlChange function in the configuration options.

Methods

The following table lists all methods for the urlChangeTracker plugin:

Name	Description
remove	Removes the urlChangeTracker plugin from the specified tracker, removes all event listeners from the DOM, and restores all modified tasks to their original state prior to the plugin being required.

For details on how analytics.js plugin methods work and how to invoke them, see calling plugin methods in the analytics.js documentation.

Example

Basic usage

In most cases, this plugin needs no customization, and should work with all modern web frameworks:

ga('require', 'urlChangeTracker');

Customizing what is considered a URL change

This code updates the shouldTrackUrlChange configuration option to not track changes where only the query string portion of the URL is different:

ga('require', 'urlChangeTracker', {
  shouldTrackUrlChange: function(newPath, oldPath) {
    // Strips the query string from the path values.
    newPath = newPath.split('?')[0];
    oldPath = oldPath.split('?')[0];

    return newPath != oldPath;
  }
});

Differentiating between virtual pageviews and the initial pageview

If you want to be able to report on pageviews sent by the urlChangeTracker separately from pageviews sent in the initial page load, you can use a custom dimension to add additional metadata to the pageview hit.

The following code uses the fieldsObj option to set a custom dimension at index 1 for all pageview hits sent by the urlChangeTracker plugin:

ga('require', 'urlChangeTracker', {
  fieldsObj: {
    dimension1: 'virtual'
  }
});
ga('send', 'pageview', {
  dimension1: 'page load'
});