O que é o gtag, como ele carrega e o que cada comando envia

O que é o gtag?

A função gtag() é a API JavaScript da tag do Google, e cada chamada a ela coloca um comando como config, event, set ou consent em uma fila chamada dataLayer, que a biblioteca gtag.js lê para enviar dados aos produtos do Google. A referência do Google resume isso em uma linha: "The Google tag (gtag.js) API uses the gtag() function to send data to Google products like Google Analytics and Google Ads." Se o código-fonte de um site carrega gtag/js?id=, esse site roda a tag do Google diretamente no próprio código, e não por meio de um contêiner do Tag Manager.

Três nomes se confundem aqui. gtag.js é o arquivo da biblioteca. gtag() é a função que o seu código chama. A tag do Google é o nome de produto que o Google usa para a configuração inteira, que ele descreve como "a single tag you can add to your website to use Google measurement and advertising products like Google Ads, Google Analytics, Campaign Manager, Display & Video 360, and Search Ads 360."

Como o gtag.js carrega em uma página?

O gtag.js carrega por meio de um snippet em duas partes que o Google manda colocar "immediately after the opening <head> HTML tag on every page you want to measure." A primeira parte baixa a biblioteca, e a segunda define a função gtag() e coloca os primeiros comandos na fila.

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'TAG_ID');
</script>

A ordem importa menos do que parece. A biblioteca carrega com async, então o script inline roda primeiro. Como gtag() não faz nada além de dataLayer.push(arguments), todo comando que você chama antes de a biblioteca chegar espera no array do dataLayer, e o gtag.js processa a fila assim que termina de carregar. É por isso que você pode chamar gtag('event', ...) em qualquer ponto da página sem verificar se a biblioteca está pronta.

O id na URL do script é um ID da tag do Google. O Google dá "GT-XXXXXXXXX, G-XXXXXXXXX, and AW-XXXXXXXXX" como exemplos e observa que "the IDs can be used interchangeably when adding the Google tag to your website." Uma tag do Google pode levar vários IDs e enviar para vários destinos, como uma propriedade do Google Analytics e uma conta do Google Ads.

O que fazem os comandos gtag()?

Os comandos gtag() são cinco verbos, cada um passado como primeiro argumento: config, event, set, get e consent. A tabela usa a sintaxe e as palavras da referência de API do Google.

O config faz mais do que a descrição sugere. O Google afirma que "The config command is needed to send data to Google advertisement products," e, no Google Analytics, a chamada config padrão também envia um evento page_view. Para impedir isso, o Google documenta send_page_view: false, que você precisa usar quando envia as pageviews por conta própria, por exemplo em uma single-page app.

O set é o comando para usar com moderação. O Google acrescenta: "We recommend using config or event commands wherever possible." Valores definidos no escopo do evento sobrescrevem os valores de config, e os valores de config sobrescrevem tudo o que foi definido globalmente com set.

O consent aceita dois modos. 'default' define o estado inicial antes de o visitante responder ao seu banner, e 'update' muda esse estado depois que ele responde. Os quatro parâmetros do consent mode v2 são ad_storage, analytics_storage, ad_user_data e ad_personalization; o guia do Google consent mode v2 explica o que os dois sinais mais novos acrescentaram.

Em que ordem os comandos gtag devem rodar?

Os comandos gtag rodam na ordem em que você os coloca na fila, e três deles só funcionam se vierem antes da primeira chamada config ou event.

1. Flag de opt-out. window['ga-disable-MEASUREMENT_ID'] = true "must be set before any calls to gtag() are made, and it must be set on each page for which you want to turn off Analytics."
2. Padrões de consentimento. O Google diz para definir o padrão de cada tipo de consentimento "on every page of your site before any commands that send measurement data (such as config or event)." Se a sua ferramenta de consentimento carrega de forma assíncrona, adicione wait_for_update com um valor em milissegundos.
3. Configurações globais. Chamadas set como allow_google_signals: false vêm antes do config, para que o primeiro hit já as leve.
4. config. Uma chamada por ID de tag.
5. event. Todo o resto vem depois.

Um padrão de consentimento colocado depois do config chega tarde demais para a primeira pageview, e essa é uma das formas mais silenciosas de um site acabar enviando hits que pretendia segurar.

Qual é a relação entre o gtag, a tag do Google e o Google Tag Manager?

O gtag.js e o Google Tag Manager são duas formas de implantar a mesma tag do Google: com o gtag.js você escreve os comandos no código da página, e com o Tag Manager você os configura em uma interface web e o script do contêiner, gtm.js, carrega tudo para você. O guia do gtag.js do Google diz que "if you're unfamiliar with JavaScript, we recommend using Google Tag Manager instead of gtag.js."

Os dois compartilham o dataLayer, então um site pode rodar ambos. O risco é contar as coisas duas vezes. O Google avisa, por exemplo, que se você configura as tags pelo Tag Manager não deve ativar também o tracking automático de histórico no Google Analytics, "as this can lead to double-counting page views." A mesma lógica vale para um snippet gtag fixo no código e uma tag do Google no GTM que apontam para o mesmo ID de medição: cada um envia o próprio page_view. O guia sobre o impacto do Google Tag Manager na privacidade cobre o outro lado dessa escolha, que é quanto código um contêiner deixa outras pessoas adicionarem às suas páginas.

Por que os bloqueadores de anúncios param o gtag?

