Escrever o contrato de dados que o desenvolvedor consegue implementar

Com o contêiner organizado, falta decidir o que o site entrega para ele ler. Sem contrato, o desenvolvedor escolhe nomes por conta própria ("enviouForm", "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 e nenhum relatório que some os três.

O custo aparece na hora de responder à pergunta do negócio. Quantos orçamentos vieram da campanha de setembro? Se o evento se chama generate_lead numa página e lead_form noutra, a resposta exige uma exploração com filtro que só a Marina sabe montar. E a coleção de relatórios de lead do GA4 fica vazia, porque ela só reconhece os nomes recomendados.

O contrato de dados resolve isso com quatro decisões: de qual categoria cada evento vem, como ele se chama, o que o dataLayer carrega e em que instante o disparo acontece. A Verde Vivo saiu daqui com uma especificação de 12 eventos para o site em Next.js, e Caio implementou sem uma única reunião de esclarecimento.

Os eventos do GA4 vêm de quatro categorias, e saber de qual vem cada um evita reimplementar o que já existe. Os automáticos (first_visit, session_start, user_engagement) disparam pela própria tag, sem configuração. Os da medição otimizada (page_view, scroll, click, file_download, form_start, form_submit, view_search_results, video_start) disparam quando a opção está ligada no fluxo. Os recomendados têm nome e parâmetros definidos pelo Google, mas exigem implementação. Os personalizados são inventados pela empresa.

A preferência pelo recomendado é uma regra de economia. Um purchase com transaction_id, value, currency e o array items preenche os relatórios de e-commerce sem ninguém configurar nada. Um generate_lead, seguido de qualify_lead, working_lead e close_convert_lead ou close_unconvert_lead (os seis eventos de lead que o Google documenta desde 2024), preenche a coleção de geração de leads e os públicos por estágio. O mesmo dado com nome inventado só vira relatório depois de trabalho manual.

A nomenclatura para o que sobra é curta: letras minúsculas, palavras separadas por sublinhado, verbo ou objeto que descreve o acontecimento e não a tela (whatsapp_click, não botao_verde_rodape). Nomes reservados pelo Google não podem ser usados, e um evento com o nome oficial e parâmetros diferentes dos oficiais engana quem lê o relatório pronto. O contrato lista cada nome uma vez, com a categoria e o dono.

O dataLayer é o lugar onde o site deposita o que a tag vai ler, e a estrutura dele é a parte do contrato que o desenvolvedor mais usa. É um array JavaScript em que cada push carrega o nome do evento e os dados no formato que o GA4 espera. O exemplo abaixo é o generate_lead da Verde Vivo, disparado depois que o servidor gravou o orçamento.

O momento do disparo é a decisão que mais separa medição confiável de medição que parece funcionar. Um mesmo formulário passa por cinco instantes, e cada um merece um evento próprio ou nenhum. A intenção é o clique em "Pedir orçamento" que abre o formulário. A tentativa é o envio. O erro é a resposta de validação. O sucesso é a resposta do servidor com identificador. A confirmação do servidor, dias depois, é o pagamento do Pix ou a etapa do CRM, que o capítulo 31 envia de fora do navegador.

Formulários em React e em outras bibliotecas mudam a regra do jogo. O envio acontece por JavaScript, sem recarregar a página, e a medição otimizada registra form_submit no instante do clique, tenha o servidor aceitado ou não. O contrato diz que form_submit é diagnóstico de funil e que generate_lead só existe depois da resposta bem-sucedida, com o lead_id gravado. A diferença entre os dois é a taxa de erro do formulário, que a Verde Vivo nunca tinha medido.

A aplicação de página única (o site em que a troca de rota acontece sem recarregar a página, como o Next.js da Verde Vivo) traz o problema mais frequente desta trilha. A Google tag dispara page_view no carregamento inicial e, por padrão, não sabe que a URL mudou depois. A medição otimizada tem a opção de registrar page_view em mudança de histórico do navegador, e o desenvolvedor pode enviar um page_view manual a cada rota. Ligar os dois gera page_view em dobro.

A escolha entre os dois caminhos depende de quem controla o título e os parâmetros. A opção automática é suficiente quando a URL diz tudo. O push manual ganha quando o título só fica pronto depois que a rota carrega os dados, ou quando o page_view precisa levar um parâmetro da página (a categoria da planta, o estágio do funil). Em qualquer caso, o contrato registra qual dos dois está ligado, e o outro fica desligado por escrito.

Armadilha comum: disparar o evento de sucesso no clique do botão porque "a API quase nunca falha". A tag não sabe da API, e o relatório passa a contar a tentativa como resultado. Quando a integração com o CRM cai por um dia, o site continua registrando leads que nunca existiram, e ninguém percebe até o comercial reclamar do silêncio.

A especificação da Verde Vivo nasceu num documento de duas páginas: nome do evento, categoria, momento exato, parâmetros com tipo e exemplo, dono e critério de teste. Caio recebeu o documento numa sexta e entregou a implementação na quarta seguinte, com um push por evento e uma função utilitária que valida os campos antes de chamar o dataLayer.

O page_view duplicado apareceu na primeira semana de teste, depois de a Google tag ter ficado única no capítulo 5: o site ainda mostrava 2,4 visualizações por sessão contra 1,3 da loja Shopify, e o DebugView exibia dois page_view a cada troca de rota, um deles com o título da rota anterior. Marina desligou a opção de mudança de histórico na medição otimizada e manteve o push manual, que levava o título certo.

Com a especificação no ar, setembro fechou com 92 generate_lead, 41 form_error (a maioria por CNPJ digitado com pontuação, corrigida no formulário na semana seguinte) e 1,4 visualizações por sessão no site. A soma de generate_lead com form_error bateu com form_submit em 131 de 133 casos, e os dois restantes foram tentativas de envio com a rede caída, sem resposta do servidor.

Escreva hoje, para o evento mais importante do seu site, as cinco linhas do contrato: nome, categoria, momento do disparo, parâmetros com exemplo e critério de teste. Entregue ao desenvolvedor e conte quantas perguntas voltam; o critério de acerto é nenhuma. O próximo capítulo registra os parâmetros desse contrato como dimensões e métricas, dentro dos limites que a propriedade padrão impõe.