---
title: Fraud Prevention — Web SDK
---

# Fraud Prevention Web SDK

The Fraud Prevention Web SDK runs on **your page** — a landing page, a signup or
login screen, or any protected resource. It requests a verdict for the current
visit and hands it back to your code, so you can decide what to do with the
traffic — record it, flag it, or ask the visitor for one extra verification.

## Quick start

```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()` returns a `Promise<BotVerdict>` as well, so you can also `await`
it instead of using `onVerdict` — both receive the same verdict object.

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

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `appKey` | string | — | Your Fraud Prevention application key (required). |
| `domain` | string | service default | Verdict service endpoint. Leave unset unless you were given a dedicated domain. |
| `escalate` | boolean | `false` | Allow Fraud Prevention to ask the visitor for **one extra verification** when a visit looks high-risk. See [Escalation](#escalation). |
| `collectWindowMs` | number | `1200` | How long (ms) the SDK observes the visit before requesting a verdict. Longer windows yield a more confident verdict at the cost of a small delay. |
| `onVerdict` | `(v) => void` | — | Called once with the final verdict. The primary integration point. |
| `onError` | `(err) => void` | — | Called if anything goes wrong. The SDK never throws into your page. |
| `onEscalate` | `(displayType) => void` | — | Called when an extra verification is shown (only when `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Called after the extra verification finishes; `passed` is `true` if the visitor cleared it. |

::: tip Traffic-source scenarios
If a third party delivers visitors to you and both sides need to reconcile on a
per-click conclusion, the SDK can also read a click token from the page URL. That is
specific to paid-traffic flows — see the [Ad fraud](./scenarios/ad-fraud) guide.
:::

## Using the verdict

`onVerdict` receives a `BotVerdict` object. The two fields you will use most:

- **`verdict.is_bot`** — `true` when the visit is judged to be automated/invalid.
- **`verdict.action`** — what we recommend you do: `record_only`, `challenge`, or
  `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;
    }
  },
});
```

See the full field list and recommended handling in the
[Verdict Reference](./verdict-reference).

## Escalation

When a visit looks high-risk, Fraud Prevention can ask the visitor to complete **one
additional verification** before you treat them as a real user. This is opt-in.

Enable it with `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
  },
});
```

Notes:

- Escalation only triggers when the verdict's `action` is `challenge`. For all
  other visits nothing is shown and the visitor experience is untouched.
- If the visitor clears the extra verification, the verdict delivered to
  `onVerdict` reflects that (treated as human).
- Escalation **fails open**: if the extra verification can't be loaded or shown,
  the SDK keeps the original verdict rather than blocking your page.

::: info
Fraud Prevention never decides *for* you. Even on `challenge`/`flag`, your code stays in
control of whether the visit proceeds — the SDK only surfaces the verdict and,
optionally, runs the extra verification.
:::

## Resilience

If the verdict service is unreachable or any error occurs, the SDK returns a
**degraded** verdict (`degraded: true`) instead of failing your page. A degraded
verdict is conservative (`is_bot: false`, `action: record_only`) so it never blocks
real users. Check `verdict.degraded` if you want to treat those visits specially.

## Next steps

- [Verdict Reference](./verdict-reference) — every field and how to act on it
- [Data API](./data-api) — pull and reconcile verdicts server-side