- A TikTok Events API envia eventos de conversão de um servidor para o TikTok, de modo que uma compra não depende de o pixel do TikTok rodar no navegador do comprador.
- O TikTok renomeou CompletePayment para Purchase, mas ainda aceita o nome antigo; para a deduplicação, o pixel e o servidor precisam usar o mesmo nome.
- O TikTok deduplica um evento do pixel e um evento do servidor quando os dois têm o mesmo nome de evento e o mesmo event_id, e registra a primeira cópia que recebe.
- O ID de clique ttclid, o cookie _ttp, o e-mail e o telefone com hash, o endereço IP e o user agent são as chaves que o TikTok usa para associar um evento a uma pessoa.
- Teste primeiro com um código de evento de teste e desconecte o pixel em qualquer outro app que o envie, ou o TikTok conta as compras duas vezes.
A TikTok Events API é a conexão servidor a servidor do TikTok para dados de conversão. Em vez de depender só do pixel do TikTok no navegador do comprador, a sua loja, ou uma ferramenta como o ROASaurus, envia eventos como compras diretamente ao TikTok. O TikTok recomenda rodar a Events API junto com o pixel e deduplicar os dois com um event_id compartilhado.
Este guia cobre o que a Events API envia de uma loja no Shopify, os nomes de evento Purchase e CompletePayment, o ID de clique e o cookie que o TikTok usa para associar eventos, como a deduplicação funciona, como testar no TikTok Events Manager e como configurar tudo no ROASaurus.
O que é a TikTok Events API?
O pixel do TikTok é um script na sua loja. Ele dispara eventos a partir do navegador do comprador, então só conta o que acontece enquanto o script carrega e roda. Um bloqueador de anúncios, um erro de script ou um comprador que fecha a aba antes de a confirmação do pedido carregar podem impedir tudo isso.
A Events API envia o mesmo tipo de evento a partir de um servidor. No Shopify, o registro mais confiável de uma compra é o próprio pedido. O Shopify informa todo pedido pago por webhook, quer o script do navegador tenha rodado ou não. Essa é a ideia por trás do rastreamento server-side no Shopify.
Os dois não são alternativas. O conselho do TikTok é compartilhar eventos pelos dois, mantê-los consistentes ao longo da jornada de compra e deixar o TikTok remover as duplicatas.
- Roda no navegador do comprador
- Pode ser bloqueada por bloqueadores de anúncios e erros de script
- Compartilha o endereço IP e o user agent por padrão
- Dispara visualizações de página e eventos de navegação à medida que acontecem
- Roda em um servidor, a partir dos dados do seu pedido
- Não depende de um script carregando no navegador
- Quem envia precisa adicionar o endereço IP e o user agent
- Envia todo pedido pago, mesmo quando o pixel não disparou
Quais eventos o ROASaurus envia ao TikTok?
Quatro momentos em uma loja no Shopify importam para a otimização do TikTok: a visualização de um produto, a adição ao carrinho, o início do checkout e a compra. O ROASaurus envia os quatro à Events API e dispara os mesmos quatro pelo pixel do TikTok, com os mesmos IDs de evento. As visualizações de página passam só pelo pixel.
| Ação do comprador | Evento do TikTok | Pixel (navegador) | Events API (servidor) |
|---|---|---|---|
| Vê uma página | Visualização de página | Sim | Não |
| Vê um produto | ViewContent | Sim | Sim |
| Adiciona ao carrinho | AddToCart | Sim | Sim |
| Inicia o checkout | InitiateCheckout | Sim, com o pixel de checkout | Sim |
| Conclui um pedido | CompletePayment | Sim, com o pixel de checkout | Sim, a partir do pedido |
Nas configurações do pixel, você pode desmarcar os eventos de servidor que não quer enviar e adicionar filtros, como um país ou um valor mínimo de pedido.
Purchase ou CompletePayment?
O TikTok renomeou o seu evento de compra. O nome atual é Purchase. O nome antigo, CompletePayment, ainda funciona: o TikTok converte os nomes legados do lado dele, os mostra com o novo nome nos relatórios, nos públicos e na otimização, e diz que o CompletePayment será aceito por tempo indefinido. O TikTok pede que as novas configurações de pixel usem Purchase.
O ROASaurus envia CompletePayment, no pixel e na Events API. No TikTok Events Manager e no Ads Manager, esses eventos aparecem como Purchase. Para a deduplicação, o que importa é que as duas cópias de uma compra usem o mesmo nome de evento, e usam.
Como o TikTok associa um evento a um comprador?
Um evento só ajuda as suas campanhas se o TikTok conseguir ligá-lo à pessoa que viu ou clicou no anúncio. O TikTok chama esses identificadores de chaves de correspondência (match keys), e o guia da Events API dele pede que você devolva todas as chaves de correspondência relevantes para aumentar as taxas de correspondência. O Events Manager mostra o resultado como uma pontuação de Event Match Quality, uma média ponderada de com que frequência cada chave de correspondência está presente.
| Chave de correspondência | De onde vem | Enviado como |
|---|---|---|
| ttclid | Um ID de clique que o TikTok adiciona à URL da página de entrada quando alguém clica em um anúncio | Valor simples |
| Cookie _ttp | Um cookie first-party do pixel do TikTok no domínio da sua loja | Valor simples |
| O pedido do Shopify | Hash SHA-256 | |
| Telefone | O pedido do Shopify | Hash SHA-256 |
| external_id | O ID de cliente do Shopify ou o ID de visitante do ROASaurus | Hash SHA-256 |
| Endereço IP e user agent | A sessão de checkout do comprador ou o pedido | Valor simples |
O TikTok observa que o pixel compartilha o endereço IP e o user agent por padrão, mas a Events API precisa que eles sejam adicionados à mão. O ROASaurus os obtém da sessão de checkout do comprador ou, se não houve sessão, do pedido. Outras duas chaves exigem atenção no Shopify.
ttclid: o ID de clique do TikTok
Quando um comprador clica em um anúncio do TikTok, o TikTok adiciona ttclid à URL da página de entrada. Se a sua loja não o salva nessa primeira página, ele se perde quando o pedido chega, várias páginas depois. O ROASaurus lê o ttclid na página de entrada, armazena-o com o ID de visitante, grava-o no carrinho do Shopify e o adiciona ao evento de servidor quando o pedido chega.
_ttp: o cookie do pixel
O cookie _ttp é um cookie first-party que o pixel do TikTok usa no seu domínio. O ROASaurus o lê na loja e no checkout e o envia como ttp no evento de servidor. É mais um motivo para manter o pixel rodando junto com a Events API.
{
"event_source": "web",
"event_source_id": "CXXXXXXXXXXXXXXXXXXX",
"data": [{
"event": "CompletePayment",
"event_time": 1793016000,
"event_id": "order-5512345678901",
"user": {
"email": "a3f1…9c2e",
"phone": "7b40…11d8",
"external_id": "e05c…4a7f",
"ttclid": "E.C.P.v3…",
"ttp": "2Xb7…",
"ip": "203.0.113.24",
"user_agent": "Mozilla/5.0 (iPhone; …)"
},
"page": { "url": "https://example-store.com/checkouts/…/thank-you" },
"properties": {
"currency": "USD",
"value": 84,
"content_type": "product",
"contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
"order_id": "5512345678901"
}
}]
}Como funciona a deduplicação?
Quando o pixel e a Events API informam a mesma compra, o TikTok recebe dois eventos para um pedido. Para manter só um, o TikTok precisa que dois valores sejam idênticos nas duas cópias: o nome do evento e o event_id. O TikTok então registra a primeira cópia que recebe para medição e relatórios, de modo que o pedido conta uma vez. Isso funciona para cópias correspondentes que chegam dentro de uma janela de 48 horas a partir da primeira.
O ROASaurus monta o ID de evento de uma compra a partir do ID do pedido do Shopify. A compra do pedido 5512345678901 tem o ID de evento order-5512345678901, no pixel de checkout e no servidor. Os eventos da loja, como visualizações de produto e adições ao carrinho, recebem um ID aleatório quando acontecem, e a cópia do navegador e a do servidor o compartilham.
Veja o que isso significa para os números. Pegue uma loja de exemplo com 200 pedidos em uma semana. O pixel dispara em 150 deles. Os outros 50 compradores usaram um bloqueador de anúncios, recusaram os cookies de marketing ou saíram antes de a página de confirmação carregar. A Events API envia os 200.
O 350 é o número que deve preocupar. Ele faria a contagem de compras do TikTok, e o ROAS baseado nela, ficarem 75% acima da realidade, porque 350 ÷ 200 = 1.75. O TikTok também usa esses eventos para otimização e segmentação, então os lances dele aprenderiam com 150 compras que não aconteceram.
Por que as compras são contadas duas vezes no Shopify?
A contagem em duplicidade acontece quando o TikTok recebe duas cópias de uma compra que não consegue associar. Confira estas causas antes de confiar em um salto nas compras do TikTok:
- Duas ferramentas enviam o mesmo pixel. O app do canal de vendas do TikTok no Shopify também pode enviar eventos para o seu pixel. Os IDs de evento dele não coincidem com os IDs que o ROASaurus usa, então o TikTok conta cada pedido duas vezes. Desconecte o pixel nesse app.
- O pixel também está no código do tema. Um snippet de pixel colado no tema dispara os próprios eventos sem os seus IDs de evento. Remova-o e deixe uma única ferramenta carregar o pixel.
- Um dos lados não tem event_id. Uma compra do servidor sem event_id, ou com um novo ID aleatório, não pode ser associada à cópia do pixel.
- Os nomes de evento são diferentes. O TikTok só deduplica eventos idênticos. As duas cópias de uma compra precisam usar o mesmo nome de evento.
O artigo de ajuda sobre contagem em duplicidade percorre as mesmas verificações para o Meta e as outras plataformas.
Como testar a Events API no TikTok Events Manager?
O TikTok Events Manager tem uma aba Test events para eventos do navegador e do servidor. Use-a antes de confiar nos dados:
- Copie um código de evento de teste
No TikTok Events Manager, abra o seu pixel e vá em Test events. Copie o código do evento de teste.
- Cole-o no ROASaurus
Abra Tracking & platforms, edite o pixel do TikTok e cole o código no campo Test event code. Os eventos de servidor passam a carregá-lo.
- Faça um pedido de teste
Visite a sua loja, veja um produto, adicione-o ao carrinho e conclua um pedido.
- Confira os dois lados
Em Test events, filtre por eventos do navegador e do servidor. Você deve ver a compra dos dois. No ROASaurus, o Event log mostra cada envio do servidor como enviado ou com falha.
- Remova o código de teste
Apague o código do evento de teste quando terminar, para que os seus eventos de servidor reais deixem de ser enviados como eventos de teste.
O TikTok pode responder a uma requisição com HTTP 200 e mesmo assim rejeitar o evento, com um código de erro no corpo da resposta. O ROASaurus lê esse código, então um evento rejeitado aparece como com falha no Event log em vez de passar em silêncio.
Depois de um dia de tráfego real, abra a visão geral do pixel no Events Manager. Ela lista cada evento com o método de conexão, a pontuação de Event Match Quality e quando foi recebido pela última vez. Os detalhes do evento incluem informações de correspondência e deduplicação, e o Diagnostics lista problemas de qualidade com orientações de como corrigi-los.
Como configurar a TikTok Events API no Shopify com o ROASaurus
Você precisa de uma loja no Shopify com o app do ROASaurus e de acesso ao TikTok Events Manager. A página de integração com o TikTok lista todos os campos que o ROASaurus envia.
- Conecte a sua loja do Shopify
Vá em Add a store › Shopify, clique em Install app e ative o app embed do ROASaurus no editor de temas. O embed captura o ttclid e o cookie _ttp em todas as páginas. O guia de configuração do Shopify mostra cada etapa.
- Adicione o pixel de checkout
No Shopify admin › Settings › Customer events, adicione um pixel personalizado chamado ROASaurus e cole o snippet da sua página Tracking & platforms. Ele dispara o pixel do TikTok no checkout, inclusive a cópia da compra no navegador.
- Crie um token de acesso
No TikTok Events Manager, abra o seu pixel e gere um token de acesso da Events API nas configurações dele. Copie o token e o código do pixel.
- Adicione o pixel do TikTok no ROASaurus
Vá em Tracking & platforms, clique em Add pixel no card do TikTok e preencha Pixel code e Events API access token. Mantenha Also load the browser pixel (recommended, deduplicated) marcado, para que os eventos do navegador e do servidor compartilhem IDs.
- Adicione o investimento (opcional)
Preencha Advertiser ID for spend e um Marketing API token. O ROASaurus passa então a importar o investimento do TikTok, e as campanhas do TikTok mostram ROAS e CPA ao lado dos seus outros canais.
- Teste e depois entre no ar
Envie um pedido de teste com um código de evento de teste, como descrito acima, e depois remova o código.
Com Respect visitor consent ativado, que é o padrão, o ROASaurus segue a escolha do comprador no banner de cookies do Shopify. Quando um comprador recusa os cookies de marketing, o ROASaurus não carrega o pixel do TikTok para ele, não define um ID de visitante, então os cliques dele não são vinculados a ele, e não envia os eventos de navegação dele ao TikTok. O pedido pago dele ainda é enviado à Events API pelo servidor, com os dados do pedido em hash e com o endereço IP e o user agent do pedido, mas sem ttclid nem _ttp. O guia de consentimento e privacidade explica o que é armazenado e enviado.
Com o investimento sincronizado, as campanhas do TikTok aparecem nos relatórios de atribuição ao lado do Meta, e a análise de criativos acrescenta as estatísticas de vídeo do TikTok por anúncio. O ROASaurus credita os pedidos aos cliques em anúncios e às UTMs que registrou e conta conversões view-through apenas como uma estimativa modelada no modelo Clicks & views, então os totais dele costumam diferir do TikTok Ads Manager. Para as outras plataformas server-side, veja o guia da Pinterest Conversions API e o guia da Conversions API do Meta.
Fontes
- TikTok For Business: About Events API
- TikTok Ads Manager: About Event Deduplication
- TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
- TikTok Ads Manager: How to set up matching events with Events API
- TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager
No ROASaurus
- Integração com o TikTok
- Rastreamento server-side no ROASaurus
- Ajuda: evitar a contagem em duplicidade
- Ajuda: configurar o ROASaurus no Shopify