Документация по API тега Google

API тега Google (gtag.js) содержит единственную функцию gtag() со следующим синтаксисом:

gtag(<command>, <command parameters>);
  • <command> – одна из следующих команд:
  • <command parameters> – параметры, которые передаются в gtag() и зависят от команды (см. справку по командам ниже).

Команды gtag() можно вызывать в любом месте страницы ниже тега Google. Подробнее читайте в статье Как установить тег Google (gtag.js).

config

Эта команда позволяет указывать дополнительные настройки, обычно связанные с определенным продуктом. Но вам эта команда потребуется, только если вы одновременно пользуетесь Google Рекламой и Google Аналитикой.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> – это идентификатор, который однозначно определяет цель обращений, например ресурс Google Аналитики или аккаунт Google Рекламы. <additional_config_info> – одна или несколько пар "параметр-значение".

В этом примере показано, как настроить тег для отправки данных в аккаунт Google Рекламы:

gtag('config', 'TAG_ID');

где "TAG_ID" — идентификатор тега Google.

В примере ниже показано, как настроить тег, который передает в аккаунт Google Аналитики дополнительную информацию о настройках с помощью параметра send_page_view со значением false и параметра groups со значением 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

Позволяет получать различные значения из gtag.js, включая значения, заданные с помощью команды set.

gtag('get', '<target>', '<field_name>', callback)
Аргумент Тип Пример Описание
<target> string G-XXXXXXXXXX

Целевой источник значений.
<field_name> FieldName client_id Название получаемого поля.
callback Function (field) => console.log(field)

Функция, которая вызывается с помощью запрашиваемого поля, или undefined, если поле не задано.

FieldName

Названием поля может быть значение, заданное в дополнительном поле с помощью команды gtag('set'), или одно из следующих значений:

Название поля Поддерживаемые целевые источники
client_id
  • Google Аналитика 4
  • Google Аналитика (Universal Analytics)
session_id
  • Google Аналитика 4
gclid
  • Google Реклама
  • Floodlight

Примеры

Получение значения объекта Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Отправка события в Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Получение установленного значения

gtag('set', {currency: 'USD'});

gtag('get', 'G-XXXXXXXXXX', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

Позволяет задавать значения, которые сохраняются во всех последующих вызовах gtag() на странице.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

<parameter-value-pair> – название ключа и значение, которое сохраняется во всех вызовах gtag(). В этом примере параметру country передается значение 'US', а параметру currency – 'USD'. Эти значения будут использоваться во всех последующих событиях на странице.

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Использование команды set отличается от передачи значений непосредственно команде event. В последнем случае значения, передаваемые в команду event, применяются только в вызываемом событии. Когда используется команда set, значения сохраняются на текущей странице и передаются во все последующие события. Сравните следующие примеры:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

и

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

В первом примере событие login будет передаваться со значением параметра method, равным 'Google', а событие share – без параметров. Во втором примере оба события login и share будут передаваться с параметром method, для которого задано значение 'Google'.

event

Используйте команду event для отправки данных о событии.

gtag('event', '<event_name>', {<event_params>});

<event_name> – это одно из следующих событий:

<event_params> – одна или несколько пар "параметр-значение", перечисленных через запятую.

Ниже показана команда event, которая вызывает рекомендуемое событие screen_view с двумя параметрами: app_name и screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Чтобы настроить согласие, используйте команду consent.

gtag('consent', {<consent_arg>}, {<consent_params>});

Дополнительная информация об особенностях настройки параметров приведена в статье Режим согласия на сайтах и в мобильных приложениях.

Для <consent_arg> можно использовать одно из следующих значений: 'default' или 'update'. 'default' позволяет задавать параметры по умолчанию, а 'update' используется для изменения этих параметров после получения согласия пользователя.

Поддерживаются следующие значения <consent_params>:

Название поля Допустимые значения
ad_storage 'granted' | 'denied'
analytics_storage 'granted' | 'denied'
wait_for_update Любое положительное целое число

Область действия параметров

Может распространяться на отдельное событие, события, связанные с определенным идентификатором <TARGET_ID>, или на все события сразу. Задается с помощью команд event, config и set.

Значения параметра, заданные в одной области действия, не влияют на значения этого параметра в другой области действия. В примере ниже команда config не изменяет глобальное значение параметра currency, заданного ранее с помощью команды set. После выполнения обеих команд для currency по-прежнему установлено глобальное значение 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

Приоритет параметров

Если одному параметру присвоены разные значения в разных областях действия, при обработке событий используется только одно из них. Значения параметра с областью действия event имеют приоритет над параметрами config, а параметры config – над глобальными параметрами команды set.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });