Agradecemos seu interesse na nova documentação sobre tags do Google. Este site está em versão Beta pública. (Feedback)

Camada de dados

A camada de dados é um objeto usado pelo Gerenciador de tags do Google e pela gtag.js para transmitir informações às tags. Eventos ou variáveis podem ser transmitidos pela camada de dados, e os acionadores podem ser configurados com base nos valores delas.

Por exemplo, se você disparar uma tag de remarketing quando o valor de purchase_total for maior que R$ 100 ou fizer isso com base em eventos específicos como o clique em um botão, é possível configurar sua camada de dados para disponibilizar essas informações às suas tags. O objeto da camada de dados é estruturado como JSON. Exemplo:

{
  event: "checkout_button",
  gtm: {
    uniqueEventId: 2,
    start: 1639524976560,
    scrollThreshold: 90,
    scrollUnits: "percent",
    scrollDirection: "vertical",
    triggers: "1_27"
  },
  value: "120"
}

As tags do Google são projetadas para referenciar facilmente as informações adicionadas à camada de dados de maneira organizada e previsível, em vez de analisar variáveis, detalhes de transações, categorias de página e outros indicadores espalhados pela página de dados. Uma implementação de camada de dados preenchida com variáveis e valores associados ajuda a garantir que os dados relevantes estejam disponíveis quando suas tags precisarem deles.

Instalação

Para instalações de páginas da Web do Gerenciador de tags, você precisa criar uma camada de dados. O código destacado abaixo mostra onde essa camada está estabelecida, antes que o Gerenciador de tags seja carregado.

<script>
window.dataLayer = window.dataLayer || [];
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Nas implementações padrão da gtag.js, onde a tag foi copiada do produto e adicionada a uma página da Web, o código para estabelecer a camada de dados é informado. Nas implementações personalizadas de tag global do site, adicione o código da camada de dados no início do script, conforme mostrado no exemplo destacado abaixo:

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

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

Como as informações da camada de dados são processadas

Quando um contêiner é carregado, o Gerenciador de tags começa a processar todas as mensagens push da camada de dados em fila. As mensagens são processadas uma por vez e na ordem em que foram recebidas. Se a mensagem for um evento, todas as tags com condições de acionamento que foram atendidas serão acionadas antes que o Gerenciador de tags passe para a próxima mensagem.

Se uma chamada gtag() ou dataLayer.push() for feita com o uso de código em uma página, modelo personalizado ou tag HTML personalizada, a mensagem associada será incluída na fila e processada depois que todas as outras mensagens pendentes forem avaliadas. Assim, não há garantia de que os valores atualizados da camada de dados estarão disponíveis para o próximo evento. Para gerenciar esses casos, adicione um nome de evento a uma mensagem quando ela for enviada à camada de dados. Depois, aguarde a detecção do nome do evento com um acionador de evento personalizado.

Usar uma camada de dados com manipuladores de eventos

O objeto dataLayer usa uma chave event para iniciar o envio de eventos.

As tags globais do site e o Gerenciador de tags usam uma variável de camada de dados especial chamada event, que é usada pelos listeners de eventos do JavaScript para disparar tags quando um usuário interage com os elementos do site. Por exemplo, convém disparar uma tag de acompanhamento de conversões quando um usuário clica em um botão de confirmação de compra. Os eventos podem ser chamados sempre que um usuário interage com elementos do site, como links, botões, rolagens etc.

Para usar esse recurso, chame dataLayer.push() quando ocorrer um evento. A sintaxe do envio de um evento com dataLayer.push() é a seguinte:

dataLayer.push({'event': 'event_name'});

Em que event_name é uma string que descreve o evento, como 'login', purchase ou search.

Use dataLayer.push() para enviar dados de eventos quando ocorrer uma ação que você quer medir. Por exemplo, para enviar um evento quando um usuário clicar em um botão, modifique o manipulador onclick do botão para chamar dataLayer.push():

<button onclick="dataLayer.push({'event': 'login'});">Button 1</button>

É possível enviar variáveis de camada de dados de forma dinâmica para registrar informações, como os valores inseridos ou selecionados em um formulário, os metadados associados a um vídeo reproduzido pelo visitante, a cor de um produto (por exemplo, um carro) personalizado pelo visitante, os URLs de destino dos links clicados etc.

Assim como nos eventos, esse recurso é acessado chamando a API push() para adicionar ou substituir as variáveis na camada de dados. Veja a seguir a sintaxe básica para a definição de variáveis dinâmicas na camada de dados:

dataLayer.push({'variable_name': 'variable_value'});

Em que a string 'variable_name' indica o nome da variável da camada de dados a ser definida e 'variable_value' representa o valor da variável a ser definida ou substituída.

Por exemplo, para definir uma variável da camada de dados com uma preferência de cor quando um visitante interage com uma ferramenta de personalização de produtos, envie a seguinte variável dinâmica:

dataLayer.push({'color': 'red'});

Um envio com diversas variáveis

É possível enviar inúmeras variáveis e eventos de uma só vez:

dataLayer.push({
  'color': 'red',
  'conversionValue': 50,
  'event': 'customize'
});

Manter as variáveis da camada de dados

