Instalando a API de eventos do TikTok

Há um problema que ninguém lhe informa quando você começa a anunciar no TikTok: O pixel fornece apenas metade dos dados. A outra metade é silenciada por bloqueadores de anúncios, navegadores privados e restrições do iOS. E se você não vê essa metade, está otimizando suas campanhas com informações incompletas. Antes de terminar este artigo, você entenderá exatamente o que é a API de eventos do TikTok, por que precisa dela e como configurá-la passo a passo. E se em algum momento você decidir que prefere que outra pessoa faça isso desde o início, explicarei como fazemos isso no final deste artigo. Analytic Pixel Pro.

O que é a API de eventos do TikTok e por que ela existe?

O pixel do TikTok é um código que é instalado em seu site e envia informações para o TikTok a partir do navegador do usuário. Quando alguém visita seu site ou compra um produto, o pixel registra e envia as informações para o TikTok.

O problema é que a jornada do navegador até o TikTok pode ser interrompida:

• Os bloqueadores de anúncios o bloqueiam.
• O Safari e o Firefox limitam os cookies de terceiros.
• Alguns usuários têm configurações de privacidade que impedem o rastreamento.
• As restrições do iOS 14+ reduzem a janela de atribuição.

O resultado é que o TikTok pode perder entre 20% e 40% de conversões reais, dependendo do seu público. E, com dados incompletos, o algoritmo é mal otimizado, suas campanhas têm desempenho inferior e você gasta mais para obter menos.

A API de eventos do TikTok (também chamada de API de eventos ou CAPI do TikTok) é a solução. Em vez de enviar os dados do navegador do usuário, você os envia de seu servidor diretamente para o servidor do TikTok. A viagem é muito mais curta, segura e não pode ser bloqueada por nenhuma extensão de navegador.

Quando você precisa da API de eventos do TikTok

Se você investe no TikTok Ads e se preocupa com a atribuição, precisa dela o tempo todo. Mas há situações em que ela se torna especialmente crítica:

• Você tem uma loja de comércio eletrônico e você deseja que o TikTok veja todas as suas compras, não apenas aquelas não bloqueadas pelo navegador.
• Você gerencia campanhas de desempenho e você precisa que o algoritmo tenha os dados corretos para fazer uma boa otimização.
• Seu público é tecnológico e provavelmente usam bloqueadores de anúncios ou o Safari com ITP ativado.
• Você investe no aumento de escala e você precisa de dados confiáveis para saber quais campanhas realmente funcionam.

Resumindo: se o pixel for sua única fonte de dados, você estará voando às cegas.

Os dois componentes de que você precisa antes de instalar qualquer coisa

Antes de mexer em qualquer configuração, você precisa saber claramente quais são as partes envolvidas.

O pixel do TikTok (lado do cliente)

O pixel ainda é necessário, mesmo que você use a API. Ele funciona no navegador e captura dados como o ttclid (o identificador de clique do TikTok) e o cookie _ttp, que são usados para identificar o usuário dentro da plataforma. Sem esses dados, a deduplicação não funciona corretamente.

A API de eventos (no lado do servidor)

A API envia os mesmos eventos que o pixel, mas a partir do seu servidor. Ela precisa de um Token de acesso para se autenticar no TikTok e em seu ID do pixel para saber a qual pixel associar os eventos.

O segredo é que os dois sistemas devem funcionar juntos, não separadamente. O TikTok usa o ID do evento para deduplicação: se você receber o mesmo evento do navegador e do servidor com o mesmo ID, ele será contado apenas uma vez. Se você não configurar a deduplicação corretamente, os dados serão inflados.

Como instalar a API de eventos do TikTok, passo a passo

Há várias maneiras de implementar a API. Vou explicar a mais profissional e escalável: usar o Google Tag Manager Server-Side (sGTM). Essa é a forma que recomendo para qualquer empresa que já tenha um grande volume de campanhas.

Etapa 1: Gerar o token de acesso no TikTok Ads Manager

1. Entrar Gerente de anúncios do TikTok.
2. Ir para Ativos → Eventos → Eventos na Web.
3. Selecione seu pixel.
4. Clique em Configurações e procure a seção Geração de token de acesso.
5. Clique em Gerar token de acesso e copie-o. Você precisará dele mais tarde.

Esse token é como a chave que dá permissão ao seu servidor para se comunicar com o TikTok. Mantenha-o em um local seguro.

