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:

Emitir — o provedor obtém um token de clique assinado (um por clique) quando roteia um visitante em direção à landing page do anunciante.
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
```
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:
js
```
BotSignal.init({ appKey: 'YOUR_APP_KEY', tokenParam: 'click_token' });
```
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:

bash

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:
bash
```
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.

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

Fraude em anúncios ​

Bloqueio em tempo real na origem ​

Os dois papéis ​

Fluxo de ponta a ponta ​

Tokens de clique ​

Opção tokenParam ​

Conciliação e liquidação ​

Próximos passos ​