Mapa de eventos entre plataformas: um evento, muitos destinos, um só nome

Uma mesma compra vira Purchase na Meta, CompletePayment no TikTok, uma conversion do tipo purchase no Google, um checkout no Pinterest. Quatro nomes para o mesmo acontecimento — e é aí que a mensuração começa a rachar. Cada equipe, cada plataforma, cada integração ao longo dos anos foi batizando o evento à sua maneira, mapeando os campos de um jeito próprio, decidindo por conta o que conta como conversão. O resultado é um emaranhado em que a Meta conta um número, o Google conta outro, e ninguém sabe explicar a diferença porque não existe uma fonte única que diga o que cada evento significa e para onde ele vai. A discrepância entre plataformas deixa de ser uma característica esperada e vira um mistério insolúvel.

A saída não é forçar todas as plataformas a usar o mesmo nome — elas não deixam. A saída é ter um mapa de eventos: um documento único e versionado que define os seus eventos de negócio de forma canônica e descreve, para cada um, como ele se traduz no vocabulário de cada plataforma de destino. Um evento, muitos destinos, um só nome interno. Sem esse mapa, cada integração vira uma interpretação isolada; com ele, todas partem da mesma verdade.

O problema: cada plataforma fala uma língua#

Não há como escapar do fato de que os destinos têm vocabulários diferentes. A mesma ação tem nomes, campos obrigatórios e formatos distintos em cada um:

• Na Meta, a compra é Purchase, com value, currency, content_ids, content_type.
• No TikTok, é CompletePayment, com value, currency, contents.
• No Google Ads, é uma conversão com uma ação de conversão específica, valor e moeda.
• No Pinterest e no LinkedIn, outros nomes e outros esquemas.

Se cada integração for escrita olhando só para o seu destino, três coisas ruins acontecem. Primeiro, a inconsistência: a mesma compra é definida de forma sutilmente diferente em cada lugar (uma inclui frete no valor, outra não), e os números divergem por construção. Segundo, a duplicação de lógica: a regra de "o que é uma compra válida" é reescrita em cada integração, e corrigir uma não corrige as outras. Terceiro, a fragilidade: uma mudança no negócio (um novo tipo de produto, uma nova moeda) exige tocar em N integrações, e alguma sempre fica para trás.

O evento canônico como fonte de verdade#

A ideia central é introduzir uma camada intermediária: o evento canônico. Em vez de o seu sistema pensar em termos de Purchase ou CompletePayment, ele pensa em termos de um evento de negócio próprio — digamos, compra_concluida — definido uma única vez, com um esquema claro:

• Que ação ele representa, sem ambiguidade (pedido pago, não pedido criado).
• Quais campos ele carrega e o que cada um significa (valor inclui ou não frete e impostos — decidido uma vez, para todos).
• Qual é o identificador estável do evento (o id do pedido), reusado como event_id de deduplicação em todos os destinos.

Toda a lógica de negócio — o que conta, quando dispara, qual o valor — vive nesse evento canônico, num lugar só. As plataformas viram meros destinos para os quais o evento canônico é traduzido. A regra é definida no centro; a tradução acontece na borda.

O mapa: canônico para plataforma#

O mapa é a tabela de tradução entre o evento canônico e cada destino. Para cada evento canônico, ele responde: em cada plataforma, qual é o nome, e como cada campo canônico vira um campo da plataforma.

Uma forma enxuta de expressar isso é uma estrutura de dados que a sua camada de conversão consulta:

``json { "compra_concluida": { "meta": { "event_name": "Purchase", "value": "valor", "currency": "moeda" }, "tiktok": { "event_name": "CompletePayment", "value": "valor", "currency": "moeda" }, "google": { "conversion_action": "compra", "value": "valor", "currency": "moeda" }, "pinterest": { "event_name": "checkout", "value": "valor", "currency": "moeda" } } } ``

Com o mapa como dado, adicionar um destino é acrescentar uma entrada, não reescrever lógica. Mudar a definição de um evento é mudar o canônico, e todos os destinos herdam. A tradução deixa de ser código espalhado e vira configuração central.

Um dicionário de eventos que todo mundo lê#

O mapa técnico precisa de um companheiro em prosa: o dicionário de eventos, um documento que descreve cada evento canônico em linguagem que marketing, dados e engenharia leem igual. Para cada evento:

• Nome canônico e o que ele significa em termos de negócio.
• Quando dispara — a condição exata (pedido com financial_status = paid, não qualquer pedido).
• Campos — cada um com significado, tipo e formato (valor é número em reais, sem símbolo; moeda em ISO-4217).
• Destinos — para quais plataformas vai e sob qual nome.
• Dono — quem responde por aquele evento.

Esse dicionário é o que acaba com a discussão eterna do "por que a Meta e o Google mostram números diferentes". Com ele, a resposta deixa de ser um mistério e vira uma consulta: os dois recebem o mesmo evento canônico, traduzido segundo o mapa, e as diferenças residuais têm causas conhecidas (janelas de atribuição, taxa de correspondência), não definições divergentes.

Nomear os eventos com disciplina#

Um mapa só se sustenta sobre uma convenção de nomes consistente. Alguns princípios que evitam o caos:

• Prefira os nomes canônicos da plataforma nos destinos. Purchase e CompletePayment são reconhecidos e otimizados pelas plataformas; inventar compra_v2 no destino perde os benefícios de eventos padrão.
• No canônico interno, use um padrão único — mesma língua, mesma caixa, mesma estrutura para todos (compra_concluida, lead_capturado, checkout_iniciado). Consistência interna importa mais que estética.
• Um evento por ação de negócio — não crie eventos redundantes para a mesma ação; isso reabre a fragmentação que o mapa veio resolver.
• Versione mudanças — alterar o significado de um evento é uma mudança de contrato; registre a versão e a data.

