Fraud Prevention Web SDK

The Fraud Prevention Web SDK runs on your landing page. 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

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

<script>
  BotSignal.init({
    appKey: 'YOUR_AD_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.

const verdict = await BotSignal.init({ appKey: 'YOUR_AD_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.
tokenParam	string	auto-detected	Name of the URL query parameter that carries the provider click token (e.g. click_token). The SDK reads it from the landing URL and ties the verdict to that click.
escalate	boolean	false	Allow Fraud Prevention to ask the visitor for one extra verification when a visit looks high-risk. See 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.

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.

BotSignal.init({
  appKey: 'YOUR_AD_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.

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:

BotSignal.init({
  appKey: 'YOUR_AD_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 — every field and how to act on it
• Data API — pull and reconcile verdicts server-side