TikTok Events API avançada: deduplicação, EMQ e payloads que a plataforma aceita

O que a Events API resolve que o pixel do TikTok não resolve#

O pixel do TikTok roda no navegador e depende de que o JavaScript carregue, o consentimento seja aceito e nenhum bloqueador atrapalhe. Em campanhas de performance, essa dependência custa caro: uma fração relevante das conversões some antes de chegar aos servidores do TikTok. A Events API é o canal server-side que envia o evento diretamente do seu backend para a API de eventos do TikTok, sem depender do dispositivo do usuário para transmitir.

A diferença prática não é só "mais eventos". É controle sobre quando o evento sai. Numa arquitetura bem feita, o pixel dispara CompletePayment no navegador de forma otimista, mas quem confirma a conversão para a plataforma é o servidor — e só depois que o pagamento foi realmente aprovado. Esse é o ponto que separa uma implementação amadora de uma madura: o TikTok recebe o evento de conversão quando a conversão é real, não quando o usuário clicou em "finalizar".

Neste guia, o foco é a camada avançada: como estruturar o payload, como calcular e melhorar o Event Match Quality (EMQ), como deduplicar contra o pixel sem contar duas vezes e como não estourar limites de rate.

Anatomia do payload da Events API#

A Events API (versão atual sob o endpoint de event/track) espera um envelope com alguns campos obrigatórios e vários opcionais que impactam diretamente a qualidade da correspondência. Os campos que sustentam a estrutura são:

• event_source — para eventos de site, o valor é web. Existem também app e offline, cada um com regras próprias.
• event_source_id — o ID do seu pixel/ativo do TikTok. É o que amarra o evento à conta certa.
• data — o array de eventos. Cada item carrega um evento individual.

Dentro de cada evento, os campos que mais importam:

• event — o nome do evento padrão (CompletePayment, Purchase, AddToCart, CompleteRegistration, SubmitForm, Lead). Usar o nome padronizado é o que permite ao TikTok otimizar. Nome custom sem mapeamento vira evento cego.
• event_time — timestamp Unix em segundos. O TikTok rejeita eventos muito antigos (a janela prática é de alguns dias); não guarde evento parado por semanas esperando enviar.
• event_id — a chave de deduplicação. É o campo mais importante para quem roda pixel e server juntos.
• user — o objeto com as match keys (dados de identidade hasheados).
• properties — valor, moeda, contents, content_id, content_type, quantidade.
• page — URL e referrer, quando disponível.

Match keys: o que hashear e o que enviar em claro#

O objeto user é onde mora o EMQ. Quanto mais sinais de identidade de qualidade você envia, maior a probabilidade de o TikTok casar o evento com um usuário logado na plataforma. Os sinais dividem-se em dois grupos.

Dados de PII, que precisam ir hasheados em SHA-256 após normalização:

• email — minúsculas, sem espaços nas pontas, antes do hash.
• phone_number — formato E.164 (com código do país, sem símbolos), depois hash.
• external_id — seu identificador interno do usuário (ID de cliente do CRM, por exemplo), também hasheado. Esse é um dos sinais mais subestimados: um external_id estável eleva o match mesmo quando email e telefone faltam.

Dados de contexto/clique, que vão em claro (não hasheados):

• ttclid — o TikTok Click ID, capturado da URL quando o usuário chega por um anúncio e persistido em cookie first-party. É o sinal de correspondência mais forte que existe, porque liga o evento diretamente ao clique.
• ttp — o valor do cookie _ttp gerado pelo pixel, que conecta o server ao contexto do navegador.
• ip e user_agent — capturados no servidor a partir da requisição original do usuário. Cuidado: precisa ser o IP e o user-agent do cliente, não o do seu servidor. Se você envia o IP do datacenter, o EMQ despenca.

A normalização antes do hash não é detalhe cosmético. João@Email.com e joao@email.com geram hashes diferentes; só o segundo casa. Centralize a normalização numa única função de borda para que pixel e server produzam exatamente o mesmo hash a partir do mesmo dado — senão a deduplicação por identidade falha silenciosamente.

Event Match Quality (EMQ): como ler e melhorar#

O EMQ é a nota de 0 a diversos níveis que o TikTok dá à sua capacidade de casar eventos com usuários. Ele aparece no Events Manager e é o termômetro mais honesto da sua implementação server-side. Uma nota baixa significa que o TikTok está recebendo eventos mas não consegue atribuí-los, o que degrada a otimização de campanha e infla o custo por conversão.

Os alavancas concretas para subir o EMQ:

