TikTok Events API para Shopify: configuração e eliminação de duplicados

A Events API do TikTok é a ligação de servidor para servidor do TikTok para dados de conversão. Em vez de depender apenas do pixel do TikTok no navegador do comprador, a sua loja, ou uma ferramenta como a ROASaurus, envia eventos como compras diretamente para o TikTok. O TikTok recomenda executar a Events API a par do pixel e eliminar os duplicados entre os dois com um event_id partilhado.

Este guia aborda o que a Events API envia a partir de uma loja Shopify, os nomes de evento Purchase e CompletePayment, o ID de clique e o cookie em que o TikTok se baseia para associar, como funciona a eliminação de duplicados, como testar no TikTok Events Manager e como configurar tudo na ROASaurus.

O que é a Events API do TikTok?

O pixel do TikTok é um script na sua loja. Dispara eventos a partir do navegador do comprador, por isso só conta o que acontece enquanto o script carrega e corre. Um bloqueador de anúncios, um erro de script ou um comprador que feche o separador antes de a confirmação da encomenda carregar podem impedi-lo.

A Events API envia o mesmo tipo de evento a partir de um servidor. No Shopify, o registo mais fiável de uma compra é a própria encomenda. O Shopify comunica cada encomenda paga por webhook, tenha o script do navegador corrido ou não. É essa a ideia por trás do tracking server-side no Shopify.

Os dois não são alternativas. O conselho do TikTok é partilhar eventos pelos dois, mantê-los coerentes ao longo do percurso de compra e deixar o TikTok remover os duplicados.

Que eventos envia a ROASaurus para o TikTok?

Quatro momentos numa loja Shopify contam para a otimização do TikTok: uma visualização de produto, uma adição ao carrinho, o início do checkout e a compra. A ROASaurus envia os quatro para a Events API e dispara os mesmos quatro através do pixel do TikTok, com os mesmos IDs de evento. As visualizações de página passam apenas pelo pixel.

Nas definições do pixel, pode desmarcar os eventos do servidor que não quer enviar e adicionar filtros, como um país ou um valor mínimo de encomenda.

Purchase ou CompletePayment?

O TikTok mudou o nome do seu evento de compra. O nome atual é Purchase. O nome antigo, CompletePayment, continua a funcionar: o TikTok converte os nomes antigos do seu lado, mostra-os com o novo nome nos relatórios, nos públicos e na otimização, e diz que o CompletePayment será suportado indefinidamente. O TikTok pede que as novas configurações de pixel usem Purchase.

A ROASaurus envia CompletePayment, no pixel e na Events API. No TikTok Events Manager e no Ads Manager, esses eventos aparecem como Purchase. Para a eliminação de duplicados, o que conta é que as duas cópias de uma compra usem o mesmo nome de evento, e usam.

Como é que o TikTok associa um evento a um comprador?

Um evento só ajuda as suas campanhas se o TikTok o conseguir ligar à pessoa que viu ou clicou no anúncio. O TikTok chama a estes identificadores match keys, e o seu guia da Events API pede que devolva todas as match keys 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 da frequência com que cada match key está presente.

O TikTok refere que o pixel partilha o endereço IP e o user agent por predefinição, mas a Events API precisa que sejam acrescentados à mão. A ROASaurus obtém-nos da sessão de checkout do comprador ou, se não houve sessão, da encomenda. Outras duas chaves exigem atenção no Shopify.

ttclid: o ID de clique do TikTok

Quando um comprador clica num anúncio do TikTok, o TikTok acrescenta o ttclid ao URL da página de entrada. Se a sua loja não o guardar nessa primeira página, perde-se quando a encomenda chega, várias páginas depois. A ROASaurus lê o ttclid na página de entrada, guarda-o com o ID de visitante, escreve-o no carrinho do Shopify e acrescenta-o ao evento do servidor quando a encomenda chega.

_ttp: o cookie do pixel

O cookie _ttp é um cookie first-party que o pixel do TikTok usa no seu domínio. A ROASaurus lê-o na loja e no checkout e envia-o como ttp no evento do servidor. É mais uma razão para manter o pixel a correr a par da 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 eliminação de duplicados?

Quando o pixel e a Events API comunicam a mesma compra, o TikTok recebe dois eventos para uma encomenda. Para ficar com apenas um, o TikTok precisa que dois valores sejam idênticos nas duas cópias: o nome do evento e o event_id. O TikTok regista então a primeira cópia que recebe para medição e relatórios, de modo que a encomenda conta uma vez. Isto funciona para cópias correspondentes que cheguem numa janela de 48 horas a partir da primeira.

A ROASaurus constrói o ID de evento de uma compra a partir do ID da encomenda do Shopify. A compra da encomenda 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 partilham-no.

Veja o que isto significa para os números. Imagine uma loja de exemplo com 200 encomendas numa semana. O pixel dispara em 150 delas. 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 as 200.

O 350 é o número com que se preocupar. Faria a contagem de compras do TikTok, e o ROAS baseado nela, ficar 75% acima da realidade, porque 350 ÷ 200 = 1.75. O TikTok também usa estes eventos para otimização e segmentação, por isso a sua licitação aprenderia com 150 compras que não aconteceram.

Porque é que as compras são contadas duas vezes no Shopify?

