Autotrack

• Overview
• Usage
  • Passing configuration options
  • Loading autotrack via npm
  • Using individual plugins
• Plugins
• Configuration Options
• Advanced Usage
  • Custom builds
  • Using autotrack with multiple trackers
• Browser Support
• Translations

Overview

The default JavaScript tracking snippet for Google Analytics runs when a web page is first loaded and sends a pageview hit to Google Analytics. If you want to know about more than just pageviews (e.g. events, social interactions), you have to write code to capture that information yourself.

Since most website owners care about most of the same types of user interactions, web developers end up writing the same code over and over again for every new site they build.

Autotrack was created to solve this problem. It provides default tracking for the interactions most people care about, and it provides several convenience features (e.g. declarative event tracking) to make it easier than ever to understand how people are using your site.

The autotrack.js library is small (3K gzipped), and includes the following plugins. By default all plugins are bundled together, but they can be included and configured separately as well:

Plugin	Description
eventTracker	Declarative event tracking
mediaQueryTracker	Media query and breakpoint tracking
outboundFormTracker	Automatic outbound form tracking
outboundLinkTracker	Automatic outbound link tracking
socialTracker	Automatic and enhanced declarative social tracking
urlChangeTracker	Automatic URL change tracking for single page applications

Disclaimer: autotrack is maintained by the Google Analytics developer relations team and is primarily intended for a developer audience. It is not an official Google Analytics product and does not qualify for Google Analytics premium support. Developers who choose to use this library are responsible for ensuring that their implementation meets the requirements of the Google Analytics Terms of Service and the legal obligations of their respective country.

Usage

To add autotrack to your site, you have to do two things:

1. Load the autotrack.js script file on your page.
2. Update the tracking snippet to require the autotrack plugin.

If your site already includes the default JavaScript tracking snippet, you can replace it with the following modified snippet (note the added require command as well as the additional autotrack.js script):

<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'autotrack');
ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>
<script async src='path/to/autotrack.js'></script>

The analytics.js plugin system is designed to support asynchronously loaded scripts, so it doesn't matter if autotrack.js is loaded before or after analytics.js. It also doesn't matter if the autotrack.js library is loaded individually or bundled with the rest of your JavaScript code.

Passing configuration options

The default behavior of autotrack can be customized via configuration options. You can pass configuration options to autotrack via the require command using the optional third parameter.

For example, you could override the default attributePrefix option as follows:

ga('require', 'autotrack', {
  attributePrefix: 'data-ga-'
});

Loading autotrack via npm

If you use npm and a module loader like Browserify, Webpack, or SystemJS, you can include autotrack in your build by requiring it as you would any other npm module:

npm install autotrack

// In your JavaScript code
require('autotrack');

Note that the above code will include the autotrack plugins in the generated JavaScript file, but it won't register the plugin for use on an analytics.js tracker object. Adding the require command to the tracking snippet is still necessary:

// In the analytics.js tracking snippet
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'autotrack');
ga('send', 'pageview');

Using individual plugins

The autotrack.js source file includes all the plugins described below, but in some cases you might not want to use all of them.

When you require the autotrack plugin, it runs the require command for each of the bundled plugins and passes them a copy of the configuration object it received (if any). To only use select plugins, you can require them individually instead of requiring the autotrack plugin.

For example, to only use the eventTracker and outboundLinkTracker plugins, you can modify the snippet as follows:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'eventTracker');
ga('require', 'outboundLinkTracker');
ga('send', 'pageview');

Individual plugins accept the same set of configuration options as autotrack. Options not relevant to a particular plugin are ignored. To use configuration options when requiring individual plugins, the simplest way is usually to pass each plugin the same object.

var opts = { /* configuration options */ };

ga('require', 'eventTracker', opts);
ga('require', 'outboundLinkTracker', opts);

When only requiring select plugins, it's important to realize that the autotrack.js source file still includes the code for all plugins. To build a custom version of the script with only the desired plugins, see the custom builds section below.

Plugins

eventTracker

The eventTracker plugin adds declarative event tracking for click events on any element with the data-event-category and data-event-action attributes. The attributes data-event-label and data-event-value are also supported (attribute names are customizable).

Options

• attributePrefix

Example

The following element would send an event hit to Google Analytics with the category "video" and the action "play":

<button data-event-category="video" data-event-action="play">Play</button>

mediaQueryTracker

The mediaQueryTracker plugin allows you to track what media query is active as well as how often the matching media query changes.

You can tell the mediaQueryTracker plugin what media query data to look for via the mediaQueryDefinitions configuration option.

Important: unlike the other autotrack plugins, to use the mediaQueryTracker plugin you have to first make a few changes to your property settings in Google Analytics. Here's what needs to be done:

1. Log in to Google Analytics, choose the account and property you're sending data too, and create a custom dimension for each set of media queries you want to track (e.g. Breakpoints, Resolution/DPI, Device Orientation)
2. Give each dimension a name (e.g. Breakpoints), select a scope of hit, and make sure the "active" checkbox is checked.
3. In the mediaQueryDefinitions config object, set the name and dimensionIndex values to be the same as the name and index shown in Google Analytics.

Refer to the mediaQueryDefinitions configuration option documentation for an example definition that will track breakpoint, device resolution, and device orientation data.

Options

• mediaQueryDefinitions

outboundFormTracker

The outboundFormTracker plugin automatically detects when forms are submitted to sites on different domains and sends an event hit. The event category is "Outbound Form", the event action is "submit", and the event label is the value of the form's action attribute.

By default a form is considered outbound if its action is not a relative path and does not contain the current location.hostname value. Note that this means forms pointing to different subdomains within the same higher-level domain are (by default) still considered outbound. This logic can be customized via the shouldTrackOutboundForm configuration option.

Options

• shouldTrackOutboundForm

outboundLinkTracker

The outboundLinkTracker plugin automatically detects when links are clicked with href attributes pointing to sites on different domains and sends an event hit. The event category is "Outbound Link", the event action is "click", and the event label is the value of the link's href attribute.

By default a link is considered outbound if its hostname property is not equal to location.hostname. Note that this means links pointing to different subdomains within the same higher-level domain are (by default) considered outbound. This logic can be customized via the shouldTrackOutboundLink configuration option.

Options

• shouldTrackOutboundLink

socialTracker

The socialTracker plugin adds declarative social interaction tracking for click events on any element with the data-social-network, data-social-action, and data-social-target attributes, similar to the eventTracking plugin.

It also automatically adds social tracking for the official Twitter tweet/follow buttons and the Facebook like button. In other words, if you include official Twitter or Facebook buttons on your page and you're using autotrack (or even just the socialTracker plugin), user interactions with those buttons will be automatically tracked.

The following table outlines the social fields captured:

Widget	Social Network	Social Action	Social Target
Like button	Facebook	like or unlike	The URL of the current page.
Tweet button	Twitter	tweet	The widget's data-url attribute or the URL of the current page.
Follow button	Twitter	follow	The widget's data-screen-name attribute.

urlChangeTracker

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.

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. Also, developers of single page applications should make sure their framework isn't already tracking URL changes to avoid collecting duplicate data.

Options

• shouldTrackUrlChange

Configuration options

The following options can be passed to the autotrack plugin or individual sub-plugins:

attributePrefix

Type: string

Default: 'data-'

The attribute prefix for declarative event and social tracking. The value used after the prefix is a kebab-case version of the field name, for example: the field eventCategory with the prefix 'data-ga-' would be data-ga-event-category.