Справочное руководство по API gtag.js

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

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

Команды gtag можно вызывать в любом месте страницы ниже глобального тега. О том, как добавить глобальный тег на страницу, читайте в этом руководстве.

config

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

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

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

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

gtag('config', 'AW-CONVERSION_ID');

Аналогичным образом команду config можно использовать с Google Analytics:

gtag('config', 'GA-TRACKING_ID');

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

gtag('config', 'GA-TRACKING_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

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

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

Область действия параметров может распространяться на отдельное событие, все события, связанные с конкретным идентификатором <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>' });