Fale Conosco

Arquitetura de Nomenclatura de Eventos: Como Organizar seu GTM sem Virar um Caos

Fábio Oliveira

Fórmulas de nome para tags, triggers e variáveis, snake_case no dataLayer, tracking plan e governança (pastas, workspace, versões) no GTM.

Contexto

O container GTM cresceu com a empresa. Tem Meta Nova Campanha, Click 3, GA4 - lead, e mais um generateLead no dataLayer que alguém colocou no release de sexta. No Tag Assistant ninguém sabe o que é legado. No GA4, Generate_Lead e generate_lead aparecem como dois eventos. No BigQuery, o mesmo “valor” vira coluna string e coluna number.

Isso não é “falta de carinho visual”. É dívida de rastreamento: auditoria lenta, disparos duplicados, regressão em cada sprint e container inchado que o browser ainda precisa baixar e avaliar.

Uma arquitetura de nomenclatura — tags, triggers, variáveis e eventos do dataLayer — transforma o GTM em índice legível. Este guia é o padrão mínimo para times em escala: fórmulas no web GTM, snake_case no GA4, um tracking plan como contrato, e governança de pasta/workspace/versão. Sem reescrever o stack inteiro em sGTM no primeiro dia.

Por que o nome importa

Ordem alfabética no GTM agrupa o que tem o mesmo prefixo. GA4 - … fica junto; Meta - … fica junto. Variáveis dlv - não se misturam com cjs - sem motivo.

O reverso: nome de campanha da semana no label da tag. Em seis meses, mídia pergunta se o purchase “ainda existe”; o único que sabe saiu. Preview e DebugView / Tag Assistant só aceleram se o timeline bater com nomes que o mapa também usa.

DIY por seletor CSS resolve a campanha de amanhã (eventos sem alterar o código); se o nome do evento GA4 também for da campanha da semana, o histórico no Analytics morre a cada rename.

Fórmulas no Web GTM

Um separador estável (-) e hierarquia fixa. Todo o time usa a mesma fórmula — melhor que inventar a “melhor” fórmula e cada agência criar a sua.

Tags

[Plataforma] - [Tipo] - [Descrição] (contexto opcional)

Exemplos:

  • GA4 - Config
  • GA4 - Event - generate_lead (contact form)
  • Meta - Event - Purchase
  • Google Ads - Conversion - form_submit

Plataforma primeiro: ordenação por vendor. Tipo (Config, Event, Conversion) separa inicialização de conversão. Descrição = o que o negócio entende; se o nome do evento GA4 for canônico, use-o igual na tag.

Triggers

[Tipo ou CE] - [Ação ou página] - [Detalhe]
  • Custom Event do dataLayer: CE - generate_lead (o trecho após CE - = nome exato do event no push)
  • Clique / visibilidade: Click - CTA pricing, Visibility - Thank you modal
  • Bloqueio: Blocking - Internal IP ou Blocking - All Link Clicks (prefixo Blocking agrupa exceções)

Variáveis

Origem do dado antes do conteúdo:

  • dlv - ecommerce.transaction_id — Data Layer Variable
  • cjs - sanitize_price — Custom JavaScript
  • const - meta_pixel_id — constante
  • url - utm_source — parâmetro de URL

Assim você não recria “mais um CJS” para ler o que já é dlv.

snake_case no dataLayer e no GA4

O nome que o front publica em dataLayer.push({ event: '…' }) e o nome que o GA4 grava são case-sensitive. generate_lead ≠ Generate_Lead ≠ generate-lead.

Regras úteis (alinhadas ao Help de event naming do GA4):

  • minúsculas + _ (snake_case)
  • começa com letra; só letras, números e _
  • sem espaços, hífens “estilo CSS”, acentos, !
  • não começar com prefixos reservados ga_, google_, firebase_
  • não começar com número (100_scroll → scroll_100)

