Taxonomia de eventos e dataLayer: o significado de cada evento

Com o contêiner organizado, falta decidir o que o site entrega para ele. Sem um documento combinado, o desenvolvedor escolhe nomes por conta própria, como "enviouForm" ou "lead_ok", o analista espera outros, e o evento chega ao relatório com um nome que ninguém procura. Dois meses depois, há três eventos para o mesmo acontecimento.

O custo aparece quando a diretoria pergunta quantos orçamentos vieram da campanha de setembro. Se o evento se chama generate_lead numa página e lead_form noutra, a resposta depende de uma análise que só uma pessoa sabe montar. O capítulo mostra como escrever a especificação de eventos: um documento que descreve cada fato do negócio, o momento em que ele vira evento e a prova de que chegou certo.

Quatro origens de evento, e só duas pedem código

Os eventos do Analytics vêm de quatro categorias, e saber de qual vem cada um evita refazer o que já existe. Os automáticos, como a primeira visita e o início de sessão, disparam pela própria tag. Os da medição otimizada disparam quando a opção está ligada no fluxo. Os recomendados têm nome e parâmetros definidos pelo Google e exigem implementação. Os personalizados são inventados pela empresa.

Preferir o recomendado é uma economia. Um purchase com número do pedido, valor, moeda e lista de itens preenche os relatórios de comércio eletrônico sem configuração extra. Para leads, o catálogo traz seis eventos, do pedido ao fechamento: generate_lead, qualify_lead, working_lead, disqualify_lead, close_convert_lead e close_unconvert_lead. Com esses nomes, os relatórios de geração de leads e os públicos por estágio funcionam; com nomes inventados, cada relatório vira trabalho manual.

Para o que sobra, a regra de nome é curta: letras minúsculas, palavras separadas por sublinhado e um nome que descreve o acontecimento, e não a tela, como whatsapp_click em vez de botao_verde_rodape. Usar um nome oficial com parâmetros diferentes dos oficiais engana quem lê o relatório pronto. A especificação lista cada nome uma vez, com a categoria e o dono.

Um formulário tem vários momentos, e só um deles é lead

O mesmo pedido de orçamento passa por momentos diferentes, e cada um merece um evento próprio ou nenhum. A pessoa começa a preencher, clica em enviar, pode receber uma recusa de validação e, se tudo der certo, o servidor grava o pedido e devolve um número. Dias depois, o comercial aceita ou descarta o pedido no CRM.

O pedido que conta é o da aceitação: o servidor gravou e devolveu um número. A ajuda do Google descreve o form_submit apenas como o envio do formulário; em formulários que enviam por JavaScript, sem recarregar a página, como os feitos em React, ele pode aparecer também para envios que o servidor recusa, e só um teste com envio recusado mostra o comportamento do site. Por isso o envio fica como diagnóstico de funil e o generate_lead só existe depois da resposta. Qual evento orienta os lances da mídia é outra decisão, tratada em Conversões do GA4 no Google Ads: escolher o resultado que orienta os anúncios.

A especificação também evita prometer contas que a realidade não fecha. Tentativas, recusas e aceitações têm relação entre si, mas não somam de forma exata: uma pessoa pode errar o CNPJ, corrigir e enviar de novo, e um envio pode ficar sem resposta com a rede caída. O documento registra a relação esperada e manda investigar quando ela muda de patamar.

A camada de dados é o recado que o site deixa para a tag

A camada de dados (dataLayer) é uma fila em que o site deposita informações para as tags lerem, como um quadro de recados na porta da cozinha. O push sozinho não envia nada ao Analytics. É a tag do Tag Manager, acionada por aquele nome de evento, que lê o recado, escolhe os parâmetros e manda para o destino. Por isso a especificação descreve as duas pontas: o que o site escreve e o que a tag envia.

O exemplo abaixo é o recado de pedido de orçamento da Verde Vivo, escrito só depois que a API respondeu com sucesso. O campo lead_id merece cuidado: qualquer script carregado na página consegue ler a camada de dados. Ali entra um código interno do orçamento, e nunca nome, e-mail ou telefone; a especificação diz se esse código segue para o Analytics ou fica só para o servidor ligar o evento ao CRM.

Eventos técnicos também passam pela camada de dados

Desde 8 de outubro de 2026, o comando de configuração da Google tag aparece na camada de dados como um evento chamado gtag.config. Ele é um evento técnico, sem significado de negócio. Um acionador do Tag Manager configurado para reagir a qualquer nome de evento passa a disparar com ele e pode criar contagens que ninguém pediu.

A especificação resolve isso listando os nomes de evento que acionam tags, um a um, e proibindo acionadores curinga em produção. Eventos técnicos ficam documentados à parte, para que ninguém os confunda com fatos do negócio.

Sites de página única pedem uma escolha escrita

Em sites que trocam de página sem recarregar, como o da Verde Vivo, a tag registra a primeira página, e as trocas seguintes só viram page_view por um de dois caminhos. O primeiro é a opção avançada da medição otimizada que registra páginas a partir das mudanças no histórico do navegador; ela funciona quando o site troca o endereço por esse mecanismo. O segundo é um page_view manual a cada troca de rota, enviado pelo desenvolvedor. Ligar os dois gera visualização em dobro. A especificação registra qual caminho está ligado, deixa o outro desligado por escrito e pede um teste no DebugView para cada tipo de rota.

A especificação da Verde Vivo coube em duas páginas

O documento traz, para cada evento, o nome, a categoria, o momento exato, os parâmetros com tipo e exemplo, o dono e o critério de teste. Caio recebeu numa sexta e entregou a implementação na quarta seguinte, com um recado por evento e uma função que confere os campos antes de escrever na camada de dados. As duas perguntas que ele fez durante o trabalho viraram linhas novas do documento.

A visualização em dobro apareceu na primeira semana de teste, depois que a Google tag já tinha ficado única: o site mostrava 2,4 visualizações por sessão contra 1,3 da loja, e o DebugView exibia dois page_view a cada troca de rota, um deles com o título da rota anterior. A causa era a opção automática ligada junto com um envio manual antigo; Caio removeu o manual, e a especificação passou a dizer qual caminho vale.

Setembro fechou com 92 pedidos de orçamento, o mesmo número do HubSpot, e 41 erros de validação, a maioria por CNPJ digitado com pontuação. O formulário passou a aceitar o CNPJ com ou sem pontos na semana seguinte, e o site estabilizou em 1,4 visualização por sessão.

O que pedir à equipe

Para o evento mais importante do seu site, peça a linha completa: nome, categoria, momento do disparo, parâmetros com exemplo, dono e critério de teste. A linha está pronta quando o desenvolvedor sabe dizer em que instante o evento dispara e como provar que chegou; cada dúvida que voltar entra no documento.

Alguns parâmetros dessa especificação vão virar colunas de relatório, e outros só aumentariam a confusão. O capítulo Dimensões e métricas personalizadas: o que merece aparecer no relatório mostra como escolher.