Etapa 2: Copie seu Pixel ID

Na mesma tela de configuração de pixels, você verá a opção ID do pixel. Copie-o também. Esse é o identificador que informa ao TikTok a qual pixel pertencem os eventos que você envia.

Etapa 3: Configure o contêiner do lado do servidor do GTM

Para que a API funcione, você precisa de um contêiner de servidor no Google Tag Manager. Há várias maneiras de configurar isso:

• Google Cloud Run (opção nativa do Google).
• Stape o TAGGRS (soluções gerenciadas que simplificam a infraestrutura).

Se você já tiver um contêiner de servidor em execução para o GA4 ou o Meta CAPI, o processo será adicionado à mesma infraestrutura.

Etapa 4: Adicione a tag da API de eventos do TikTok no servidor GTM

1. Faça login no contêiner do servidor GTM.
2. Ir para Tags → New → Tag Configuration.
3. Pesquisar no Galeria de modelos da comunidade o rótulo API de eventos do TikTok (oficial).
4. Adicione seu Token de acesso e sua ID do pixel nos campos apropriados.
5. Se você for testar, adicione o Código do evento de teste (você pode encontrá-lo no Gerenciador de eventos do TikTok, na guia Eventos de teste). Lembre-se de excluí-lo antes de publicar na produção.

Etapa 5: Mapear os parâmetros do evento

Essa é a parte mais importante e onde a maioria dos erros é cometida. Você precisa se certificar de que os eventos enviados ao servidor contenham as informações corretas:

• Nome do evento: Compra, Adicionar ao carrinho, Exibir conteúdo, CompleteRegistration, etc.
• ID do evento: Um identificador exclusivo por evento. Isso é o que o TikTok usa para deduplicação. Deve ser o mesmo que o enviado pelo pixel do navegador.
• Dados do usuário: e-mail, telefone, IP do usuário, agente do usuário. O TikTok faz o hash deles automaticamente em SHA-256.
• Parâmetros do produto: valor, moeda, content_id, content_type.
• ttclid e _ttp: Identificador de cliques e cookie do TikTok. Eles são essenciais para a atribuição.

Etapa 6: Configurar o acionador

O acionador define quando a tag do TikTok é disparada. Geralmente, ela é configurada para disparar em eventos do GA4 que já vêm do seu contêiner da Web. Por exemplo, quando o GA4 registra um compra, O mesmo evento chega ao servidor e, a partir daí, você o encaminha para o TikTok.

Etapa 7: Configurar a deduplicação

Para que o TikTok não conte o mesmo evento duas vezes (uma vez a partir do pixel e outra a partir da API), você deve passar o mesmo evento para o TikTok. ID do evento em ambos os lados:

• No pixel da web: gera uma ID exclusiva (por exemplo, purchase_12345_timestamp) e passar o tempo no campo event_id do pixel.
• No servidor: Use o mesmo ID na tag da API de eventos do TikTok.

Se você não fizer isso, o TikTok poderá duplicar suas conversões e seus dados ficarão incorretos.

Etapa 8: Teste antes de publicar

1. Use o Modo de visualização GTM para verificar se a etiqueta foi acionada corretamente.
2. Ir para Gerenciador de eventos do TikTok → Testar eventos e verifique se os eventos do servidor estão listados na seção Eventos do servidor de teste.
3. Verifique se o Qualidade de correspondência de eventos (EMQ) é alta. Essa métrica mede a capacidade do TikTok de associar seus eventos a usuários reais. Quanto mais alta, melhor a atribuição.

Etapa 9: Publicar

Depois de verificar que tudo funciona, publique o contêiner do servidor. A partir desse momento, você começará a recuperar as conversões que o pixel perdeu.

Erros mais comuns ao instalar a API do TikTok

Já vi essas implementações muitas vezes e sempre aparecem os mesmos erros:

Não configure a deduplicação. Se você enviar o mesmo evento do navegador e do servidor sem um ID de evento para vinculá-los, o TikTok os contabilizará como duas conversões diferentes. Seus dados são inflados e o algoritmo otimiza com base em mentiras.

Esqueça o ttclid e o _ttp. Esses valores são o que permitem que o TikTok atribua a conversão ao clique correto no anúncio. Se você não os enviar, perderá a atribuição.

Falha ao fazer o hash dos dados do usuário corretamente. O TikTok espera que o e-mail e o telefone venham em letras minúsculas SHA-256. Se você os enviar em texto simples ou em letras maiúsculas, a correspondência falhará.

