The analytics.js library provides two main objects to interact with Google Analytics. Each object contains various methods:
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|Boolean 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.