Справочник по API тегов Google

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

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

Вы можете вызывать gtag() в любом месте на своей странице, если они отображаются под фрагментом тега Google. Чтобы узнать, как добавить фрагмент на страницу, см. руководство по установке .

config

Позволяет добавлять к целям дополнительную информацию о конфигурации. Обычно это конфигурация продукта для конкретного продукта, но вам нужно настроить ее только один раз, если вы используете Google Ads и Google Analytics.

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

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

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

gtag('config', 'TAG_ID');

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

Чтобы продемонстрировать, как отправлять дополнительную информацию о конфигурации, вот пример, который настраивает тег для отправки данных в аккаунт Google Analytics с параметром 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)
Аргумент Тип Пример Описание
<цель> string UA-XXXXXXXX-Y

Цель, из которой извлекаются значения.

<имя_поля> Имя поля ID клиента Имя поля, которое необходимо получить.
перезвонить Function (field) => console.log(field)

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

Имя поля

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

Имя поля Поддерживаемые цели
ID клиента
  • Google Аналитика 4
  • Универсальная аналитика Google Analytics
идентификатор сессии
  • Google Аналитика 4
гклид
  • Google Реклама
  • Прожектор

Примеры

Получите ценность в обещании

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

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

Отправить событие в протокол измерений

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

Получите значение, которое вы установили

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

gtag('get', 'UA-XXXXXXXX-Y', '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>' });