---
title: 不正対策 — Web SDK
---

# 不正対策 Web SDK

不正対策 Web SDK は **あなたのページ** 上で動作します——ランディングページ、登録やログインの
画面、あるいは保護対象の任意のリソースです。現在のアクセスについて判定を要求し、それを
あなたのコードに返すので、そのトラフィックをどう扱うか——記録する、フラグを立てる、
あるいは訪問者にもう 1 つの追加検証を求める——を判断できます。

## クイックスタート

```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()` は `Promise<BotVerdict>` も返すので、`onVerdict` を使う代わりに `await`
することもできます——どちらも同じ判定オブジェクトを受け取ります。

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

## オプション

| オプション | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `appKey` | string | — | 不正対策アプリケーションキー（必須）。 |
| `domain` | string | サービス既定値 | 判定サービスのエンドポイント。専用ドメインを付与された場合を除き、未設定のままにしてください。 |
| `escalate` | boolean | `false` | アクセスが高リスクに見える場合に、不正対策が訪問者へ **もう 1 つの追加検証** を求めることを許可します。[エスカレーション](#escalation) を参照してください。 |
| `collectWindowMs` | number | `1200` | SDK が判定を要求する前にアクセスを観察する時間（ms）。観察時間を長くするほど、わずかな遅延と引き換えに、より確度の高い判定が得られます。 |
| `onVerdict` | `(v) => void` | — | 最終的な判定とともに 1 度だけ呼ばれます。主要な連携ポイントです。 |
| `onError` | `(err) => void` | — | 何か問題が起きたときに呼ばれます。SDK があなたのページに例外を投げることはありません。 |
| `onEscalate` | `(displayType) => void` | — | 追加検証が表示されたときに呼ばれます（`escalate: true` のときのみ）。 |
| `onEscalateDone` | `(passed) => void` | — | 追加検証が完了した後に呼ばれます。訪問者がクリアした場合 `passed` は `true` です。 |

::: tip トラフィックソースのシナリオ
第三者があなたに訪問者を届け、双方がクリック単位の結論で突き合わせる必要がある場合、SDK は
ページの URL からクリックトークンを読み取ることもできます。これは有料トラフィックのフローに
固有のものです——[広告不正](./scenarios/ad-fraud) ガイドを参照してください。
:::

## 判定の使い方

`onVerdict` は `BotVerdict` オブジェクトを受け取ります。最もよく使う 2 つのフィールドは
次のとおりです。

- **`verdict.is_bot`** — アクセスが自動化／無効と判定された場合に `true` です。
- **`verdict.action`** — 推奨する対処：`record_only`、`challenge`、または `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;
    }
  },
});
```

すべてのフィールド一覧と推奨される処理は、[Verdict リファレンス](./verdict-reference) を
参照してください。

## エスカレーション {#escalation}

アクセスが高リスクに見える場合、不正対策は、訪問者を実在のユーザーとして扱う前に、
**もう 1 つの追加検証** の完了を求めることができます。これはオプトインです。

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

注意点：

- エスカレーションは、判定の `action` が `challenge` のときにのみ発生します。それ以外の
  すべてのアクセスでは何も表示されず、訪問者の体験はそのまま保たれます。
- 訪問者が追加検証をクリアすると、`onVerdict` に渡される判定はそれを反映します
  （人間として扱われます）。
- エスカレーションは **フェイルオープン** です。追加検証を読み込めない・表示できない場合、
  SDK はあなたのページをブロックせず、元の判定を保持します。

::: info
不正対策があなたの **代わりに** 決定を下すことはありません。`challenge` / `flag` の場合でも、
アクセスを進めるかどうかの主導権はあなたのコードにあります——SDK は判定を提示し、必要に応じて
追加検証を実行するだけです。
:::

## 耐障害性

判定サービスに到達できない、または何らかのエラーが発生した場合、SDK はあなたのページを
失敗させる代わりに **degraded**（劣化）判定（`degraded: true`）を返します。degraded 判定は
保守的（`is_bot: false`、`action: record_only`）なので、実在のユーザーをブロックすることは
決してありません。そうしたアクセスを特別に扱いたい場合は `verdict.degraded` を確認してください。

## 次のステップ

- [Verdict リファレンス](./verdict-reference) — すべてのフィールドと、その対処方法
- [Data API](./data-api) — サーバーサイドで判定を取得・突き合わせる