dataLayer: o guia completo da camada de dados no Google Tag Manager

Toda mensuração profissional que você já viu tem a mesma fundação invisível: uma camada de dados bem especificada.

O dataLayer é a ponte entre o código do seu site e o Google Tag Manager. Quando você quer dizer às ferramentas de análise qual produto foi comprado, qual o valor, qual o grupo da página ou quem é o usuário logado, é por essa ponte que a informação atravessa. O GTM sozinho enxerga cliques e envios; tudo que exige contexto do negócio vem da camada de dados.

E é exatamente por ser fundação que ela quebra caro: dataLayer mal especificada é a origem silenciosa de (not set), relatório de e-commerce vazio e retrabalho de desenvolvimento a cada nova tag.

O que é a camada de dados?

Tecnicamente, o dataLayer é uma variável JavaScript global do tipo array, declarada antes do snippet do GTM, que recebe objetos com informações no padrão chave-valor:

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

Cada informação nova entra com um push:

javascriptCopiar
window.dataLayer.push({
  event: "login",
  method: "email"
});

O GTM escuta o array: a chave event vira acionador de Evento Personalizado, e as demais chaves viram Variáveis de Camada de Dados, disponíveis para qualquer tag.

Dois detalhes técnicos que valem conhecer: o nome "dataLayer" é definido no quarto argumento do próprio snippet do GTM (e pode ser renomeado ali, embora quase nunca deva); e um push sem a chave event chega ao GTM como o evento genérico message, ou seja, sem event não há acionador de evento personalizado possível.

Os dois momentos de implementar

1. No carregamento da página: informações de contexto que já existem quando a página abre, empurradas antes do snippet do GTM no head. Exemplos: grupo da página (page_type), dados do produto na PDP, status de login, ID do usuário hasheado.

htmlCopiar
<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    page_type: "produto",
    user_logged: true
  });
</script>
<!-- snippet do GTM entra depois -->

2. Nas interações do usuário: pushes disparados quando algo acontece. Adição ao carrinho, avanço de etapa, envio de formulário customizado, erro exibido.

A ordem importa: push de contexto depois do GTM carregar significa tag disparando sem a informação, e o sintoma clássico é parâmetro chegando vazio em parte dos hits.

O padrão de e-commerce do GA4: o objeto ecommerce aninhado

Para os eventos de comércio eletrônico (view_item, add_to_cart, begin_checkout, purchase e os demais), o GA4 espera um formato específico: as informações aninhadas dentro do objeto ecommerce, com os produtos no array items.

javascriptCopiar
window.dataLayer.push({ ecommerce: null }); // limpa o objeto anterior
window.dataLayer.push({
  event: "purchase",
  ecommerce: {
    transaction_id: "T12345",
    value: 59.89,
    tax: 4.90,
    shipping: 5.99,
    currency: "BRL",
    coupon: "PROMO_VERAO",
    items: [{
      item_id: "12345",
      item_name: "Camiseta Métricas Boss",
      item_brand: "MB",
      item_category: "Vestuário",
      item_variant: "Preta",
      price: 15.25,
      quantity: 1
    }]
  }
});

Três regras que evitam 90% dos problemas:

1. •Limpe o objeto antes de cada push de e-commerce (ecommerce: null). Sem isso, dados do evento anterior vazam para o seguinte, e o purchase herda items do add_to_cart.
2. •Respeite os nomes do padrão: item_id, item_name, value, currency. A tag de evento do GA4 no GTM lê o objeto ecommerce automaticamente quando os nomes batem; qualquer criatividade na nomenclatura desliga o automático e esvazia o relatório de monetização.
3. •Números como números: value e price sem aspas de milhar, ponto como decimal, currency sempre presente.

Para o mapeamento completo de todos os eventos de e-commerce por tipo de página, veja o guia de implementação da camada de dados para plataformas de e-commerce.

eventCallback e eventTimeout: quando o push precisa segurar um redirecionamento

Em interações que tiram o usuário da página (clique que redireciona, envio que navega), a tag pode não ter tempo de disparar. O par eventCallback e eventTimeout resolve: o callback executa o redirecionamento depois que as tags dispararam, e o timeout força a execução após o limite em milissegundos, protegendo a experiência caso algo trave.

javascriptCopiar
window.dataLayer.push({
  event: "clique_saida",
  eventCallback: function() { window.location = "/destino"; },
  eventTimeout: 2000
});

A especificação: o documento que economiza meses

A camada de dados é um contrato entre marketing e desenvolvimento, e contrato verbal quebra. A especificação profissional documenta, para cada push: o nome do evento, as chaves e tipos de cada valor, o momento exato do disparo, a página onde ocorre e um exemplo completo de payload.

Esse documento é o que permite ao desenvolvedor implementar sem adivinhar, ao analista validar sem depender de memória e à próxima agência entender o que existe sem arqueologia. Nas auditorias da Métricas Boss, a ausência de especificação é o melhor preditor de camada de dados quebrada.

Os erros que aparecem em auditoria

1. •Push depois do GTM: contexto chegando tarde, parâmetros vazios em parte dos hits.
2. •ecommerce sem limpeza: dados de um evento vazando para o próximo.
3. •Nomenclatura fora do padrão GA4: relatório de monetização vazio com dado "chegando".
4. •Tipos errados: value como string com vírgula, quantity como texto.
5. •dataLayer duplicada: dois snippets declarando o array, um apagando o outro.
6. •Dependência de scraping do DOM: variáveis raspando HTML em vez de camada de dados; quebra a cada mudança de layout.

Perguntas frequentes sobre dataLayer

O que é o dataLayer em uma frase? É a variável JavaScript global que transporta informações do código do site para o Google Tag Manager, permitindo que tags de análise e mídia recebam contexto do negócio (produto, valor, usuário, página).

Preciso de desenvolvedor para implementar a camada de dados? Para os pushes de contexto e de e-commerce, sim: eles vivem no código do site ou da plataforma. O papel do analista é entregar a especificação; o do desenvolvimento, implementá-la; o do GTM, consumi-la.

Qual a diferença entre dataLayer e variáveis do GTM? O dataLayer é a fonte; as Variáveis de Camada de Dados no GTM são os leitores que extraem cada chave para uso em tags e acionadores.

Por que meu relatório de e-commerce está vazio se o dataLayer existe? Quase sempre por nomenclatura fora do padrão do GA4 (objeto ecommerce, array items, chaves item_id/item_name/value) ou pela falta da limpeza com ecommerce: null entre eventos.

O dataLayer funciona com server-side? Sim: no fluxo server-side, a camada de dados continua alimentando o container web, que encaminha os eventos ao container de servidor. A qualidade da especificação importa igual, ou mais.

Lucian Fialho

Fundador e CTO da Métricas Boss, com sólido background em tecnologia, tendo passado por empresas como Comprafacil.com e Leader.com. Atuou no desenvolvimento de lojas como Globo, Olimpíadas do Rio, Ipiranga Shop, entre outras.

Publicado em 6 de julho de 2026