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) |
Функция, которая вызывается с помощью запрашиваемого поля, или |
FieldName
Названием поля может быть значение, заданное в дополнительном поле с помощью команды gtag('set')
, или одно из следующих значений:
Название поля | Поддерживаемые целевые источники |
---|---|
client_id |
|
session_id |
|
gclid |
|
Примеры
Получение значения объекта 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>
– это одно из следующих событий:
- Рекомендуемое событие. Такие события могут принимать рекомендуемые параметры.
- Пользовательское событие. Это событие с произвольным названием, которое выбирает пользователь, и с произвольными (т. е. специальными) параметрами. Пример: пользовательские события в 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' |
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>' });