Writing Plugins

Plugins are scripts that enhance the functionality of analytics.js to help solve problems and aid in measuring user interaction. This guide describes the process of writing your own analytics.js plugins. For information about how to use analytics.js plugins in your own implementations, see Using plugins.

Defining a plugin

Plugins are defined via the provide command, which must be invoked with the name of the plugin as the first argument followed by the plugin's constructor function. When the provide command is run, it registers the plugin to be used with the ga() command queue.

Plugins need to function correctly even in cases where the global ga object has been renamed, so if you're writing a plugin for third-party use, you should include a check to see if the GoogleAnalyticsObject variable has been set to a string other than 'ga'. The following providePlugin function does this:

Configuring Plugin Instances

When the ga() command queue executes a require command, it instantiates a new object using the new operator on the provide plugin's constructor function. The constructor is passed the tracker object as its first argument, and any configuration options passed to the require command as its second argument.

Consider the following require command added to the JavaScript tracking snippet:

When the require command is run, the following will be logged to the console (note that the name of the default tracker is "t0"):

// localHitSender enabled for path: /log
// on tracker: t0

Defining Plugin Methods

Plugins can expose their own methods which can be invoked using the ga command queue syntax:

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

where trackerName is optional and methodName corresponds to the name of a function on the plugin constructors prototype. If methodName does not exist on the plugin or the plugin does not exist, an error will occur.

Loading plugins

Plugins are typically loaded from a separate JavaScript file or bundled together with your main application code.

<script async src="myplugin.js"></script>

Plugins do not necessarily need to be defined before they are required. Since analytics.js is loaded asynchronously and plugins are often also loaded asynchronously, the ga() command queue is built to handle this.

If the command queue receives a require command for a plugin that has not yet been provided, it will halt execution of the remaining items in the queue until the plugin is available.

The following code shows how the ga('require', 'myplugin') command is not actually executed until the ga('provide', 'myplugin', ...) command is encountered, three seconds later.

Important!
While order of the require and provide commands is not important, they cannot be called before the JavaScript tracking snippet is run since they both reference to the global ga command queue function.

Examples

The following example plugin is designed to capture custom campaign values from a page's URL and pass them to the tracker. This plugin demonstrates how to define and register a plugin script, pass plugin configuration parameters, and define and call plugin methods.

Autotrack plugins

The autotrack library is open source, available on GitHub, and includes several analytics.js plugins that aid in tracking common user interactions. Refer to the autotrack source code to get a better understanding of how plugins work.