Para manter as variáveis da camada de dados entre páginas da Web, chame dataLayer.push() depois que a camada de dados for instanciada em cada carregamento de página e envie as variáveis para a camada de dados. Se você quiser que essas variáveis da camada de dados estejam disponíveis para o Gerenciador de tags quando o contêiner for carregado, adicione uma chamada dataLayer.push() acima do código do contêiner, conforme mostrado abaixo.

<script>
window.dataLayer = window.dataLayer || [];

dataLayer.push({
 'event': 'Pageview',
 'pagePath': 'https://www.googleanalytics.dev/pancakes',
 'pageTitle': 'Pancake Event Signup',
 'visitorType': 'customer'
});
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Cada variável declarada no objeto da camada de dados persistirá enquanto o visitante permanecer na página atual. As variáveis da camada de dados que são relevantes para as páginas (por exemplo, visitorType) precisam ser declaradas na camada de cada página do seu site. Embora não seja necessário inserir o mesmo conjunto de variáveis na camada de dados em todas as páginas, você precisa usar uma nomenclatura consistente. Em outras palavras, se você definir a categoria na página de inscrição usando uma variável chamada pageCategory, suas páginas de produtos e de compra também usarão a variável pageCategory.

Solução de problemas

Veja algumas dicas para solucionar problemas da camada de dados:

Não substitua a variável window.dataLayer: ao usar a camada de dados diretamente (por exemplo, dataLayer = [{'item': 'value'}])), ela substitui os valores atuais na dataLayer. As instalações do Gerenciador de tags precisam instanciar a camada de dados no nível mais alto possível do código-fonte, acima do snippet de contêiner ou de qualquer snippet de ocultação de página do Optimize, usando window.dataLayer = window.dataLayer || [];. Depois que você declarar o dataLayer, use o método dataLayer.push({'item': 'value'}) para adicionar outros valores a ele. Se esses valores precisarem estar disponíveis no Gerenciador de tags quando a página for carregada, dataLayer.push() também precisa estar acima do código do contêiner do Gerenciador de tags.

O nome do objeto dataLayer diferencia maiúsculas de minúsculas: não é possível enviar uma variável ou um evento com a capitalização incorreta.

datalayer.push({'pageTitle': 'Home'});    // Bad (datalayer in lowercase)
dataLayer.push({'pageTitle': 'Home'});    // Good (dataLayer in camel case)

É necessário chamar dataLayer.push com objetos JavaScript válidos. Todos os nomes de variáveis da camada de dados devem estar entre aspas.

dataLayer.push({new-variable: 'value'});      // Bad - no quote marks
dataLayer.push({'new-variable': 'value'});    // Good - proper quote marks

Mantenha nomes de variáveis consistentes em todas as páginas: se você usar nomes diferentes para o mesmo conceito em páginas distintas, suas tags não serão disparadas de forma consistente em todos os locais desejados.

Ruim:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitor_type': 'high-value'});

Bom:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitorType': 'high-value'});

Renomear a camada de dados

O nome padrão do objeto da camada de dados iniciado pela tag global do site ou pelo Gerenciador de tags é dataLayer. Caso prefira usar outro nome, edite o valor de parâmetro da camada na tag global do site ou no snippet de contêiner do Gerenciador de tags com o nome escolhido.

gtag.js

Adicione um parâmetro de consulta chamado "l" ao URL para definir o novo nome da camada de dados, por exemplo, l=myNewName. Atualize todas as instâncias de dataLayer no snippet da tag global do site para o novo nome.

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

  gtag('config', 'G-ZZZZZZ');
</script>

Gerenciador de tags

Substitua o valor de parâmetro da camada de dados (destacado abaixo) no seu snippet de contêiner pelo nome que você preferir.

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','myNewName','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Depois de renomeadas, todas as referências à sua camada de dados (ou seja, ao declará-la acima do snippet ou enviar eventos ou variáveis dinâmicas a ela com o comando .push()) precisam ser ajustadas para refletir o nome da camada de dados personalizada:

<script>
  myNewName = window.dataLayer || [];
  myNewName.push({'variable_name': 'variable_value'});
</script>

Métodos de camada de dados personalizados

Se você enviar uma função para a camada de dados, ela será invocada com essa definição como um modelo de dados abstratos. Esse modelo pode buscar e definir os valores para um armazenamento de chave-valor, além de fornecer uma maneira de redefinir a camada de dados.

set

Com a função set no modelo de dados abstratos, você define valores a serem recuperados por meio da função "get".

window.dataLayer.push(function() {
  this.set('time', new Date());
});

get

A função get no modelo de dados abstratos permite recuperar valores com "set".

window.dataLayer.push(function() {
  const existingTime = this.get('time');
  if (existingTime !== null) {
    // Change behavior based on whether or not this value exists...
  } else {
    // ...
  }
})

reset

A função reset no modelo de dados abstratos permite redefinir os dados na camada de dados. Isso é mais útil com uma página que permanecerá aberta e o tamanho da camada de dados continuará crescendo com o tempo. Para redefinir a camada de dados, use o seguinte código:

window.dataLayer.push(function() {
  this.reset();
})