Google Analytics

Method Reference - Web Tracking (analytics.js)

The analytics.js library provides two main objects to interact with Google Analytics. Each object contains various methods:

  1. ga Object Methods
    1. create
    2. getByName
    3. getAll
  1. Tracker Object Methods
    1. send
    2. set
    3. get
  1. Calling Syntax
    1. Async (default tracker)
    2. Async (named tracker)
    3. Sync
    4. Asynchronous Synchronization

ga Object Methods

When you include the default analytics.js JavaScript snippet on your page it creates a global object named ga. Developers use the ga object to create tracker objects that in turn, send data to a Google Analytics Web Property.

create

Creates a new default tracker object.

ga('create', trackingId, opt_configObject);

Parameters

  • String trackingId – The web property ID for the site being tracked.
  • Object opt_configObject – An optional object containing configuration field/value pairs.

Examples

Create a default tracker.

ga('create', 'UA-XXXX-Y', 'auto');

Create a tracker using a custom cookie name.

ga('create', 'UA-XXXX-Y', 'auto', {'cookieName': '_ga2'});

Create a tracker using the Synchronous syntax:

var tracker = ga.create('UA-XXXX-Y', 'auto');

ga('create', ...) can accept both position arguments and object arguments for the trackingId, cookieDomain and name fields. Order is important. For example, the following two snippets are identical:

ga('create', 'UA-XXXX-Y', 'auto', 'T1000');
ga('create', {trackingId: 'UA-XXXX-Y', cookieDomain: 'auto', name: 'T1000'});

getByName

Returns the tracker object with the given name, or null if no tracker object with the given name currently exists.

ga.getByName(name);

Parameters

  • String name – Name of the tracker to fetch.

Returns

  • Tracker – A tracker object.

Example

Return the tracker object named shoehorn:

ga(function() {
  var tracker = ga.getByName('shoehorn');
});

getAll

Returns an array containing all the tracker objects that currently exist, in the order they were created.

ga.getAll();

Returns

  • Array<Tracker> – An array of all tracker objects.

Example

Return all tracker objects and alert their names:

ga(function() {
  var trackers = ga.getAll();

  for (var i=0; i < trackers.length; ++i) {
    var tracker = trackers[i];
    alert(tracker.get('name'));
  }
});

Tracker Object Methods

Once a tracker object has been created using the create method, the following methods can be used to interact with Google Analytics.

send

Sends a tracking beacon to Google’s collection servers. The optional field object allows users to override one or more field values for this hit only.

ga('send', hitType, opt_fieldObject);

Parameters

  • String hitType – The type of hit to send. This supported values are:
  • Object opt_fieldObject – An object containing one or more field/value pairs used to override a field value for this hit only. Fields will revert to their original values after the hit is complete.

Example

Send a pageview type hit, and override the page title.

ga('send', 'pageview', {'title': 'my new title'});

set

Updates the value currently associated with the given field. The set method can be called with a single field and value:

ga('set', fieldName, value);

Parameters

  • String fieldName – Name of the field to set.
  • String|Number|Object value – New value to associate with the given field.

You can also call set with an object containing multiple field/value pairs for bulk updating.

ga('set', fieldObject);

The values that are set will persist with all the subsequent send calls for the lifetime of the tracker object.

Parameters

  • Object fieldObject – An object containing one or more field/value pairs to set.

Examples

Setting the page field for all subsequent hits:

ga('set', 'page', '/my-new-page');

Setting both the page and title for all subsequent hits:

ga('set', {
  'page': '/my-new-page',
  'title': 'my new title'
});

get

Returns the value currently associated with the given field. This should be called on an instantiated tracker object.

var fieldValue = tracker.get(fieldName);

Parameters

  • String fieldName – Name of the field to retrieve.

Returns

  • String|Number|Object – The value of the field.

Example

Get the current page of a tracker:

ga(function(tracker) {
  var page = tracker.get('page');
});

This function will execute once the analytics.js library has loaded. When the function executes, the tracker parameter will have a reference to the default tracker (assuming it was created prior to the function being called). The tracker reference is then used to get the page value.

Calling Syntax

There are a couple of ways you can call each of the ga methods.

Asynchronous (default tracker)

The anaytics.js JavaScript snippet is designed to load asynchronously to prevent browsers from pausing to load the library. So that you do not have to synchronize your code around the library load, you can use the ga object like a function by passing the method name as the first parameter:

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

This will execute as soon as the library is done loading. The create method will create a default tracking object named t0. Then the send method, or any other method called using this syntax, will be executed on the default tracking object.

In this case, the creation of a default tracker object is done as a convenience for most implementations.

Asynchronous (named tracker)

In some cases, you might want to create multiple trackers on the same page. To differentiate between trackers, you must name each additional tracker.

You create a named tracker object by setting the name configuration field using the optional configuration object parameter of the create method.

ga('create', 'UA-XXXX-Y', 'auto', {'name': 'tracker2'});

You then call the tracker methods on named trackers by prepending the methods with the tracker name and a . (dot):

ga('tracker2.send', 'pageview');

Synchronous

The anaytics.js library also supports a synchronous way to call methods. In this case, you call the methods directly on the ga or tracker objects respectively:

var tracker = ga.create('UA-XXXX-Y', 'auto');
tracker.send('pageview');

Asynchronous Synchronization

In some cases, certain methods need to be called only once the library has loaded. For example, the get method will only work once the library has loaded, the tracker created, and the fields are set. To solve this, you can pass the ga object a function that will only execute once the library has loaded:

ga(function(tracker) {
  var page = tracker.get('name');
});

The function you pass to the ga object accepts a parameter, that, once executed, will have the value of the default tracker. The tracker object can then be used with the synchronous syntax. For example, this also works:

ga('create', 'UA-XXXX-Y', 'auto');
ga(function(tracker) {
  tracker.send('pageview');
});

Similarly, to track a pageview on all trackers that have been created, you can use:

ga(function() {
  var trackers = ga.getAll();
  for (var i=0; i<trackers.length; ++i) {
    var tracker = trackers[i];
    tracker.send('pageview');
  }
});

This can be especially useful if you want to develop extensions where you might not know how many trackers were created on a site. Using this syntax, the function can execute a lot of additional logic, for every tracker on the page, once the tracking code has loaded.







Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.