Referência da API gtag.js

A API gtag.js consiste em uma única função, gtag(), com a seguinte sintaxe:

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

<command> é um dos seguintes comandos:
- config
- get
- set
- event
<command parameters> são os parâmetros a serem enviados para a gtag(). Esse tipo de parâmetro varia de acordo com o comando. Consulte a referência de comandos abaixo.

Você pode invocar comandos gtag em qualquer local da sua página, desde que estejam abaixo do snippet global. Para saber como adicionar o snippet global em uma página, consulte a orientação sobre snippet.

`config`

Permite incluir mais informações de configuração nos destinos. Essa configuração normalmente é específica para um produto, como o Google Ads ou o Google Analytics.

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

<TARGET_ID> identifica exclusivamente o destino dos hits, como uma propriedade do Google Analytics ou uma conta do Google Ads. <additional_config_info> representa um ou mais pares de valor de parâmetro.

Neste exemplo, uma tag é configurada para enviar dados a uma conta do Google Ads:

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

O comando config também pode ser usado com o Google Analytics:

gtag('config', 'GA_MEASUREMENT_ID');

Veja como enviar outras informações sobre "config" no exemplo abaixo, em que uma tag é configurada para enviar dados a uma conta do Google Analytics usando um parâmetro send_page_view com um valor false e um parâmetro groups definido como 'agency'.

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

`get`

Permite enviar diversos valores da gtag.js, incluindo conjuntos de valores com o comando set.

gtag('get', '<target>', '<field_name>', callback)

Argumento	Tipo	Exemplo	Descrição
<target>	`string`	UA-XXXXXXXX-Y	Destino em que os valores serão buscados.
<field_name>	FieldName	client_id	Nome do campo que será recebido.
callback	`Function`	`(field) => console.log(field)`	Função que será invocada com o campo solicitado, ou `undefined` se ele não tiver um valor.

FieldName

O nome do campo pode ser o nome de um campo personalizado definido com o comando gtag('set'), ou um dos seguintes valores:

Nome do campo	Destinos compatíveis
client_id	Google Analytics 4 Universal Analytics do Google Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

Exemplos

Ver um valor para um Promise

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

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

Enviar evento para o Protocolo de avaliação

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

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

Ver um valor que você definiu

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

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

`set`

Permite que você defina valores que permanecem em todas as chamadas da gtag() subsequentes na página.

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

O valor do nome de chave <parameter-value-pair> deve ser mantido nas chamadas de gtag(). Por exemplo, o código abaixo define o valor de country como 'US' e de currency como 'USD' para todos os eventos subsequentes na página:

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

Há diferenças entre usar o comando set e transmitir os valores diretamente para o event. Quando você envia os valores diretamente para um comando event, eles são aplicados apenas ao evento disparado. No entanto, ao usar set, os valores permanecem na página atual e são transmitidos para todos os eventos subsequentes. Veja a seguir a diferença entre os dois exemplos:

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

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

No primeiro exemplo, o evento login é enviado com um valor method definido como 'Google', e o evento share é transmitido sem parâmetros. No segundo, tanto login quanto share são transferidos com um valor method 'Google'.

`event`

Use o comando event para enviar dados de eventos.

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

<event_name> pode ser:

um evento recomendado, que aceita parâmetros recomendados;
um evento personalizado, ou seja, um nome de evento arbitrário criado por você, com parâmetros arbitrários (ou seja, personalizados). Por exemplo, veja como eventos personalizados são usados no Google Analytics.

<event_params> representa um ou mais pares de valor de parâmetro, em que cada par é separado por uma vírgula.

O comando event a seguir dispara o evento recomendado screen_view com dois parâmetros: app_name e screen_name.

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

Escopo do parâmetro

É possível definir o escopo dos valores de parâmetro para um evento individual, além de enviar todos os eventos para um <TARGET_ID> específico ou globalmente para todos os eventos. Se quiser fazer isso, use os comandos event, config e set.

Os valores de parâmetro definidos em um escopo não modificam aqueles estabelecidos para o mesmo parâmetro em outro escopo. No exemplo abaixo, o comando config não altera o valor global de currency atribuído anteriormente com set. Quando os dois comandos forem executados, o valor global de currency ainda será 'EUR'.

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

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

Precedência do parâmetro

Se valores diferentes forem atribuídos ao mesmo parâmetro em escopos diferentes, apenas um valor será usado durante o processamento de eventos. Os valores de parâmetros com escopo event terão prioridade sobre aqueles com escopo config. Além disso, os parâmetros config prevalecerão sobre aqueles que têm escopo global e usam 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>' });