Se você já mexeu em GTM, viu a palavra dataLayer aparecer em tutorial, em código de e-commerce e no Preview Mode, mas talvez nunca tenha parado para entender o que ela é de fato. E esse é o conceito que sustenta quase todo traqueamento sério: sem dataLayer, o GTM fica adivinhando o que aconteceu na página em vez de receber o dado pronto.
O dataLayer é o array JavaScript window.dataLayer que fica no seu site e serve de ponte entre a página e o GTM. Você empurra dados para dentro dele com dataLayer.push() (o valor de uma compra, o nome de um produto, o passo do checkout) e o GTM lê esses dados para decidir quais tags disparar e com quais parâmetros. É uma fila de mensagens estruturada: o site publica, o GTM consome.
Este artigo mostra o que é o dataLayer, como o push funciona por dentro, como o GTM lê esses valores e como montar o seu do zero, com um exemplo real de e-commerce. É o pré-requisito conceitual para entender eventos de e-commerce no GA4 e os erros mais comuns no Google Tag Manager, porque a maioria deles começa num dataLayer mal montado.
O que é o dataLayer, na prática
Tecnicamente, o dataLayer é um array de objetos JavaScript. O snippet do GTM inicializa esse array assim que carrega, e a partir daí qualquer script da página pode adicionar um objeto a ele. Cada objeto carrega pares de chave e valor: uma chave é o nome do dado (event, value, transaction_id) e o valor é o conteúdo ('purchase', 97.00, 'ABC123').
A razão de ele existir é desacoplar o dado do site da tag que consome esse dado. Sem dataLayer, cada tag precisaria vasculhar o HTML da página para achar o preço da compra ou o e-mail do lead, e qualquer mudança de layout quebraria o traqueamento. Com dataLayer, o site declara o dado uma vez, de forma estruturada, e todas as tags (GA4, Pixel do Meta, Google Ads) leem da mesma fonte. Muda o layout, o dataLayer continua igual, e nada quebra.
Pense no dataLayer como o contrato entre quem desenvolve o site e quem cuida do traqueamento. O dev garante que o objeto certo é empurrado no momento certo; o analista lê esse objeto no GTM sem precisar pedir alteração de código a cada nova tag. É essa separação que faz o GTM valer a pena numa operação de verdade.
Como o dataLayer.push funciona
A operação central é o dataLayer.push(). Você passa um objeto com os dados que quer disponibilizar, e ele entra no fim da fila. A convenção mais importante é a chave event: quando o objeto empurrado contém event, o GTM trata aquilo como um evento personalizado e reavalia todos os triggers naquele instante.
window.dataLayer = window.dataLayer || [];
dataLayer.push({
event: 'lead_enviado',
form_id: 'contato-home',
valor_estimado: 500
});A primeira linha é uma garantia: se o dataLayer ainda não existe, ela cria um array vazio antes de empurrar. Isso evita erro quando o push acontece antes de o GTM terminar de carregar. Da segunda linha em diante é o objeto em si: event nomeia o que aconteceu, e as outras chaves carregam o contexto que as tags vão querer usar.
Nem todo push precisa de event. Um push só com dados, sem a chave event, apenas atualiza os valores disponíveis no dataLayer sem forçar a reavaliação dos triggers. Isso é útil para dados que já precisam estar prontos no carregamento da página, como o ID do usuário logado ou o tipo de página. A regra prática: use event quando quiser que uma tag dispare naquele momento; omita quando só quiser deixar o dado disponível para quando outra tag precisar.
Como o GTM lê o dataLayer
O GTM consome o dataLayer por dois caminhos, e vale entender os dois porque eles trabalham juntos.
O primeiro é o trigger de evento personalizado. Você cria um trigger do tipo Custom Event e informa o nome exato do evento, por exemplo lead_enviado. Toda vez que um push com event: 'lead_enviado' entra no dataLayer, esse trigger ativa e as tags associadas a ele disparam. É assim que o site avisa o GTM "isso aconteceu agora".
O segundo é a variável de dataLayer (Data Layer Variable). Ela lê um valor específico de dentro do objeto empurrado. Se o push trouxe valor_estimado: 500, você cria uma variável apontando para a chave valor_estimado e ela devolve 500 para a tag usar como parâmetro. Para valores aninhados, o caminho usa ponto: ecommerce.value lê o campo value dentro do objeto ecommerce.
Obs.: o caminho da variável precisa bater exatamente com a estrutura do push. Um ecommerce.value apontado onde o dado real é ecommerce.purchase.value devolve undefined, a tag envia vazio, e o relatório de receita fica zerado sem nenhum erro na tela. No Preview Mode, a aba "Data Layer" mostra o objeto exato de cada evento: é ali que você confere o caminho antes de confiar nele.
Exemplo real: dataLayer de e-commerce
O caso mais comum e mais valioso é o push de compra. O GA4 espera um objeto ecommerce estruturado, com o array items descrevendo os produtos. Veja como fica um push de purchase completo:
window.dataLayer = window.dataLayer || [];
dataLayer.push({ ecommerce: null }); // limpa o ecommerce anterior
dataLayer.push({
event: 'purchase',
ecommerce: {
transaction_id: 'ORD-98765',
value: 386.80,
currency: 'BRL',
items: [{
item_id: 'SKU-001',
item_name: 'Tênis de Corrida',
price: 289.90,
quantity: 1
}, {
item_id: 'SKU-014',
item_name: 'Meia Esportiva',
price: 48.45,
quantity: 2
}]
}
});O dataLayer.push({ ecommerce: null }) antes do evento é uma etapa que muita gente pula. Ele limpa o objeto ecommerce de um push anterior, evitando que dados de um produto vazem para o evento seguinte quando o usuário navega numa Single Page Application. Sem essa limpeza, o item da página de produto pode acabar contaminando o carrinho.
Repare no transaction_id. Ele é obrigatório em compra porque é a chave que permite deduplicar a venda: sem ele, o GA4 pode contar a mesma compra duas vezes se a página de obrigado for recarregada, e o Gerenciador de Eventos do Meta não consegue casar o evento do Pixel com o da API de Conversões. Um único ID único por transação resolve os dois problemas de uma vez.
Os erros que mais quebram o dataLayer
Na minha experiência auditando containers, os problemas de dataLayer se concentram em três padrões. Eles são silenciosos: a tag parece configurada, o site parece funcionar, e mesmo assim o dado chega vazio ou errado.
Push depois do trigger avaliar (race condition). Se o push com os dados acontece depois de a tag já ter disparado, a variável de dataLayer lê o valor antigo ou undefined. O caso clássico é a tag de conversão disparar no carregamento da página enquanto o push com o valor da compra só chega meio segundo depois, via JavaScript assíncrono. A tag lê o que existe naquele instante, e o que existe ainda é vazio. A ordem correta é sempre empurrar o dado antes de disparar o evento que a tag escuta.
Nome de chave inconsistente. O site empurra valorCompra num lugar, valor_compra em outro e purchase_value num terceiro. A variável do GTM aponta para um único nome e devolve undefined nos demais. Nomenclatura de dataLayer é contrato: definiu value, é value em toda a operação. Mistura de camelCase com snake_case na mesma base é uma das fontes mais comuns de parâmetro que chega zerado.
dataLayer só no template do tema. A plataforma de e-commerce injeta o dataLayer na página de produto padrão, mas não na landing page de campanha, no checkout customizado ou na página de obrigado que o dev montou à parte. Aí o traqueamento funciona no ambiente de teste e falha justamente na página que gera receita. Vale conferir cada template de página que participa da conversão, não só o principal.
Audite se o seu dataLayer está sendo lido
O dataLayer é invisível até quebrar, e quando quebra, quebra em silêncio: a tag dispara, o evento chega, mas os parâmetros vêm vazios e o relatório mente. O GTM Audit lê o JSON do seu container e mostra quais variáveis de dataLayer as tags esperam, onde os caminhos podem estar quebrados e quais eventos de conversão estão sem os campos obrigatórios, antes de você publicar. Para o passo seguinte, o guia completo de auditoria de container GTM mostra o processo de ponta a ponta, e a configuração do GA4 no GTM conecta o dataLayer às tags de analytics.
FAQ
Preciso saber programar para usar o dataLayer?
Para ler o dataLayer no GTM (criar variável de dataLayer e trigger de evento personalizado), não. Isso é tudo pela interface do GTM. Para popular o dataLayer com os dados certos no momento certo, alguém precisa colocar o dataLayer.push() no código do site: normalmente um dev, ou a própria plataforma de e-commerce, que já injeta boa parte dos pushs. O analista de traqueamento define o que precisa estar no push; o dev garante que está lá.
Qual a diferença entre dataLayer e variável de dataLayer?
O dataLayer é o array window.dataLayer no site, onde os dados são empurrados. A variável de dataLayer é um recurso do GTM que lê um valor específico de dentro desse array. O dataLayer é a fonte; a variável é o canudo que puxa um campo dela para a tag usar. Um push traz o objeto inteiro; cada variável lê uma chave desse objeto.
Preciso limpar o dataLayer entre eventos?
Em e-commerce, sim, principalmente para o objeto ecommerce. O dataLayer.push({ ecommerce: null }) antes de cada novo evento de e-commerce evita que os itens de um push anterior vazem para o próximo. Isso é crítico em Single Page Applications, onde a página não recarrega e o dataLayer acumula estado entre navegações.
Por que minha variável de dataLayer volta undefined?
As três causas mais comuns: o caminho da variável não bate com a estrutura real do push (confira na aba "Data Layer" do Preview Mode); o push acontece depois de a tag já ter disparado (problema de ordem); ou a chave tem nome diferente do esperado em alguma página. Nos três casos, o Preview Mode mostra o objeto exato que chegou no dataLayer, e é comparando esse objeto com o caminho da variável que você acha a divergência.