Referência da API da tag do Google

A API da tag do Google (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
- consent
<command parameters> são os parâmetros que você pode transmitir para 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 página, desde que estejam abaixo do snippet de tag do Google. Para saber como adicionar o snippet a uma página, consulte o guia de instalação.

Escopo do parâmetro

É possível definir o escopo de valores de parâmetros para eventos específicos, todos os eventos enviados a 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âmetros 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 campaign_id atribuído antes com set. Quando os dois comandos forem executados, o valor global de campaign_id ainda será '1234'.

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

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

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 têm prioridade sobre aqueles com escopo config. Além disso, os parâmetros config prevalecem sobre aqueles que têm escopo global e usam 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`

Permite incluir mais detalhes de configuração nos destinos. Essa geralmente é uma configuração específica do produto, mas você só vai precisar definir uma vez se estiver usando o Google Ads e o Analytics.

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

<TARGET_ID> identifica exclusivamente o destino dos hits, como uma propriedade do 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', 'TAG_ID');

"TAG_ID" é o ID da tag do Google.

Veja como enviar outras informações de configuração 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', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

`get`

Permite receber 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`	G-XXXXXXXXXX	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 com suporte
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 Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

Conferir um valor que você definiu

gtag('set', {campaign_name: 'Spring_Sale'});

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

`set`

Com o comando "set", você pode definir parâmetros que serão associados a todos os eventos seguintes na página.

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

Por exemplo, é possível compartilhar parâmetros de campanha para que possam ser acessados por várias tags na mesma página.

O exemplo abaixo mostra a definição de um nome e ID de campanha para um evento de compras da Black Friday. Como você usou set, todas as outras tags (por exemplo, tags de evento do GA4 ou de remarketing do Google Ads) poderão acessar os dados em questão.

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

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

`consent`

Use o comando consent para configurar o consentimento.

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

Consulte o artigo sobre consentimento na Central de Ajuda para mais informações sobre o comportamento que esses parâmetros definem.

<consent_arg> é um dos campos 'default' ou 'update'. 'default' é usado para definir os parâmetros de consentimento padrão que precisam ser usados, e 'update' é usado para atualizar esses parâmetros depois que um usuário indica o consentimento dele.

Estes <consent_params> são aceitos:

Nome do campo	Valores permitidos	Descrição
`ad_storage`	`'granted'` \| `'denied'`	Permite o armazenamento, como cookies (Web) ou identificadores de dispositivos (apps), relacionado à publicidade.
`ad_user_data`	`'granted'` \| `'denied'`	Define o consentimento para enviar dados do usuário ao Google para fins de publicidade.
`ad_personalization`	`'granted'` \| `'denied'`	Define o consentimento para veicular publicidade personalizada.
`analytics_storage`	`'granted'` \| `'denied'`	Permite o armazenamento, como cookies (Web) ou identificadores de aplicativos (apps), relacionado a análises (por exemplo, duração da visita).
`wait_for_update`	Um número inteiro positivo	Define um tempo, em milissegundos, de espera por uma chamada de atualização do consentimento.