Como o mapa vive no tempo#

Um mapa de eventos não é um documento que se escreve uma vez e se esquece; é um artefato vivo, versionado junto com o código da camada de conversão. Quando o negócio ganha um novo tipo de evento, ele entra primeiro no dicionário e no mapa, com dono e definição, e só então na implementação. Quando uma plataforma muda seu esquema, o ajuste é localizado na entrada daquele destino. E quando alguém pergunta "esse evento existe? o que ele conta? para onde vai?", a resposta está no mapa, não na memória de quem configurou.

• Mudou o negócio — atualize o canônico e o dicionário primeiro; a implementação segue.
• Mudou a plataforma — ajuste a entrada do destino no mapa; o canônico não muda.
• Nasceu uma dúvida — o dicionário responde; se não responde, é sinal de que o mapa envelheceu e precisa de revisão.

Erros comuns ao montar o mapa#

• Não ter camada canônica — traduzir direto de cada integração para cada destino recria a fragmentação; o evento canônico no meio é o que centraliza a regra.
• Definir "valor" de forma diferente por destino — um inclui frete, outro não; a decisão precisa ser única no canônico.
• Inventar nomes nos destinos — usar compra_custom onde a plataforma reconhece Purchase joga fora a otimização de eventos padrão.
• Deixar o mapa desatualizado — um mapa que não acompanha as mudanças do negócio mente com aparência de verdade.
• Não versionar — sem histórico, ninguém sabe quando o significado de um evento mudou nem por quê.

O mapa como linguagem comum entre times#

Há um ganho do mapa que transcende o técnico: ele dá a marketing, dados e engenharia uma linguagem comum. Sem ele, cada área fala de conversão nos termos da ferramenta que usa — o marketing fala em Purchase da Meta, o time de dados fala na tabela do data warehouse, a engenharia fala no payload da API —, e a mesma coisa ganha três vocabulários que nunca se encontram. O evento canônico é o termo neutro que os três compartilham: quando alguém diz compra_concluida, todos sabem exatamente do que se trata, independentemente da ferramenta. Essa convergência de vocabulário reduz atrito em toda conversa sobre mensuração, e é o tipo de benefício que só aparece depois que o mapa existe — mas que, uma vez presente, ninguém quer abrir mão.

Discrepância esperada versus discrepância que denuncia um bug#

Com um mapa no lugar, a discussão sobre "por que os números não batem" ganha uma distinção que ela nunca teve antes: qual diferença é normal e qual é defeito. Sem o mapa, toda divergência parece um erro; com ele, você separa as duas categorias e para de caçar fantasmas.

A discrepância esperada nasce de características legítimas de cada plataforma, mesmo recebendo o evento canônico idêntico:

• Janelas de atribuição diferentes — a Meta e o Google creditam conversões em janelas distintas, então contam períodos diferentes do mesmo funil.
• Modelos de atribuição diferentes — last-click, data-driven, view-through; cada plataforma distribui o crédito à sua maneira.
• Taxa de correspondência diferente — o mesmo evento casa em proporções distintas em cada base, então cada uma "vê" um subconjunto diferente das conversões.
• Deduplicação e modelagem — o quanto cada plataforma modela o que não observou varia.

A discrepância que denuncia bug é outra coisa, e o mapa a expõe: se a Meta recebe muito mais eventos de compra do que o TikTok, algo na tradução ou no envio de um destino quebrou. Se o valor médio diverge de forma estrutural, um destino está incluindo frete e o outro não — exatamente o tipo de inconsistência que o evento canônico existe para prevenir. Com o mapa como referência, a pergunta deixa de ser "por que são diferentes?" e passa a ser "essa diferença cabe no esperado, ou é sinal de que a tradução quebrou?". A primeira pergunta é insolúvel; a segunda tem resposta.

Testar o mapa como um contrato#

Se o mapa é a fonte de verdade da tradução, ele precisa ser testável — porque uma tradução silenciosamente errada é pior que a ausência de tradução: ela produz números plausíveis e falsos. Tratar o mapa como um contrato verificável significa validar, de forma automatizada, que cada evento canônico produz o payload correto em cada destino.

• Teste a tradução de campos — dado um evento canônico de exemplo, o valor foi para o campo certo de cada plataforma, no formato certo? A moeda? O event_id?
• Teste os obrigatórios — cada destino tem campos que não podem faltar; um teste garante que a tradução os preenche, evitando o 422 que só apareceria em produção.
• Teste a cobertura — todo evento canônico tem entrada no mapa para todos os destinos que deveria alcançar? Um evento sem destino é uma conversão que some.

Esses testes viram uma rede de segurança para mudanças. Quando alguém altera a definição de um evento ou o esquema de um destino, os testes acusam a quebra antes de ela chegar à produção e distorcer semanas de dados. O mapa deixa de ser um documento que se espera estar certo e passa a ser um contrato que se prova estar certo.

Um mapa de eventos entre plataformas é o que transforma a mensuração de uma coleção de integrações independentes numa arquitetura coerente. O evento canônico define o significado uma vez; o mapa o traduz para cada destino; o dicionário deixa todo mundo lendo a mesma verdade. Com essa camada no meio, um evento pode ter quatro nomes em quatro plataformas e ainda assim representar exatamente a mesma coisa — que é a única forma de olhar para quatro relatórios e confiar que eles estão contando o mesmo acontecimento.