Getting and Setting Field Data

Getting and setting field data on a tracker sometimes requires having a reference to the tracker object itself. Since commands added to the ga() command queue execute asynchonously and do not return a value, and since trackers are most commonly created using the create command, getting a reference to a tracker object requires waiting until after the create command has been executed. You can do this via the ready callback.

The ready callback

The ready callback is a function that you can add to the ga() command queue. The function will be invoked as soon as the analytics.js library is fully loaded, and all previous commands added to the queue have been executed.

Since all commands to the queue are executed in order, adding a ready callback to the queue after adding a create command will ensure that the ready callback is executed after the tracker has been created. If a default tracker has been created when a ready callback is invoked, it is passed as the callback's first (and only) argument.

The following code shows how to access the default tracker object and log it to the console:

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

ga(function(tracker) {
  // Logs the tracker created above to the console.
  console.log(tracker);
});

Getting trackers via ga Object methods

If you're not using a default tracker, or if you have more than one tracker on the page, you can access those trackers via one of the ga object methods.

Once the analytics.js library is fully loaded, it adds additional methods to the ga object itself. Two of those methods, getByName and getAll, are used to access tracker objects.

getByName

If you know the name of the tracker you want to access, you can do so using the getByName method:

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

ga(function() {
  // Logs the "myTracker" tracker object to the console.
  console.log(ga.getByName('myTracker'));
});

getAll

To get an array of all created trackers, use the getAll method:

ga('create', 'UA-XXXXX-Y', 'auto', 'tracker1');
ga('create', 'UA-XXXXX-Z', 'auto', 'tracker2');

ga(function() {
  // Logs an array of all tracker objects.
  console.log(ga.getAll());
});

Getting data stored on a tracker

Once you have a reference to a tracker object, you can use its get method to access the value of any field currently stored on the tracker.

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

ga(function(tracker) {
  // Logs the trackers name.
  // (Note: default trackers are given the name "t0")
  console.log(tracker.get('name'));

  // Logs the client ID for the current user.
  console.log(tracker.get('clientId'));

  // Logs the URL of the referring site (if available).
  console.log(tracker.get('referrer'));
});

Update data

Tracker objects can be updated using the set method. A tracker's set method can be called on a tracker object itself or by adding a set command to the ga() command queue.

Since getting a reference to a tracker object requires using the ready callback, using the ga() command queue is the recommended way to update a tracker.

The ga() command queue

The set command can be invoked in two ways: by passing two parameters, a field and its corresponding value, or by passing an object of field/value pairs.

The following example sets the page field to '/about' on the default tracker:

ga('set', 'page', '/about');

This example sets the page and title fields at the same time:

ga('set', {
  page: '/about',
  title: 'About Us'
});

Using a named tracker

If you're using a named tracker instead of the default tracker, you can pass its name in the command string.

The following call sets the page field on the tracker named "myTracker":

ga('myTracker.set', 'page', '/about');

On the tracker object itself

If you have a reference to the tracker object, you can call that tracker's set method directly:

ga(function(tracker) {
  tracker.set('page', '/about');
});

Ampersand syntax

Tracker fields are usually get and set using their field names. (Refer to the field reference for a complete list of analytics.js fields and their names.)

An alternative way to get and set fields is to refer to them by their corresponding Measurement Protocol parameter names names.

For example, the following two console.log expressions both log the document title to the console:

ga(function(tracker) {
  // Gets the title using the analytics.js field name.
  console.log(tracker.get('title'));

  // Gets the title using the measurement protocol
  // parameter name, prefixed with an ampersand.
  console.log(tracker.get('&dt'));
});

In general, ampersand syntax is not recommended and should only be used when the analytics.js field name for a Measurement Protocol parameter does not exist (this occassionally happens if a new feature is added to the Measurement Protocol before it is implemented in analytics.js).

Next steps

Now that you know how to create trackers and update the data stored on them, the next step is to learn how to send that data to Google Analytics for processing.