Autotrack Documentation

The socialWidgetTracker plugin automatically tracks user interactions with official Twitter tweet/follow buttons and the Facebook like button. To enable it, use the ga('require', ...) command.

In most cases, no customization is required.

ga('require', 'socialWidgetTracker');

To use Autotrack with a standard tracking snippet, follow these two steps:

1. Load the autotrack.js file on your page.
2. Use the ga('require', 'pluginName') command in your tracking snippet to enable the plugins you want.

Note: autotrack.js can be loaded before or after analytics.js due to the asynchronous nature of the plugin system.

<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXX-Y', 'auto');

// Enable specific plugins
ga('require', 'eventTracker');
ga('require', 'outboundLinkTracker');
ga('require', 'urlChangeTracker');

ga('send', 'pageview');
</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
<script async src="path/to/autotrack.js"></script>

If you use a module loader that supports ES2015 imports (like Webpack or Rollup), you can install Autotrack via npm.

Important: Autotrack source is published as ES2015; ensure your build process does not exclude it from compilation.

To include all plugins, import autotrack. To reduce bundle size, import only the specific plugins you need from autotrack/lib/plugins/.

npm install autotrack

// To include all plugins
import 'autotrack';

// To include specific plugins only
import 'autotrack/lib/plugins/event-tracker';
import 'autotrack/lib/plugins/outbound-link-tracker';
import 'autotrack/lib/plugins/url-change-tracker';

// After importing, you must still require them on the tracker
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'eventTracker');
ga('require', 'outboundLinkTracker');
ga('require', 'urlChangeTracker');

ga('send', 'pageview');

To effectively use the data from pageVisibilityTracker, create a custom metric in Google Analytics called Page Visible Time (using the index provided in visibleMetricIndex).

You can then create calculated metrics to analyze engagement:

• Avg. Page Visible Time (per Session): Use this for session-level dimensions (e.g., Referrer, Device Category).

  • Formula: {{Page Visible Time}} / {{Sessions}}

• Avg. Page Visible Time (per Page): Use this for page-specific dimensions (e.g., Page, Title).

  • Formula: {{Page Visible Time}} / {{Unique Pageviews}}

When using stripQuery: true, site search parameters (like q) will be removed from the page field. Since Google Analytics does not automatically infer site search from the location field when a page field is present, you must whitelist these parameters using queryParamsWhitelist to ensure search data is still captured.

ga('require', 'cleanUrlTracker', {
  stripQuery: true,
  queryParamsWhitelist: ['q'],
});

The mediaQueryTracker plugin tracks responsive design media queries and sends them to Google Analytics as custom dimensions. It also sends event hits when media query values change (e.g., when a user resizes their browser).

To enable the plugin, use the ga('require', ...) command with a configuration object containing definitions.

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

When upgrading to version 2.x.x, be aware of the following breaking changes:

• Module Syntax: The source code now uses ES2015 module syntax to enable tree shaking. This may cause compatibility issues with bundlers that do not natively support this syntax, such as older versions of Browserify.
• cleanUrlTracker: Calls to tracker.get('page') will now return the 'cleaned' version of the page.
• impressionTracker: Events sent by this plugin are now nonInteraction by default.
• pageVisibilityTracker:
  • The change event action is no longer used. Instead, events with a track action are sent when the page transitions out of the visible state to record visibility time.
  • The changeTemplate option has been removed.
  • The hiddenMetricIndex option has been removed.

The urlChangeTracker plugin detects URL changes via the History API and automatically sends pageview hits. This is designed for Single Page Applications (SPAs) to track navigation without manual configuration.

Note: This plugin does not support tracking hash changes. Ensure your SPA framework is not already tracking URL changes to avoid duplicate data.

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

The pageVisibilityTracker plugin improves engagement measurement by using the Page Visibility API instead of relying solely on page loads. It tracks how long a page is visible and can automatically trigger new sessions or pageviews when a user returns to a tab.

To enable the plugin, use the ga('require', ...) command. If you configure the plugin to handle the initial pageview, you must remove the manual ga('send', 'pageview') command from your tracking snippet to avoid duplicate hits.

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