Guia do desenvolvedor da gtag.js

A tag global do site (gtag.js) é uma API e estrutura de tagging que permite enviar dados de eventos para o Google AdWords, Google Analytics e DoubleClick. Em vez de gerenciar várias tags para diferentes produtos, você pode usar a gtag.js e aproveitar com maior facilidade os mais recentes recursos e integrações de acompanhamento disponíveis.

A gtag.js facilita o envio de dados para vários produtos do Google por meio da inclusão de código no seu site. Não é necessário criar contas adicionais ou gerenciar a configuração em uma interface separada.

O Gerenciador de tags do Google é um sistema de gerenciamento de tags completo e eficiente compatível com todas as tags do Google e de terceiros. Você pode adicionar e modificar tags por meio da interface do Gerenciador de tags sem ajustar o código no seu site. Leia o Guia do desenvolvedor do Gerenciador de tags para saber mais.

Se você usa o Gerenciador de tags do Google, deve continuar a usá-lo em vez de adicionar o código da gtag.js ao seu site. No entanto, a gtag.js e o Gerenciador de tags do Google foram projetados para coexistir, portanto ambos funcionarão corretamente se implantados na mesma página.

Sobre este guia

Este guia ajudará você com os primeiros passos para utilizar a gtag.js em casos de uso comum que se aplicam ao Google AdWords, DoubleClick e Google Analytics. O guia inclui:

  • configuração básica para o Google AdWords, DoubleClick e Google Analytics.
  • como enviar dados de eventos.

No entanto, boa parte do seu uso da gtag.js dependerá dos produtos que você utiliza e dos dados específicos que você precisa capturar. Para documentação e casos de uso específicos de cada produto, consulte:

Etapas avançadas para uso da gtag.js

Não importa se você quer enviar dados para o Google AdWords, DoubleClick ou Google Analytics, o modelo básico para usar a gtag.js é o seguinte:

  1. Adicione o snippet global a cada página do seu site e configure-o para funcionar com o Google Analytics, Google AdWords e/ou DoubleClick. Leia abaixo a seção Adicionar o snippet global.
  2. Use os comandos gtag() para capturar eventos e enviar dados para um ou mais produtos (por exemplo, Google Analytics, Google AdWords, DoubleClick). Leia abaixo a seção Usar comandos gtag() para configurar e enviar dados.

Adicionar o snippet global

O snippet global precisa aparecer no topo de cada página do seu site. Os comandos gtag() não podem enviar dados sem um snippet global no topo da página, antes dos comandos gtag().

Se você precisa enviar dados para apenas um produto, siga as orientações para o produto específico (Google Analytics, Google AdWords ou DoubleClick). Para criar seu próprio snippet, selecione a guia correspondente abaixo, copie o trecho e cole-o imediatamente após a tag <head> em cada página do seu site. Você precisa implementar somente um snippet global por página.

Se você quer enviar dados para vários produtos, leia abaixo a seção Adicionar outro produto ou outra conta ao snippet global.

Google Analytics

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

  gtag('config', 'GA_TRACKING_ID');
</script>

Para localizar seu GA_TRACKING_ID:

  1. Na sua conta do Google Analytics, clique em Administrador.
  2. Selecione uma conta no menu da coluna CONTA.
  3. Selecione uma propriedade no menu da coluna PROPRIEDADE.
  4. Em PROPRIEDADE, clique em Informações de acompanhamento > Código de acompanhamento.

Seu ID de acompanhamento e o número da propriedade são exibidos na parte superior da página.

Google AdWords

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

  gtag('config', 'AW-GOOGLE_CONVERSION_ID');
</script>

Para localizar seu AW-GOOGLE_CONVERSION_ID:

  1. Na sua conta do Google AdWords, navegue até Ferramentas > Conversões > Ações de conversão.
  2. Na coluna Nome, selecione o nome da ação de conversão que você quer usar com a gtag.js.
  3. Na caixa de código, encontre os valores da variável google_conversion_id.

Adicionar outro produto ou conta ao seu

snippet global

Uma vez que o snippet gtag.js esteja instalado para qualquer produto, você pode configurá-lo para que funcione com outros produtos, basta adicionar mais comandos config.

Veja um exemplo de snippet global do Google Analytics com uma conta do Google AdWords adicionada no final:

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

  gtag('config', 'UA-12345-6');
  gtag('config', 'AW-123456789');
</script>

A primeira linha do snippet gtag.js inclui um URL no atributo src:

<script async src="https://www.googletagmanager.com/gtag/js?id=UA-12345-6">

Essa linha de código carrega a biblioteca gtag.js e inclui um ID de acompanhamento usado como identificador da tag global do site para associá-la ao produto que a originou.

Para ver exemplos de como adicionar vários produtos e contas ao seu snippet global, leia o Guia de roteamento da gtag.js.

Usar comandos gtag() para configurar e enviar dados

É possível invocar comandos gtag() em qualquer local da sua página após o snippet global. Você pode usar três comandos: config, set e event.

config

Use o comando config para inicializar e definir configurações de determinada conta de produto. O comando config apresenta o seguinte formato:

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

Uma linha semelhante no snippet global do Google Analytics define dois pontos:

em que <target_ID> é o ID da conta do produto para o qual você quer enviar dados, e <additional_config_info> é um objeto opcional usado para especificar mais opções de configuração.

Dependendo do produto de target_ID, o comando config pode se comportar de forma diferente. Por exemplo, quando o comando config é chamado com um ID de conversão do Google AdWords, ele inicia uma solicitação de remarketing e copia os IDs de clique em cookies primários. Quando o comando config é chamado com um ID de propriedade do Google Analytics, ele inicia um rastreador do Google Analytics que será usado pelos próximos comandos event na página e envia automaticamente um hit de exibição de página para a propriedade especificada do Google Analytics.

Você pode ajustar e estender o comportamento de configuração especificando parâmetros no objeto opcional <additional_config_info>. Por exemplo, adicionar o parâmetro a seguir impedirá o envio automático de uma exibição de página do Google Analytics:

gtag('config', 'UA-12345-6', {'send_page_view': false});

set

O comando set permite definir um valor que será automaticamente associado a cada evento subsequente na página. Por exemplo, se todas as transações no seu site usam a mesma moeda, use o comando set após o snippet global para especificar o campo currency.

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

Você pode definir vários atributos com um único comando set:

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

event

Com o comando event você envia dados de eventos. Por exemplo, para enviar um evento "conversion" com parâmetros value e currency:

gtag('event', 'conversion', {
  'value': 1.0,
  'currency': 'USD'
});

Existe um conjunto de eventos recomendados e parâmetros recomendados úteis em contextos específicos. Por exemplo, o evento "page_view" envia um hit de exibição de página para o Google Analytics. Saiba mais sobre os eventos e parâmetros recomendados na Referência de eventos.

Você também pode criar seus próprios eventos usando nomes que não sejam de eventos recomendados. Esses eventos são chamados de eventos personalizados.