A contagem duplicada acontece quando o TikTok recebe duas cópias de uma compra que não consegue associar. Verifique estas causas antes de confiar num salto nas compras do TikTok:

• Duas ferramentas enviam o mesmo pixel. A app do canal de vendas do TikTok no Shopify também pode enviar eventos para o seu pixel. Os IDs de evento dessa app não coincidem com os que a ROASaurus usa, por isso o TikTok conta cada encomenda duas vezes. Desligue o pixel nessa app.
• O pixel também está no código do tema. Um snippet de pixel colado no tema dispara os seus próprios eventos sem os seus IDs de evento. Remova-o e deixe uma só 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 dos eventos diferem. O TikTok só elimina duplicados entre eventos idênticos. As duas cópias de uma compra têm de usar o mesmo nome de evento.

O artigo de ajuda sobre a contagem em duplicado percorre as mesmas verificações para a Meta e para as outras plataformas.

Como se testa a Events API no TikTok Events Manager?

O TikTok Events Manager tem um separador Test events para eventos do navegador e do servidor. Use-o antes de confiar nos dados:

1. Copie um código de evento de teste

   No TikTok Events Manager, abra o seu pixel e vá a Test events. Copie o código do evento de teste.

2. Cole-o na ROASaurus

   Abra Tracking & platforms, edite o pixel do TikTok e cole o código no campo Test event code. Os eventos do servidor passam a trazê-lo.

3. Faça uma encomenda de teste

   Visite a sua loja, veja um produto, adicione-o ao carrinho e conclua uma encomenda.

4. Verifique os dois lados

   Em Test events, filtre por eventos do navegador e do servidor. Deve ver a compra nos dois. Na ROASaurus, o Event log mostra cada envio do servidor como enviado ou falhado.

5. Remova o código de teste

   Apague o código do evento de teste quando terminar, para que os seus eventos do servidor em produção deixem de ser enviados como eventos de teste.

O TikTok pode responder a um pedido com HTTP 200 e mesmo assim rejeitar o evento, com um código de erro no corpo da resposta. A ROASaurus lê esse código, por isso um evento rejeitado aparece como falhado 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. Lista cada evento com o seu método de ligação, a pontuação de Event Match Quality e quando foi recebido pela última vez. Os detalhes do evento incluem informação de correspondência e de eliminação de duplicados, e o Diagnostics lista problemas de qualidade com orientações para os corrigir.

Como configurar a Events API do TikTok no Shopify com a ROASaurus

Precisa de uma loja Shopify com a app ROASaurus e de acesso ao TikTok Events Manager. A página da integração com o TikTok lista todos os campos que a ROASaurus envia.

1. Ligue a sua loja Shopify

   Vá a Add a store › Shopify, clique em Install app e ative o app embed da ROASaurus no editor de temas. O embed capta o ttclid e o cookie _ttp em todas as páginas. O guia de configuração do Shopify mostra cada passo.

2. Adicione o pixel de checkout

   No Shopify admin › Settings › Customer events, adicione um pixel personalizado com o nome ROASaurus e cole o snippet da sua página Tracking & platforms. Dispara o pixel do TikTok no checkout, incluindo a cópia da compra no navegador.

3. Crie um token de acesso

   No TikTok Events Manager, abra o seu pixel e gere um token de acesso da Events API nas suas definições. Copie o token e o código do pixel.

4. Adicione o pixel do TikTok na ROASaurus

   Vá a Tracking & platforms, clique em Add pixel no cartão do TikTok e preencha Pixel code e Events API access token. Mantenha Also load the browser pixel (recommended, deduplicated) assinalado, para que os eventos do navegador e do servidor partilhem IDs.

5. Adicione o investimento (opcional)

   Preencha Advertiser ID for spend e um Marketing API token. A ROASaurus passa então a importar o investimento do TikTok, para que as campanhas do TikTok mostrem ROAS e CPA a par dos outros canais.

6. Teste e depois entre em produção

   Envie uma encomenda 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 é a predefinição, a ROASaurus segue a escolha do comprador no banner de cookies do Shopify. Quando um comprador recusa os cookies de marketing, a ROASaurus não carrega o pixel do TikTok para ele, não define nenhum ID de visitante, pelo que os seus cliques não ficam associados a ele, e não envia os seus eventos de navegação ao TikTok. A sua encomenda paga continua a ser enviada para a Events API a partir do servidor, com os dados da encomenda com hash e o endereço IP e o user agent da encomenda, mas sem ttclid nem _ttp. O guia de consentimento e privacidade explica o que é guardado e enviado.

Com o investimento sincronizado, as campanhas do TikTok aparecem nos relatórios de atribuição a par da Meta, e a análise de criativos acrescenta as estatísticas de vídeo do TikTok por anúncio. A ROASaurus atribui as encomendas aos cliques em anúncios e aos UTMs que registou, e só conta conversões view-through como estimativa modelada no seu modelo Clicks & views, por isso os seus totais costumam diferir do TikTok Ads Manager. Para as outras plataformas server-side, veja o guia da Conversions API do Pinterest e o guia da Conversions API da Meta.

Fontes

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

Na ROASaurus

• Integração com o TikTok
• Tracking server-side na ROASaurus
• Ajuda: evitar a contagem em duplicado
• Ajuda: configurar a ROASaurus no Shopify

Continue a ler