Os bloqueadores de anúncios param o gtag bloqueando a requisição da biblioteca em www.googletagmanager.com ou os hits que ela envia aos endpoints de coleta do Google. Quando a requisição do script falha, gtag() continua existindo, já que o snippet inline a definiu, mas nada lê a fila do dataLayer, então nenhum dado sai da página. O guia sobre bloqueadores de anúncios e a precisão do analytics explica como essa lacuna aparece nos relatórios. O Google tag gateway for advertisers serve a tag a partir do seu próprio domínio, embora a documentação do gateway do Google não mencione bloqueadores de anúncios.

Como verificar o que o gtag está enviando?

Você verifica o que o gtag envia observando as requisições de rede e as ferramentas de depuração do Google, e não lendo o snippet. Os próprios guias do Google usam duas: o Tag Assistant, que mostra os comandos e os hits que cada um gerou, e o DebugView no Google Analytics, que mostra os eventos conforme chegam quando o modo de depuração está ativo. No navegador, filtre o painel Network pelas requisições de coleta e confirme que cada pageview ou evento aparece uma única vez, com os parâmetros esperados. O checklist de verificação do analytics percorre as mesmas checagens para qualquer rastreador.

Como o script do Flowsery se compara ao gtag?

O rastreador do Flowsery é uma única tag de script com um ID de site, então não há fila de comandos para configurar antes de os dados começarem a chegar. Cole <script defer data-fl-website-id="flid_******" src="https://cdn.flowsery.com/main.js"></script> no head e as pageviews são rastreadas automaticamente. Metas personalizadas usam um atributo data-fs-goal no elemento ou uma chamada como window.flowsery('signup'), e a documentação do Flowsery mostra um pequeno stub de fila, window.flowsery.q, que guarda as chamadas feitas antes de o script carregar, o mesmo padrão que o gtag usa com o dataLayer. O script também tem uma opção sem cookies que usa um hash de visitante trocado diariamente e não armazena dados pessoais. O script leve tem menos de 10 KB e carrega de forma assíncrona. Se a sua equipe já gerencia tags no Google Tag Manager, a documentação do Flowsery inclui uma configuração de tag HTML personalizado para o GTM, para que os dois convivam durante uma migração.

Perguntas frequentes

O gtag é a mesma coisa que o Google Tag Manager?

Não. O gtag.js é a biblioteca por trás da tag do Google, e você chama gtag() no código da sua própria página. O Google Tag Manager é um contêiner separado, carregado pelo gtm.js, em que as tags são configuradas em uma interface web. Os dois podem implantar a mesma tag do Google.

Posso chamar gtag() antes de o gtag.js carregar?

Sim. O snippet inline define gtag() como uma função que coloca seus argumentos no array do dataLayer. As chamadas feitas antes de a biblioteca chegar esperam nessa fila, e o gtag.js as processa em ordem assim que carrega.

Um único snippet gtag pode enviar dados ao Google Analytics e ao Google Ads?

Sim. Uma tag do Google pode se conectar a vários destinos, como uma propriedade do Google Analytics e uma conta do Google Ads. Uma única tag pode levar vários IDs de tag, e o Google observa que esses IDs podem ser usados de forma intercambiável ao adicionar a tag ao seu site.

Por que o gtag envia um page_view sem uma chamada de evento?

A chamada config padrão para um ID do Google Analytics envia um evento page_view por conta própria. Defina send_page_view: false se quiser enviar as pageviews manualmente. Em sites com medição otimizada, as pageviews baseadas no histórico continuam disparando, a menos que você também desative essa opção no fluxo de dados.

Onde o snippet gtag deve ficar?

O Google diz para colocá-lo logo depois da tag <head> de abertura em cada página que você quer medir. Uma flag de opt-out vai em um script antes do snippet, já que o Google diz que ela precisa ser definida antes de qualquer chamada gtag(). Os padrões de consentimento vão dentro do snippet, antes da chamada config, já que o Google diz que eles precisam rodar antes de qualquer comando que envie dados de medição.

O gtag funciona se o script for bloqueado?

Nenhum dado é enviado. A parte inline do snippet ainda define gtag() e preenche o dataLayer, mas sem a biblioteca gtag.js nada processa essa fila. É por isso que os visitantes bloqueados simplesmente somem do Google Analytics, em vez de aparecerem como erros.

Qual é a diferença entre gtag.js, gtag() e a tag do Google?

gtag.js é o arquivo da biblioteca, carregado de googletagmanager.com. gtag() é a função que seu código chama para colocar comandos no dataLayer. A tag do Google é o nome que o Google dá a todo o conjunto, uma única tag que cobre produtos como Google Ads e Google Analytics.

Quais formatos de ID de tag posso usar no snippet gtag?

O Google dá GT-XXXXXXXXX, G-XXXXXXXXX e AW-XXXXXXXXX como exemplos e diz que os IDs podem ser usados de forma intercambiável ao adicionar a tag do Google ao seu site. O ID vai no parâmetro id da URL do script e na sua chamada config. Uma mesma tag do Google pode levar vários IDs.

Quando devo usar gtag('set')?

Use set para parâmetros que devem ser associados a todo evento seguinte na página. O Google recomenda usar config ou event sempre que possível. Valores no nível do evento substituem os de config, e os de config substituem o que foi definido globalmente. Se usar set, coloque-o antes de config para que o primeiro hit já leve esses valores.

Como desativo o Google Analytics com um sinalizador de exclusão do gtag?

Defina window['ga-disable-MEASUREMENT_ID'] = true na página. Segundo o Google, isso deve ser feito antes de qualquer chamada a gtag() e em cada página em que você quiser desativar o Analytics.