Справка по очереди команд 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]);

Параметры

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

Возвращаемое значение

undefined

Примеры

// 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 Аналитику.

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

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

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

Возвращаемое значение

undefined

Примеры

// 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);

Параметры

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

Возвращаемое значение

undefined

Примеры

// 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 Advertising Features plugin
// 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');