---
title: Prevenção de Fraude — Web SDK
---

# Web SDK da Prevenção de Fraude

O Web SDK da Prevenção de Fraude roda na **sua página** — uma landing page, uma tela de
cadastro ou login, ou qualquer recurso protegido. Ele solicita um veredito para a visita
atual e o devolve ao seu código, para que você possa decidir o que fazer com o tráfego —
registrá-lo, sinalizá-lo ou pedir ao visitante uma verificação extra.

## Início rápido

```html
<!-- Load the Fraud Prevention SDK -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot, verdict.score, verdict.action — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>
```

`BotSignal.init()` também retorna uma `Promise<BotVerdict>`, então você também pode usar
`await` em vez de `onVerdict` — ambos recebem o mesmo objeto de veredito.

```js
const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });
```

## Opções

| Opção | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `appKey` | string | — | Sua chave de aplicação da Prevenção de Fraude (obrigatório). |
| `domain` | string | padrão do serviço | Endpoint do serviço de veredito. Deixe sem definir, a menos que você tenha recebido um domínio dedicado. |
| `escalate` | boolean | `false` | Permite que a Prevenção de Fraude peça ao visitante **uma verificação extra** quando uma visita parece de alto risco. Veja [Escalonamento](#escalation). |
| `collectWindowMs` | number | `1200` | Por quanto tempo (ms) o SDK observa a visita antes de solicitar um veredito. Janelas mais longas produzem um veredito mais confiante ao custo de um pequeno atraso. |
| `onVerdict` | `(v) => void` | — | Chamado uma vez com o veredito final. O principal ponto de integração. |
| `onError` | `(err) => void` | — | Chamado se algo der errado. O SDK nunca lança exceções para a sua página. |
| `onEscalate` | `(displayType) => void` | — | Chamado quando uma verificação extra é exibida (somente quando `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Chamado após a verificação extra terminar; `passed` é `true` se o visitante a concluiu. |

::: tip Cenários de fonte de tráfego
Se um terceiro entrega visitantes a você e ambos os lados precisam conciliar com base
em uma conclusão por clique, o SDK também pode ler um token de clique da URL da página.
Isso é específico de fluxos de tráfego pago — veja o guia de [Fraude em anúncios](./scenarios/ad-fraud).
:::

## Usando o veredito

`onVerdict` recebe um objeto `BotVerdict`. Os dois campos que você mais usará:

- **`verdict.is_bot`** — `true` quando a visita é julgada como automatizada/inválida.
- **`verdict.action`** — o que recomendamos que você faça: `record_only`, `challenge` ou
  `flag`.

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});
```

Veja a lista completa de campos e o tratamento recomendado na
[Referência de Veredito](./verdict-reference).

## Escalonamento {#escalation}

Quando uma visita parece de alto risco, a Prevenção de Fraude pode pedir ao visitante
que conclua **uma verificação adicional** antes de você tratá-lo como um usuário real.
Isso é opcional (opt-in).

Ative com `escalate: true`:

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to false
  },
});
```

Observações:

- O escalonamento só é acionado quando o `action` do veredito é `challenge`. Para todas
  as outras visitas nada é exibido e a experiência do visitante permanece intacta.
- Se o visitante concluir a verificação extra, o veredito entregue a `onVerdict` reflete
  isso (tratado como humano).
- O escalonamento **falha em modo aberto** (fail open): se a verificação extra não puder
  ser carregada ou exibida, o SDK mantém o veredito original em vez de bloquear sua
  página.

::: info
A Prevenção de Fraude nunca decide *por* você. Mesmo em `challenge`/`flag`, seu código
continua no controle de saber se a visita prossegue — o SDK apenas expõe o veredito e,
opcionalmente, executa a verificação extra.
:::

## Resiliência

Se o serviço de veredito estiver inacessível ou ocorrer qualquer erro, o SDK retorna um
veredito **degradado** (`degraded: true`) em vez de falhar sua página. Um veredito
degradado é conservador (`is_bot: false`, `action: record_only`), de modo que nunca
bloqueia usuários reais. Verifique `verdict.degraded` se você quiser tratar essas visitas
de forma especial.

## Próximos passos

- [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