CRBRASIL
Analytics

Dicionário de eventos: como padronizar o tracking entre GA4, session replay, testes A/B e CRM

Por CRO Brasil ·

Dicionário de eventos: como padronizar o tracking entre GA4, session replay, testes A/B e CRM

O mesmo clique vira “add_to_cart” no GA4, “Adicionou ao carrinho” na CleverTap e “cart_click” no Hotjar. Veja como criar um dicionário único que todas as ferramentas usam.

Índice do artigo

O problema: cada ferramenta com o seu vocabulário

Uma operação digital madura usa várias ferramentas ao mesmo tempo: analytics (GA4), session replay (Clarity, Hotjar, Fullstory, UXCam), experimentação (VWO, ABsmartly), personalização (Croct, Dynamic Yield) e engajamento (CleverTap, Emarsys). Cada uma recebe eventos. Se cada time instrumenta a sua, o resultado é previsível: nomes diferentes para a mesma ação, propriedades com formatos incompatíveis e números que nunca batem.

Em uma frase: dicionário de eventos é o contrato que garante que “compra” significa a mesma coisa em todas as ferramentas.

O que é um dicionário de eventos

É um documento vivo (planilha, Notion, repositório) que lista cada evento de negócio, quando ele dispara, quais propriedades carrega e para quais ferramentas vai. Ele é a fonte de verdade para produto, analytics, CRO e engenharia.

A estrutura mínima de cada evento

Para cada linha do dicionário:

  1. Nome técnico (ex.: add_to_cart)
  2. Descrição de negócio (o usuário adicionou um item ao carrinho)
  3. Gatilho exato (resposta de sucesso da API do carrinho, não o clique no botão)
  4. Propriedades com nome, tipo e exemplo (item_id: texto; price: decimal; quantity: inteiro)
  5. Plataformas (web, app, servidor)
  6. Destinos (GA4, Clarity, Hotjar, CleverTap…)
  7. Dono (quem responde pelo evento)
  8. Status (proposto, implementado, validado, depreciado)

O gatilho é o campo mais negligenciado e o mais importante. “Clique no botão comprar” e “pedido confirmado pela API” geram números muito diferentes.

Convenção de nomes: as regras que evitam retrabalho

  • Um padrão só. Escolha snake_case em minúsculas (add_to_cart) e use em tudo. Quando uma ferramenta exige outro formato, o mapeamento fica documentado no dicionário.
  • Objeto + ação. form_submit, video_start, coupon_apply. Fica fácil agrupar e ordenar.
  • Nome é categoria, não valor. Nada de purchase_12345 ou view_tenis_azul. Valores vão em propriedades. No Hotjar, por exemplo, isso protege o limite de 10.000 eventos únicos por site; na CleverTap, o limite de 512 tipos de evento por conta.
  • Sem dado pessoal no nome ou nas propriedades. E-mail, CPF e telefone não entram em evento; identificação tem API própria em cada ferramenta.
  • Reaproveite os eventos recomendados do GA4 quando existirem (view_item, add_to_cart, begin_checkout, purchase). Eles viram a espinha dorsal do dicionário.

Um evento, muitos destinos: o papel da camada de dados

O desenho que escala é: a aplicação publica o evento uma única vez na camada de dados (dataLayer), e o Google Tag Manager distribui para cada ferramenta com as adaptações necessárias.

dataLayer.push({

event: 'add_to_cart',

ecommerce: {

items: [{ item_id: 'SKU-123', price: 199.9, quantity: 1 }]

}

});

A partir desse push, o GTM dispara:

  • a tag de evento do GA4;
  • window.clarity(“event”, “add_to_cart”) no Clarity;
  • hj(‘event’, ‘add_to_cart’) no Hotjar;
  • FS(‘trackEvent’, { name: ‘add_to_cart’, properties }) no Fullstory;
  • ScarabQueue.push([‘cart’, …]) na Emarsys;
  • clevertap.event.push(‘add_to_cart’, props) na CleverTap.

Uma fonte, vários destinos, zero divergência de dado entre eles.

Para app, o equivalente é uma camada de abstração no código (um “tracker” interno) que recebe o evento e repassa para cada SDK.

Os limites de cada ferramenta que o dicionário precisa respeitar

  • Hotjar: nomes de até 250 caracteres, conjunto restrito de caracteres, até 10.000 eventos únicos por site.
  • Fullstory: tipos inferidos pelo valor na API v2; números viram decimal, a menos que um schema declare inteiro.
  • CleverTap: até 512 tipos de evento e 256 propriedades por tipo; valores escalares ou data.
  • UXCam: até 100 propriedades por usuário, números enviados como texto.
  • VWO FME: eventos só são contabilizados se ligados a experimentos ativos.
  • Emarsys: o comando cart precisa ir em toda página, mesmo vazio.

Documente esses limites numa aba do próprio dicionário.

Governança: quem cria, quem aprova, quem remove

  1. Proposta: qualquer time pode propor um evento, sempre ligado a uma pergunta de negócio.
  2. Revisão: analytics valida nome, propriedades e duplicidade.
  3. Implementação: engenharia implementa na camada de dados.
  4. Validação: QA confere no preview do GTM, no DebugView do GA4 e no modo debug de cada ferramenta.
  5. Depreciação: evento sem uso há um período definido é marcado como depreciado e removido na próxima limpeza.

Os erros que mais aparecem

  1. Evento disparado no clique em vez da confirmação de sucesso.
  2. O mesmo evento com nomes diferentes em cada ferramenta.
  3. Valores dinâmicos no nome do evento.
  4. Propriedades com tipos inconsistentes (preço como texto em um lugar, número em outro).
  5. Dicionário criado uma vez e nunca mais atualizado.

Perguntas frequentes

O que é um dicionário de eventos?

Um documento que define cada evento de negócio, seu gatilho, propriedades, destinos e responsável, servindo de fonte de verdade para todas as ferramentas.

Qual a diferença entre dicionário de eventos e plano de mensuração?

O plano de mensuração parte dos objetivos e KPIs do negócio; o dicionário é o detalhamento técnico dos eventos que alimentam esses KPIs.

Qual padrão de nomenclatura usar para eventos?

Um só, em todas as ferramentas. snake_case minúsculo com objeto + ação é o mais comum, alinhado aos eventos recomendados do GA4.

Como enviar o mesmo evento para várias ferramentas?

Publicando uma vez na camada de dados e distribuindo pelo Google Tag Manager para cada destino.

Posso colocar o ID do pedido no nome do evento?

Não. O ID vai em propriedade; o nome é a categoria da ação.

Quem deve ser o dono do dicionário de eventos?

Normalmente o time de analytics, com participação obrigatória de produto e engenharia.