Publicar com o código de evento de teste ativo. Se você se esquecer de excluí-lo antes de publicar, os dados reais serão marcados como testes e poderão não ser processados corretamente.

Use o contêiner do servidor para tudo, sem o pixel da Web. A API e o pixel são complementares. Você precisa de ambos para que a deduplicação funcione e para capturar o ttclid.

Quantos dados são aprimorados com a API de eventos

O impacto real depende do seu público e do seu setor, mas, em geral, você pode esperar isso:

• Recuperação de entre 15% e 40% de eventos que o pixel perdeu.
• Melhoria do Event Match Quality Score, o que significa melhor atribuição.
• Algoritmo do TikTok mais eficiente, pois tem mais dados reais para otimizar.
• Públicos personalizados maiores, porque são criados com mais sinais.

Esses dados se traduzem diretamente em um ROAS mais alto quando você aumenta o investimento. Não porque você gastou mais, mas porque o algoritmo toma decisões melhores.

Privacidade e conformidade com o GDPR

A API de eventos do TikTok não o isenta da conformidade com o GDPR. Na verdade, ao lidar com dados de usuários no servidor, é preciso garantir:

• Envie apenas dados de usuários que tenham dado seu consentimento.. O servidor deve saber se você aceitou cookies de marketing antes de enviar seus dados para o TikTok.
• Anonimizar ou não enviar determinados dados se o usuário não tiver dado consentimento explícito.
• Documentar o fluxo de dados como parte do seu registro de atividades de processamento.

Um sistema de gerenciamento de consentimento (CMP) bem configurado deve controlar quais dados são enviados ao servidor e sob quais condições.

Por que faz sentido ser configurado pelo Analytic Pixel Pro

Instalando a API de eventos do TikTok Não é complicado se você já tiver experiência com o GTM no lado do servidor, mas há muitos detalhes em que uma configuração incorreta pode custar dados ou gerar duplicações que distorcem toda a sua análise.

Em Analytic Pixel Pro Implementamos a API do TikTok integrada em um ecossistema de rastreamento que inclui:

• GTM web e servidor conectados corretamente.
• Deduplicação configurada para que nenhum evento seja contado duas vezes.
• Integração com consentimento para que o rastreamento esteja em conformidade com o GDPR.
• Verificação da qualidade da partida do evento antes que a implementação seja considerada bem-sucedida.
• Testes em um ambiente de teste antes de entrar em produção.

Se você já tiver o Meta CAPI ou o GA4 em execução em um servidor, adicionar a API de eventos do TikTok à mesma infraestrutura é muito mais eficiente do que configurá-la separadamente.

O objetivo é que, ao aumentar seu investimento no TikTok, você o faça sabendo que cada euro investido está sendo medido corretamente. Você pode Entre em contato conosco aqui para analisar sua configuração atual e ver quais dados estão sendo perdidos.

Perguntas frequentes sobre a API de eventos do TikTok

Preciso da API se já tiver o pixel instalado? Sim, o pixel só funciona no navegador e está sujeito a bloqueios. A API recupera os eventos que o pixel perde. Eles são complementares, não alternativos.

Posso instalar a API sem o servidor do Google Tag Manager? Sim, o TikTok oferece integração direta via API e também há soluções como a Stape que simplificam a infraestrutura. Mas para as empresas que já usam o GTM para outras plataformas, o contêiner de servidor é a opção mais limpa e dimensionável.

Quanto tempo leva para ver o impacto? Depois que a implementação é publicada, o TikTok começa a receber eventos do servidor imediatamente. Pode levar de 24 a 72 horas para que o algoritmo processe o novo volume e ajuste a otimização da campanha.

A API funciona para aplicativos móveis? O TikTok tem uma API de eventos para aplicativos (versão 2.0) que funciona de maneira semelhante. Neste artigo, concentrei-me na implementação na Web, que é a mais comum para comércio eletrônico e empresas com presença na Web.

O que é o Event Match Quality Score? Essa é uma pontuação que o TikTok atribui a cada evento para indicar quão bem você pode relacioná-lo a um usuário real do TikTok. Quanto mais alta for essa pontuação (escala de 1 a 10), melhor será a atribuição obtida. Ela é aprimorada com o envio de mais sinais de usuário: e-mail, telefone, IP, ttclid e _ttp.