Справка по очереди команд ga

Очередь команд ga() позволяет выполнять практически любые действия с библиотекой analytics.js.

Изначально функцию очереди команд ga() определяет код отслеживания JavaScript, поэтому ее можно использовать до окончания загрузки библиотеки analytics.js. Когда эта библиотека будет извлечена, элементы очереди команд начнут выполняться в порядке получения. После этого сразу же будут обрабатываться новые команды, передаваемые в очередь.

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

Сигнатура функции
ga(command, [...fields], [fieldsObject])

Вызов функции очереди команд ga() с приведенной сигнатурой передает команды в очередь для выполнения после загрузки библиотеки.

ga(readyCallback)

Вызов функции очереди команд ga() путем передачи в нее функции запланирует выполнение переданной функции в следующей позиции в очереди.

Так как команды выполняются только после полной загрузки библиотеки analytics.js, чаще всего передача функции в очередь выполняется с целью обратного вызова после загрузки библиотеки.

Добавление команд в очередь

Вызов функции очереди команд ga() с приведенной сигнатурой передает команды в очередь для выполнения после загрузки библиотеки.

Использование

ga(command, [...fields], [fieldsObject])

Параметры

Название Тип Обязательно? Описание
command string Да

Идентификатор команды, которую нужно добавить в очередь. Состоит из трех частей (первые две использовать необязательно):

[trackerName.][pluginName:]methodName
trackerName Название счетчика, в котором нужно вызвать запланированную команду. Если оно не указано, команда выполняется в счетчике, заданном по умолчанию.
pluginName Название требуемого плагина analytics.js. Если параметр pluginName содержит значение, в качестве methodName должен быть указан метод, относящийся к этому плагину.
methodName Название метода, который должен быть выполнен. Если название плагина не указано, это должен быть один из перечисленных ниже методов команд.
...fields * Нет Один или несколько задаваемых параметров для быстрого указания общих полей. Количество и тип разрешенных полей зависят от вызываемого метода.
fieldsObject Object Нет

Объект для указания значений, не указанных в параметрах fields.

Если поле задано и в качестве параметра fields, и в качестве объекта fieldsObject, используется значение, заданное в fieldsObject.

Ознакомьтесь с документацией по полям.

Примеры

Примеры команд приводятся в разделе методы команд ниже.

Обратный вызов

Вызов функции очереди команд ga() путем передачи в нее функции запланирует выполнение переданной функции в следующей позиции в очереди.

Так как команды выполняются только после полной загрузки библиотеки analytics.js, чаще всего передача функции в очередь выполняется с целью обратного вызова после загрузки библиотеки.

Использование

ga(readyCallback)

Параметры

Название Тип Обязательно? Описание
readyCallback Function Да

Функция, которая вызывается после полной загрузки и готовности библиотеки. При вызове функции ее первым аргументом является объект счетчика по умолчанию. Если его не существует, первым аргументом является undefined.

При вызове этой функции все методы объекта ga доступны для использования.

Примеры

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});
// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

Сведения о методах команд

Ниже приводится список всех методов, которые можно передать в очередь команд ga() (кроме методов плагинов).

create

Создает новый экземпляр счетчика с указанными полями.

Использование

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

Параметры

Ознакомьтесь с документацией по полям.

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

Не определено

Примеры

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

Отправляет обращение в Google Analytics.

Использование

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

Отправляемые поля представляют собой значения, указанные в параметрах ...fields и fieldsObject. Они объединены с полями, которые содержатся в счетчике.

Параметры

Поля, которые можно определить с помощью параметров ...fields, зависят от типа обращения. В таблице ниже показаны поля для каждого из них. Не перечисленные здесь типы обращений не принимают параметры ...fields, принимая только fieldsObject.

Тип обращения ...fields
pageview (просмотр страницы) page
event eventCategory, eventAction, eventLabel, eventValue
social socialNetwork, socialAction, socialTarget
timing timingCategory, timingVar, timingValue, timingLabel

Ознакомьтесь с документацией по полям.

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

Не определено

Примеры

// Sends a pageview hit.
ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

Устанавливает одну или несколько пар полей и значений в объекте счетчика.

Использование

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

Параметры

Ознакомьтесь с документацией по полям.

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

Не определено

Примеры

// Sets the page field to "/about.html".
ga(set, 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About".
ga(set, {
  page: '/about.html',
  title: 'About'
});

require

Требует наличия плагина analytics.js.

Использование

ga('[trackerName.]require', pluginName, [pluginOptions]);

Параметры

Название Тип Обязательно? Описание
pluginName string Да Название требуемого плагина. Внимание! Если это не официальный плагин analytics.js, он должен быть размещен на странице.
pluginOptions Object Нет Объект инициализации, который передается конструктору плагина при создании инстанции.

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

undefined

Пример

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Display Features plugin for the tracker
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

Предоставляет плагин analytics.js и его методы для использования в очереди команд ga().

ga('provide', pluginName, pluginConstuctor);

Параметры

Название Тип Обязательно? Описание
pluginName string Да Название предоставляемого плагина. Должно совпадать с названиями, которые используются в вызовах require.
pluginConstuctor Function Да Функция конструктора, содержащая логику и методы плагина. При вызове конструктора объект pluginsOptions указывается в методе require.

Пример

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

Удаляет объект счетчика.

Использование

ga('[trackerName.]remove');

Примеры

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');