---
title: Prevenção de Fraude — Fraude em anúncios
---

# Fraude em anúncios

Este é um **guia de cenário**. A integração principal não muda — você carrega o
[Web SDK](../web-sdk), lê um [veredito](../verdict-reference) e obtém dados da
[Data API](../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](../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**.

```mermaid
sequenceDiagram
    autonumber
    participant P as Provedor (conta B)
    participant V as Visitante
    participant A as Página do anunciante + SDK
    participant F as API de Prevenção de Fraude

    P->>P: Assina click_token (bot_kid + secret, carrega pkid)
    P->>V: Entrega o link com ?_ctk=click_token
    V->>A: Clica → chega à página do anunciante (URL carrega _ctk)
    A->>A: SDK lê _ctk da URL
    A->>F: POST criptografado /bot/verify<br/>(app_key = anunciante, click_token = assinado pelo provedor)
    F->>F: app_key → advertiser_app_id,<br/>verifica pkid → provider_app_id, chega a um veredito,<br/>grava uma linha carregando ambos os app_ids
    F-->>A: verdict → onVerdict
    A->>A: Trata conforme verdict.action (registrar / bloquear / desafiar)

    Note over P,F: Conciliação (entre contas)
    A->>F: GET /v1/bot com App-Key do anunciante
    F-->>A: Mesma linha (correspondida em advertiser_app_id)
    P->>F: GET /v1/bot com App-Key do provedor
    F-->>P: Mesma linha (correspondida em provider_app_id)
```

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](../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' });
   ```

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:

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

## 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](../web-sdk) — colete vereditos na landing page
- [Referência de Veredito](../verdict-reference) — cada campo e como agir sobre ele
- [Data API](../data-api) — obtenha e concilie vereditos no lado do servidor