The ga Command Queue Reference

The ga() command queue provides an interface for doing almost everything you need to do with the analytics.js library.

The JavaScript tracking snippet defines the initial ga() command queue function, so it can be used even before the analytics.js library is fully loaded. As soon as the analytics.js library is loaded, the items in the command queue are executed in the order they were received. Once this is done, new commands pushed onto the queue are executed immediately.

In order to keep the tracking snippet as small as possible, the ga() command queue is overloaded to accept arguments in many different formats. This document details all the various ways the ga() command queue function can be invoked.

Function signature
ga(command, [...fields], [fieldsObject])

Invoking the ga() command queue function with the following function signature will push commands onto the queue to be scheduled for execution once the library is loaded.

ga(readyCallback)

Invoking the ga() command queue function by passing it a function will schedule the passed function for execution at the next point in the queue.

Since commands are only executed after the analytics.js library is fully loaded, the most common reason to pass the command queue a function is as a callback for when the analytics.js library is loaded and ready.

Adding commands to the queue

Invoking the ga() command queue function with the following function signature will push commands onto the queue to be scheduled for execution once the library is loaded.

Usage

ga(command, [...fields], [fieldsObject])

Parameters

Name Type Required Description
command string yes

An identifier representing the command to add to the queue. The identifier is made up of three parts (the first two being optional):

[trackerName.][pluginName:]methodName
trackerName The name of the tracker to invoke the scheduled command on. If no tracker name is specified, the command is invoked on the default tracker.
pluginName The name of an analytics.js plugin that has been required. If pluginName is specified, the methodName must be a method provided by the plugin.
methodName The name of the method to be scheduled for execution. When not specifying a plugin name, this method must be one of the command methods listed below.
...fields * no One or more optional convenience parameters for quickly specifying common fields. The number of and specific fields allowed varies depending on the command method being called.
fieldsObject Object no

An object for specifying any remaining values not specified in any of the fields parameters.

If a field is set in both a fields parameter and fieldsObject, the value in fieldsObject will be used.

See the field reference for individual field documentation.

Examples

See the command methods section below for individual command examples.

Ready callback

Invoking the ga() command queue function by passing it a function will schedule the passed function for execution at the next point in the queue.

Since commands are only executed after the analytics.js library is fully loaded, the most common reason to pass the command queue a function is as a callback for when the analytics.js library is loaded and ready.

Usage

ga(readyCallback)

Parameters

Name Type Required Description
readyCallback Function yes

A callback function to be invoked when the library is fully loaded and ready to be interacted with. The function is invoked with the default tracker object as it first argument. If no default tracker has been created, the first argument is undefined.

Note: when the callback function is invoked, all ga object methods are available for use.

Examples

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});
// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

Command method details

The following is a list of all methods that can be passed to the ga() command queue (excluding plugin methods).

create

Creates a new tracker instance with the specified fields.

Usage

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

Parameters

See the field reference for individual field documentation.

Returns

undefined

Examples

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

Sends a hit to Google Analytics.

Usage

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

The fields that are sent are the values specified in the ...fields parameters and fieldsObject, merged with the fields currently stored on the tracker.

Parameters

The fields that can be specified by the ...fields parameters vary depending on the hit type. The following table lists the fields that correspond to each hit type. Hit types not listed do not accept ...fields parameters, only the fieldsObject.

Hit type ...fields
pageview page
event eventCategory, eventAction, eventLabel, eventValue
social socialNetwork, socialAction, socialTarget
timing timingCategory, timingVar, timingValue, timingLabel

See the field reference for individual field documentation.

Returns

undefined

Examples

// Sends a pageview hit.
ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

Sets a single field and value pair or a group of field/value pairs on a tracker object.

Usage

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

Parameters

See the field reference for individual field documentation.

Returns

undefined

Examples

// Sets the page field to "/about.html".
ga(set, 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About".
ga(set, {
  page: '/about.html',
  title: 'About'
});

require

Requires an analytics.js plugin.

Usage

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

Parameters

Name Type Required Description
pluginName string yes The name of the plugin to be required. Note: if the plugin is not an official analytics.js plugin, it must be provided elsewhere on the page.
pluginOptions Object no An initialization object that will be passed to the plugin constructor upon instantiation.

Returns

undefined

Example

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Display Features plugin for the tracker
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

Provides an analytics.js plugin and its methods for use with the ga() command queue.

ga('provide', pluginName, pluginConstuctor);

Parameters

Name Type Required Description
pluginName string yes The name of the plugin being provided. The name used must be the same name used by any require calls.
pluginConstuctor Function yes A constructor function the provides all of the plugin logic and methods. This constructor will be invoked with the pluginsOptions object specified in the require method.

Example

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

Removes a tracker object.

Usage

ga('[trackerName.]remove');

Examples

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');