• Envie ttclid sempre que existir. Persista-o no momento do primeiro toque e recupere-o na conversão. Um evento de compra sem ttclid mas com email vale menos que um com os dois.
• Adicione external_id. É barato de implementar (você já tem o ID do cliente) e mede muito no agregado.
• Nunca envie campos vazios ou com placeholder. Mandar email com string vazia ou "null" como texto é pior que omitir — o TikTok pode tratar como sinal ruim.
• Garanta IP e user-agent do cliente. Em arquiteturas com proxy/CDN, leia o cabeçalho de encaminhamento correto (o primeiro IP confiável da cadeia), não o IP direto da conexão.
• Consistência de event_time. Enviar o horário real da conversão, e não o horário do processamento em lote, mantém a janela de atribuição precisa.

Trate o EMQ como uma métrica de produção: acompanhe-o por evento e por semana. Uma queda súbita geralmente denuncia uma regressão — um deploy que parou de capturar o ttclid, uma mudança de normalização, um campo que virou nulo.

Deduplicação com o pixel: o par event_id + event#

A recomendação da casa é rodar pixel e Events API em paralelo (arquitetura híbrida) para maximizar cobertura, mas isso só funciona se a deduplicação estiver certa. Sem ela, cada compra conta duas vezes e sua taxa de conversão vira ficção.

O mecanismo do TikTok usa dois campos combinados: o event_id e o nome do event. Quando o pixel e o server enviam o mesmo CompletePayment com o mesmo event_id, o TikTok reconhece que é o mesmo fato e mantém apenas uma ocorrência. As regras práticas:

• Gere o event_id no servidor no momento em que o pedido é criado (por exemplo, o ID do pedido ou um ULID atrelado a ele). Esse mesmo valor precisa chegar ao pixel no navegador e ao envio server-side.
• Não use timestamp como event_id. Dois eventos legítimos podem colidir e um deles seria descartado indevidamente.
• Mantenha o mesmo nome de evento nas duas pontas. CompletePayment no pixel e Purchase no server não deduplicam — o TikTok os vê como eventos distintos.

Vale reforçar: a deduplicação não é motivo para mandar tudo em dobro por preguiça. O papel de cada canal é claro — o pixel cobre o contexto do navegador e captura sinais como o ttp; o server garante a entrega e envia o evento no momento da conversão confirmada.

Enviar só na conversão real: o padrão de webhook#

O maior valor da Events API server-side aparece quando você desacopla o evento da interação do usuário. Em vez de disparar CompletePayment quando o cliente clica em pagar, você dispara quando o gateway confirma o pagamento.

O fluxo maduro:

1. O usuário finaliza a compra; o pedido nasce com status pendente.
2. O gateway de pagamento processa e, quando aprova, chama um webhook do seu backend.
3. O handler do webhook valida a assinatura, confirma que o pedido está pago e só então monta o payload e chama a Events API.
4. O evento vai com o event_id do pedido, as match keys que você já tinha capturado no checkout e o valor real cobrado.

Esse desenho elimina a conversão falsa por boleto não pago, por cartão recusado após a tela de sucesso, por assinatura que não completou o primeiro ciclo. O TikTok otimiza para receita real, não para intenção.

Entrega confiável e limites#

Chamar uma API externa dentro do fluxo de conversão traz um risco: se o TikTok estiver indisponível ou lento, você não pode perder o evento nem travar a resposta ao gateway. O padrão da casa é o outbox: o handler do webhook grava o evento numa fila persistente na mesma transação em que confirma o pedido, e um worker separado consome a fila e chama a Events API com retry e backoff.

Pontos de atenção operacionais:

• Idempotência. Se o worker reprocessa um item por causa de um retry, o event_id estável garante que o TikTok deduplica. Ainda assim, marque o item como enviado com um CAS atômico para não gerar chamadas redundantes em massa.
• Batch. A Events API aceita múltiplos eventos por chamada no array data. Agrupe para reduzir overhead, respeitando o teto de eventos por requisição.
• Códigos de erro. Trate a resposta de verdade — um 40000 de payload malformado não se resolve com retry, precisa de correção; já um 5xx transitório merece nova tentativa. Nunca engula o erro; logue com o trace_id e alerte quando a taxa de falha subir.
• Test Events. Antes de mandar para produção, use o código de teste do Events Manager para validar o formato sem sujar os números reais. Confira que o EMQ do evento de teste é alto — se já nasce baixo, o payload está incompleto.

Checklist de maturidade#

Uma implementação avançada da Events API do TikTok passa por estes pontos:

• event_id estável, gerado no servidor, compartilhado com o pixel.
• ttclid capturado no primeiro toque e persistido em cookie first-party.
• Match keys hasheadas com normalização idêntica nas duas pontas.
• external_id incluído sempre que houver usuário identificado.
• IP e user-agent do cliente, nunca do servidor.
• Evento de conversão disparado no webhook de pagamento aprovado.
• Outbox com retry, idempotência e alerta em falha.
• EMQ monitorado por evento e por semana como métrica de produção.

Com essa base, o TikTok recebe eventos completos, únicos e verdadeiros — e a otimização de campanha responde com custo por resultado menor e atribuição que sobrevive ao fim dos cookies de terceiros.