Справка по методам – Веб-отслеживание (analytics.js)

Библиотека analytics.js предлагает два основных объекта для взаимодействия с Google Analytics, у каждого из которых есть свои методы.

Методы объекта ga

Когда вы размещаете на странице фрагмент кода JavaScript analytics.js, он создает глобальный объект ga. На его основе разработчики создают объекты трекера, которые затем передают данные на веб-ресурс.

create

Создает новый объект трекера по умолчанию.

ga('create', trackingId, opt_configObject);

Параметры

  • String trackingId – идентификатор веб-ресурса отслеживаемого сайта.
  • Object opt_configObject – необязательный объект, содержащий конфигурацию пар "поле/значение".

Примеры

Создание трекера по умолчанию:

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

Создание трекера с использованием собственного имени файла cookie:

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

Создание трекера с использованием синхронного синтаксиса:

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

ga('create', ...) может принимать как аргументы позиции, так и аргументы объекта в полях trackingId, cookieDomain и name. Порядок их следования имеет значение. Например, следующие два фрагмента идентичны:

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

getByName

Возвращает объект трекера с заданным именем или нулевое значение, если такого объекта нет.

ga.getByName(name);

Параметры

  • String name – имя запрашиваемого объекта трекера.

Что будет возвращено

  • Tracker – объект отслеживания.

Пример

Этот код возвращает объект трекера с именем shoehorn:

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

getAll

Возвращает массив, содержащий все существующие объекты трекера в том порядке, в котором они были созданы.

ga.getAll();

Что будет возвращено

  • Array<Tracker> – массив со всеми объектами трекера.

Пример

Этот код возвращает все объекты отслеживания с указанием их имен:

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

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

Методы объекта трекера

Создав объект трекера с помощью метода create, используйте следующие методы для взаимодействия с Google Analytics.

send

Отправляет маркер отслеживания на серверы Google. Необязательный объект поля позволяет перезаписать одно или несколько значений полей только для этого обращения.

ga('send', hitType, opt_fieldObject);

Параметры

Пример

Отправка обращения типа pageview (просмотр страницы) и переопределение заголовка страницы:

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

set

Обновляет значение, связанное с данным полем. Метод set можно вызывать с одним полем и значением:

ga('set', fieldName, value);

Параметры

  • String fieldName – название устанавливаемого поля.
  • String|Number|Object|Boolean value – новое значение, присваиваемое полю.

Чтобы обновить значения нескольких полей, вызовите метод set с объектом, содержащим несколько пар "поле/значение".

ga('set', fieldObject);

Установленные значения будут использоваться при всех последующих вызовах метода send на протяжении жизненного цикла объекта трекера.

Параметры

  • Object fieldObject – объект, содержащий одну или несколько пар "поле/значение" для записи.

Примеры

Установка поля page для всех последующих обращений:

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

Установка полей page и title для всех дальнейших обращений:

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

get

Возвращает значение, в данный момент присвоенное этому полю. Этот метод следует вызывать для экземпляра объекта трекера.

var fieldValue = tracker.get(fieldName);

Параметры

  • String fieldName – название поля.

Что будет возвращено

  • String|Number|Object – значение поля.

Пример

Этот код позволяет получить текущую страницу трекера:

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

Эта функция будет выполнена, как только загрузится библиотека analytics.js. Параметр tracker будет ссылаться на трекер по умолчанию (при условии, что он был создан до вызова функции). Затем эта ссылка используется для получения значения page.

Синтаксис вызова

Далее описывается, как вызвать каждый метод объекта ga.

Асинхронный вызов (трекер по умолчанию)

Фрагмент кода anaytics.js загружается асинхронно, чтобы браузер не приостанавливал свою работу во время загрузки библиотеки. Чтобы не синхронизировать свой код с загрузкой библиотеки, вы можете использовать объект ga в качестве функции. Для этого передайте название метода в первом параметре:

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

Как только завершится загрузка библиотеки, метод create создаст объект трекера по умолчанию t0, в отношении которого будет выполнен метод send (или любой другой метод, вызванный с помощью этого синтаксиса).

В данном случае объект трекера по умолчанию создается для удобства реализации.

Асинхронный вызов (трекер с именем)

Иногда на одной странице может понадобиться создать несколько трекеров. Чтобы их различать, вам нужно будет присвоить имя каждому дополнительному трекеру.

Чтобы создать объект трекера с именем, задайте поле конфигурации name, используя параметр объекта конфигурации метода create.

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

Затем вызовите методы трекера для проименованных трекеров. Для этого поставьте перед каждым методом имя трекера и точку (.):

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

Синхронный вызов

Библиотека anaytics.js поддерживает также и синхронные вызовы. В этом случае вы выполняете методы напрямую над объектами ga или tracker:

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

Асинхронная синхронизация

Некоторые методы необходимо вызывать только после загрузки библиотеки. Например, метод get сработает только после того, как будет загружена библиотека, создан трекер и установлены все необходимые поля. В этом случае вы можете передать объекту ga функцию, которая будет выполнена только по завершении загрузки библиотеки:

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

Эта функция принимает параметр, который после ее выполнения будет иметь значение трекера по умолчанию. Затем этот объект трекера можно использовать с синхронным синтаксисом. Пример:

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

Аналогичным образом можно отслеживать просмотры страниц на всех трекерах, которые вы создали:

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

Это особенно полезно, если вы хотите создать расширения, поскольку в этом случае вам может быть неизвестно, сколько трекеров имеется на сайте. Благодаря использованию этого синтаксиса функция сможет выполнять много дополнительных логических схем для каждого трекера на странице, после того как загрузится код отслеживания.