Fraude em anúncios

Este é um guia de cenário. A integração principal não muda — você carrega o Web SDK, lê um veredito e obtém dados da Data API exatamente como descrito naquelas páginas. Esta página acrescenta as poucas especificidades de que só o cenário de fraude em anúncios precisa.

A proteção contra fraude em anúncios filtra bots e tráfego inválido para fora de campanhas pagas, para que anunciantes e plataformas de anúncios paguem por cliques e impressões genuínos — não por volume falso. O que a torna diferente dos outros casos de uso é que um terceiro entrega o visitante e ambos os lados precisam chegar a um acordo sobre uma conclusão humano / bot independente e por clique.

Bloqueio em tempo real na origem

A Fraud Prevention roda inline no ponto de entrada e retorna um veredito em tempo real — não é um relatório a posteriori. Quem for dono da página em que o visitante aterrissa pode agir sobre esse veredito de imediato:

• Os anunciantes rodam o SDK na landing page: o tráfego inválido é detectado — e, opcionalmente, recebe um desafio — no momento em que chega, antes de entrar no funil ou distorcer os relatórios.
• As plataformas de tráfego rodam o SDK em sua própria pre-lander ou página de redirecionamento: um clique é verificado antes de ser encaminhado, de modo que os bots são barrados na entrada e nunca se tornam tráfego entregue.

O único requisito é uma página capaz de rodar o SDK: um veredito precisa de sinais do navegador, então um 302 puramente do lado do servidor não tem onde coletá-los — adicione uma página intermediária leve e o mesmo bloqueio em tempo real se aplica.

O token de clique assinado e a Data API ficam por cima para a conciliação entre os dois lados; o bloqueio inline em tempo real é o mecanismo principal, e a limpeza posterior via API é o recurso de reserva para o tráfego sem página intermediária.

Os dois papéis

• Anunciante (Advertiser) — é dono da landing page em que o visitante chega. Roda o Web SDK nessa página para obter um veredito para cada visita que chega, e obtém vereditos da Data API para conciliar aquilo pelo que foi cobrado.
• Provedor (Provider) (fonte de tráfego / anúncio) — entrega o clique. Ele precisa comprovar a qualidade do que enviou, então emite um token de clique por clique e, depois, cruza seu relatório de entrega com os vereditos independentes.

Ambos os lados se autenticam na Data API com suas próprias credenciais de aplicação e leem o mesmo veredito por clique, que é o que lhes permite conciliar sem confiar nos logs brutos um do outro.

Fluxo de ponta a ponta

A sequência abaixo mostra como um clique percorre o caminho desde a entrega do provedor, passando pelo visitante e pela landing page do anunciante, até um único veredito que ambas as contas leem depois, cada uma do seu lado.

A propriedade decisiva: ambos os app_ids ficam na mesma linha. O anunciante a lê correspondida em advertiser_app_id, o provedor a lê correspondida em provider_app_id — duas contas diferentes, cada uma consultando com sua própria App-Key, cada uma chegando ao mesmo veredito independente. Nenhum dos lados precisa expor ou confiar nos logs brutos do outro para concordar sobre o que aconteceu em um determinado clique.

Tokens de clique

Um token de clique vincula o clique entregue por um provedor ao veredito que a visita acaba recebendo. É o identificador por clique sobre o qual ambas as partes liquidam. Os outros casos de uso da Prevenção de Fraude não precisam de tokens de clique — eles conciliam vereditos sem eles.

O fluxo:

1. Emitir — o provedor obtém um token de clique assinado (um por clique) quando roteia um visitante em direção à landing page do anunciante.

2. Carregá-lo na URL de destino — acrescente o token emitido à URL de destino como um parâmetro de consulta:

   https://advertiser.example/lp?click_token=ct_xxxxxxxx

3. Lê-lo na página — o Web SDK lê o token da URL automaticamente. Se você usar um nome de parâmetro diferente, defina tokenParam:

   BotSignal.init({ appKey: 'YOUR_APP_KEY', tokenParam: 'click_token' });

4. Conciliar — consulte o clique depois pela Data API e cruze-o de volta com o relatório de entrega do provedor.

INFO

O token já está assinado quando é emitido para você — você só precisa carregá-lo até a URL de destino. Não há nada para assinar ou calcular do seu lado.

Opção tokenParam

O Web SDK ganha uma opção extra neste cenário:

Opção	Tipo	Padrão	Descrição
tokenParam	string	detectado automaticamente	Nome do parâmetro de consulta da URL que carrega o token de clique do provedor (por exemplo, click_token). O SDK o lê da URL da página e vincula o veredito a esse clique. Deixe sem definir se você não usar tokens de clique.

Conciliação e liquidação

Uma vez que as visitas carregam um token de clique, ambos os lados liquidam com base nos mesmos vereditos independentes:

• Obter o veredito de um único clique — por exemplo, para contestar ou confirmar um clique:

  GET /v1/bot/verdict?click_token=ct_xxx
  X-App-Key: YOUR_APP_KEY
  X-App-Secret: YOUR_APP_SECRET

• Exportar linhas por clique — obtenha um intervalo de tempo e cruze o click_token de cada linha de volta com seus próprios logs de clique:

  GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
  X-App-Key: YOUR_APP_KEY
  X-App-Secret: YOUR_APP_SECRET

  Cada linha carrega o click_token da visita (quando presente), o timestamp e os campos do veredito (is_bot, score, level, action).

O anunciante exclui cliques sinalizados e de bots daquilo pelo que paga; o provedor concilia seu relatório de entrega com as mesmas conclusões. Como ambos leem o mesmo veredito independente, a liquidação não depende dos logs brutos de nenhum dos lados.

Modelo de segurança

A cid e o token de clique viajam na URL, então trate-os como identificadores — não como credenciais:

• Ler um veredito exige App-Key + App-Secret. A Data API autentica cada chamada com o seu app secret (comparado em tempo constante) e retorna apenas linhas em que o seu app é o advertiser ou o provider. Uma cid sozinha não busca nada — um terceiro que a copia da URL não tem secret e não é parte da linha.
• O provider fica vinculado pela assinatura. O token de clique é assinado com HMAC usando o secret do provider e carrega o pkid do provider; não pode ser forjado, e uma cid só pode ser reivindicada uma vez (protegida contra repetição).
• Opcionalmente, vincule também o advertiser. Assine o app_key do advertiser de destino no token como aud. A verificação passa então a exigir que o app_key da página coincida com aud, de modo que um token emitido para o advertiser A não possa atribuir um veredito ao advertiser B. Omita aud e qualquer página de advertiser poderá aceitar o token.

Efeito líquido: o veredito de uma cid só é legível pelos dois apps vinculados a ela — o advertiser cuja página rodou o SDK e o provider cujo token foi apresentado — cada um autenticando-se com o seu próprio App-Secret.

Próximos passos

• Web SDK — colete vereditos na landing page
• Referência de Veredito — cada campo e como agir sobre ele
• Data API — obtenha e concilie vereditos no lado do servidor