Using Plugins

Plugins are scripts that enhance the functionality of analytics.js to aid in measuring user interaction. Plugins are typically specific to a set of features that may not be required by all Google Analytics users, such as ecommerce or cross-domain tracking, and are therefore not included in analytics.js by default.

This guide explains how to require and use analytics.js plugins.

Requiring plugins

The require command takes the name of a plugin and registers it for use with the ga() command queue. If the plugin accepts configuration options, those options can be passed as the final argument to the require command.

The following is the full require command's signature:

ga('[trackerName.]require', pluginName, [pluginOptions]);

For example, here is how you would require the Enhanced Ecommerce plugin for use with the default tracker:

ga('require', 'ec');

And here is how you would require the Advertising Features plugin for a tracker named "myTracker" and pass a configuration option that overrides the default cookie name value:

ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

Loading the plugin code

The require command initializes the plugin methods for use with the ga() command queue, but it does not load the plugin script itself. If you're using a third-party plugin, or writing a plugin yourself, you'll need to manually add the plugin code to the page.

The recommended method for adding plugin code to the page is via a <script> tag with the async attribute set to ensure it doesn't block the loading of other features on your site.

The following code both requires and loads a hypothetical link tracking plugin:

<script>
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'linkTracker');
ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="/path/to/link-tracker-plugin.js"></script>

Waiting for plugins to load

Because both the analytics.js library and analytics.js plugins are loaded asynchronously, it can be a challenge to know when plugins are fully loaded and ready to be used.

The analytics.js library solves this problem by halting the execution of the command queue when it encounters a require command for a plugin that isn't yet loaded. Once the plugin is loaded, queue execution continues as normal.

As a result, it's extremely important that you test the plugins you're using to ensure they load and run correctly. If a plugin fails to load or has an error, it will prevent all subsequent analytics.js commands from executing.

Calling plugin methods

After requiring a plugin, it's methods become available for use with the ga() command queue. Here is the command signature for calling plugin methods:

ga('[trackerName.][pluginName:]methodName', ...args);

For example, the Enhanced Ecommerce plugin's addProduct method can be called like this:

ga('ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

Or on a named tracker by adding the tracker name to the command string:

ga('myTracker.ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

Next steps

If you've read all the guides in this section, you should be familiar with most of the features of analytics.js. The next guide explains how to debug your analytics.js implementations to more easily detect errors and see exactly what your code is doing.