不正対策 Web SDK

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

クイックスタート

<!-- 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 することもできます——どちらも同じ判定オブジェクトを受け取ります。

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

オプション

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

トラフィックソースのシナリオ

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

判定の使い方

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

• verdict.is_bot — アクセスが自動化／無効と判定された場合に true です。
• verdict.action — 推奨する対処：record_only、challenge、または flag。

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 リファレンス を 参照してください。

エスカレーション

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

escalate: true で有効化します。

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 リファレンス — すべてのフィールドと、その対処方法
• Data API — サーバーサイドで判定を取得・突き合わせる