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 das variáveis.

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 a 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. Em implementações personalizadas da tag do Google, adicione o código da camada de dados no início do script, como mostrado no exemplo abaixo:

<!-- 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>

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 disparadas 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.

Importante: não use as tags HTML personalizadas para implantar o código com base na gtag.js. Em vez disso, use os modelos de tag nativos do Gerenciador de tags para Google Ads, Analytics e Floodlight.

Importante: não use a tag HTML personalizada para definir configurações de consentimento no Gerenciador de tags. Como as definições de autorização precisam ser implementadas antes que as tags relevantes sejam disparadas em um contêiner do Gerenciador, use as APIs de consentimento do Gerenciador de tags para configurar e atualizar o comportamento padrão. O uso das APIs de consentimento do Gerenciador de tags garante que as atualizações sejam processadas antes de qualquer item na fila da camada de dados. Assim, o mesmo estado de consentimento vai aparecer para todas as tags disparadas pelo mesmo evento.

Importante: use o Assistente de tags do Google para inspecionar o status da sua camada de dados em qualquer ponto em uma cadeia de eventos.

Usar uma camada de dados com manipuladores de eventos

O objeto dataLayer usa um comando event para iniciar o envio de eventos.

A tag do Google e o Gerenciador de tags usam uma variável especial de camada de dados chamada event, que é usada pelos listeners de eventos JavaScript para disparar tags quando um usuário interage com os elementos do site. Por exemplo, é recomendável 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 dinamicamente variáveis da camada de dados 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'
});

Importante: se você enviar uma variável com o mesmo nome de uma variável atual à camada de dados, o valor atual será substituído pelo novo.

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, usando window.dataLayer = window.dataLayer || [];. Depois que você declarar dataLayer, use o método dataLayer.push({'item': 'value'}) para adicionar outros valores a ele. Se quiser disponibilizar estes valores 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 do Google ou pelo Gerenciador de tags é dataLayer. Se preferir usar outro nome, edite o valor de parâmetro da camada na tag do Google 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 do Google para o novo nome.

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

  gtag('config', 'TAG_ID');
</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.

Importante: não substitua o valor de parâmetro não destacado.

<!-- 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>

Observação: só é possível inserir um objeto dataLayer por página.

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 oferecer uma maneira de redefinir a camada de dados.

Importante: para usar métodos personalizados de camada de dados, use .push para enviar informações diretamente à variável dataLayer. Se você utilizar gtag, a função será interpretada como um comando inválido e ignorada.

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 vai 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();
})