How analytics.js Works

Almost everything you need to measure with analytics.js can be done using the ga() command queue. This guide explains what the command queue is, how it works, and how to execute commands to measure user interactions.

The ga command queue

The Google Analytics tag defines a global ga function known as the "command queue". It's called the command queue because rather than executing the commands it receives immediately, it adds them to a queue that delays execution until the analytics.js library is fully loaded.

In JavaScript, functions are also objects, which means they can contain properties. The Google Analytics tag defines a q property on the ga function object as an empty array. Prior to the analytics.js library being loaded, calling the ga() function appends the list of arguments passed to the ga() function to the end of the q array.

For example, if you were to run the Google Analytics tag and then immediately log the contents of ga.q to the console, you'd see an array, two items in length, containing the two sets of arguments already passed to the ga() function:

console.log(ga.q);

// Outputs the following:
// [
//   ['create', 'UA-XXXXX-Y', 'auto'],
//   ['send', 'pageview']
// ]

Once the analytics.js library is loaded, it inspects the contents of the ga.q array and executes each command in order. After that, the ga() function is redefined, so all subsequent calls execute immediately.

This pattern allows developers to use the ga() command queue without having to worry about whether or not the analytics.js library has finished loading. It provides a simple, synchronous-looking interface that abstracts away most of the complexities of asynchronous code.

Adding commands to the queue

All calls to the ga() command queue share a common signature. The first parameter, the "command", is a string that identifies a particular analytics.js method. Any additional parameters are the arguments that get passed to that method.

The method a particular command refers to can be a global method, like create, a method on the ga object, or it can be an instance method on a tracker object, like send. If the ga() command queue receives a command it doesn't recognize, it simply ignores it, making calls to the ga() function very safe, as they will almost never result in an error.

For a comprehensive list of all commands that can be executed via the command queue, see the ga() command queue reference.

Command parameters

Most analytics.js commands (and their corresponding methods) accept parameters in a number of different formats. This is done as a convenience to make it easier to pass commonly used fields to certain methods.

As an example, consider the two commands in the Google Analytics tag:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

In the first command, create accepts the fields trackingId, cookieDomain, and name to optionally be specified as the second, third, and fourth parameters, respectively. The send command accepts an optional hitType second parameter.

All commands accept a final fieldsObject parameter that can be used to specify any fields as well. For example, the above two commands in the tag could be rewritten as:

ga('create', {
  trackingId: 'UA-XXXXX-Y',
  cookieDomain: 'auto'
});
ga('send', {
  hitType: 'pageview'
});

See the ga() command queue reference for a comprehensive list of the optional parameters allowed for each of the commands.

Next steps

After reading this guide you should have a good understanding of how to execute commands with analytics.js, and how the command queue works. The next guide will cover how to create tracker objects.