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
Para se aprofundar
Para se aprofundar, assista ao episódio do canal da Métricas Boss sobre o tema:
- O problema: cada ferramenta com o seu vocabulário
- O que é um dicionário de eventos
- A estrutura mínima de cada evento
- Convenção de nomes: as regras que evitam retrabalho
- Um evento, muitos destinos: o papel da camada de dados
- Os limites de cada ferramenta que o dicionário precisa respeitar
- Governança: quem cria, quem aprova, quem remove
- Os erros que mais aparecem
- Perguntas frequentes
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:
- Nome técnico (ex.: add_to_cart)
- Descrição de negócio (o usuário adicionou um item ao carrinho)
- Gatilho exato (resposta de sucesso da API do carrinho, não o clique no botão)
- Propriedades com nome, tipo e exemplo (item_id: texto; price: decimal; quantity: inteiro)
- Plataformas (web, app, servidor)
- Destinos (GA4, Clarity, Hotjar, CleverTap…)
- Dono (quem responde pelo evento)
- 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
- Proposta: qualquer time pode propor um evento, sempre ligado a uma pergunta de negócio.
- Revisão: analytics valida nome, propriedades e duplicidade.
- Implementação: engenharia implementa na camada de dados.
- Validação: QA confere no preview do GTM, no DebugView do GA4 e no modo debug de cada ferramenta.
- Depreciação: evento sem uso há um período definido é marcado como depreciado e removido na próxima limpeza.
Os erros que mais aparecem
- Evento disparado no clique em vez da confirmação de sucesso.
- O mesmo evento com nomes diferentes em cada ferramenta.
- Valores dinâmicos no nome do evento.
- Propriedades com tipos inconsistentes (preço como texto em um lugar, número em outro).
- 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.
Estude com a Métricas Boss
Quem quer dominar analytics, CRO e mensuração na prática pode estudar com o time que faz a CRO Brasil. A MB Prime reúne mais de 20 cursos de Digital Analytics, GA4, Google Tag Manager, GTM server-side, Looker Studio e Product Analytics, com plano de estudos, materiais, certificado e comunidade de alunos. É também onde ficam as lives da CRO Brasil e as gravações do CRO Summit.
Precisa de uma consultoria de analytics? Conheça a Métricas Boss, que ajuda times a estruturar a mensuração, auditar os dados e transformar tracking em decisão. Peça um diagnóstico pelo site.
