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 Display 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.