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

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

gtag(<command>, <command parameters>);

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

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

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

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

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

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

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

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

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

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

`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', {campaign_name: 'Spring_Sale'});

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

`set`

Команда set позволяет задавать параметры, которые будут связаны с каждым последующим событием на странице.

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

Например, вы можете предоставить доступ к параметрам кампании разным тегам на одной странице.

В примере ниже показано, как задать название и идентификатор кампании для события "Черная пятница". Поскольку вы использовали set, доступ к этим данным могут получить все остальные теги, включая теги событий GA4 и теги ремаркетинга Google Рекламы.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`event`

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

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

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

Рекомендуемое событие. Такие события могут принимать рекомендуемые параметры.
Пользовательское событие. Это событие с произвольным названием, которое выбирает пользователь, и с произвольными (т. е. специальными) параметрами. Пример: пользовательские события в Google Аналитике.

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

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

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

`consent`

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

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

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

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

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

Название поля	Допустимые значения	Описание
`ad_storage`	`'granted'` \| `'denied'`	Разрешает сохранять данные, например файлы cookie (сайты) или идентификаторы устройств (приложения), связанные с рекламой.
`ad_user_data`	`'granted'` \| `'denied'`	Устанавливает статус согласия на отправку в Google пользовательских данных, связанных с рекламой.
`ad_personalization`	`'granted'` \| `'denied'`	Устанавливает статус согласия на персонализированную рекламу.
`analytics_storage`	`'granted'` \| `'denied'`	Разрешить сохранять данныенапример файлы cookie (сайты) или идентификаторы устройств (приложения), связанные с аналитикой, такие как продолжительность посещения.
`wait_for_update`	Любое положительное целое число	Устанавливает период ожидания вызова команд update для режима согласия в миллисекундах.