Semântica: foque em negócio, não em cor de botão.

  • Evite: clique_botao_azul, Submit-Form!, Purchase_Event
  • Prefira: generate_lead, newsletter_subscribed, purchase, demo_requested

Parâmetros na mesma disciplina: user_status, form_id, plan_selected — não userStatus nem User-Status. Tipagem estável (number vs string no mesmo campo) evita dor no warehouse; o contrato de Data Layer para devs entra aqui.

Tracking plan: o contrato único

Sem documento, o front muda o event e analytics repara no funil vazio. O tracking plan (uma planilha ou página de wiki) é a fonte da verdade entre eng, produto e mídia:

  • Event name — snake_case exato
  • Description — o que o usuário fez
  • Triggering condition — quando o front emite (ex.: HTTP 200 do form, não só clique no botão)
  • Parameters — lista + tipo (string / number / boolean)
  • Source — web, app, server
  • Owner — time que mantém

Tudo o que não está no plan não é evento oficial de conversão — é experimento ou lixo a limpar. O mesmo mapa alimenta o checklist de auditoria de qualidade no GA4.

Pastas, workspace e versões

Pastas — agrupe por vendor (Analytics, Meta, Google Ads) ou por capability (Consent, Ecommerce, Lead forms). Tags soltas no root = caos em 200 itens.

Workspaces — um espaço por tarefa/sprint/agência, ex.: Agency - Consent Mode v2 ou Dev - Event purchase SPA. Dois humanos no mesmo workspace default viram merge conflitado e publish surpresa.

Versões — cada Publish com nome semântico e descrição: o que mudou, quem pediu, o que validou no Preview. Sem nota, rollback vira loteria.

Preview não substitui process: valide o draft, publique, smoke test em prod. Workflow de QA no Tag Assistant.

Server-side (só o naming)

Quando existir sGTM, as entidades novas pedem o mesmo rigor em outras palavras:

  • Client - GA4 - Web Ingestion
  • Transform - Hash - user_phone / Transform - Exclude - pii_email
  • sTag - Meta - Purchase API
  • triggers sGTM tipo stg - GA4 - Event Equals purchase

O detalhe de hospedagem e CAPI fica para o pilar server-side do blog. O ponto aqui: não chame a transformação de “New Transformation 2”.

Como sair do caos (fases)

  1. Documentar o tracking plan oficial (mesmo se o container ainda mentir).
  2. Auditar — pausar/remover tags duplicadas, triggers órfãos, vars mortas; reduzir bloat.
  3. Renomear e pastas no Web GTM segundo as fórmulas; alinhar eventos do plan (dual-fire temporário se o histórico no GA4 for crítico).
  4. Só então evoluir sGTM/PII se a arquitetura pedir — com naming já disciplinado no cliente.

Não renomeie 80 eventos de produção numa sexta sem janela e sem mapa de correspondência.

Checklist

  1. Toda tag começa por plataforma (GA4, Meta, Google Ads…).
  2. Todo Custom Event trigger é CE - [nome_exato_do_event].
  3. Variáveis com prefixo de tipo (dlv, cjs, const, url).
  4. Eventos e parâmetros no dataLayer em snake_case; sem ga_.
  5. Tracking plan preenchido para tudo que mídia chama de conversão.
  6. Pastas por vendor ou capability; root limpo.
  7. Workspace por tarefa; version note + Preview antes do Publish.
  8. Nada de nome de campanha da semana no nome do evento GA4.

Próximo passo

Nomenclatura é barata de definir e cara de adiar. Container legível encurta toda auditoria e cada handoff de agência.

Se o GTM já tem centenas de tags sem mapa, o próximo passo é uma auditoria objetiva: o que dispara, o que é legado, o que o tracking plan passa a oficializar — e o que some no publish seguinte.

Se quiser, partimos de um export do container (ou print do folder root) e devolvemos a taxonomia sugerida + lista do que pausar primeiro.