不正対策 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' });

オプション

option	type	default	説明
appKey	string	—	必須。不正対策アプリケーションキー。
domain	string	signal-v1.world-dynamic.com	SDK が送信する Signal ドメイン。
tokenParam	string	_ctk	SDK がクリックトークンを読み取る URL クエリパラメータ。
onVerdict	(v) => void	—	最終的な判定とともに 1 度だけ呼ばれます。主要な連携ポイントです。init() は Promise<BotVerdict> も返します。
onError	(err) => void	—	何らかの失敗時に呼ばれます。SDK があなたのページに例外を投げることはありません。
onChallenge	(v) => creds | null | Promise<…>	—	エスカレーションの資格情報を上書きします。独自の { appKey, serverToken }（serverToken は あなたのバックエンド が発行）を返すか、エスカレーションをスキップする場合は null を返します。未設定の場合は、verdict.escalate 内のバックエンド発行のデフォルト資格情報が使われます（ゼロコンフィグ）。
challengeConfig	object	—	キャプチャの外観／配置：product（popup/float/embed）、container、theme、lang。
onEscalate	(displayType) => void	—	エスカレーションのキャプチャが表示されたときに呼ばれます。
onEscalateDone	(passed, detail) => void	—	エスカレーションの後に呼ばれます。passed = 訪問者がクリアしたかどうか。detail = パスの サーバーサイド検証 に使う { token, challengeId, cid }。

エスカレーションはサーバー主導です。 SDK は、サーバーの判定 action が challenge で かつ アプリに対応するエスカレーションアクションが設定されている場合にのみキャプチャを表示します——クライアント側にそれを切り替えるトグルはありません。独自の資格情報を渡したりエスカレーションをスキップしたりするには onChallenge を、外観を制御するには challengeConfig を使ってください。訪問者がパスした後は、detail.token（および challenge_id/cid）を使ってあなた自身のバックエンドで結果を検証してください——クライアント側の passed フラグだけを信用しないでください。

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

第三者があなたに訪問者を届け、双方がクリック単位の結論で突き合わせる必要がある場合、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 つの追加検証 の完了を求めることができます。これはクライアント側のフラグではなく、 サーバーの判定によって駆動されます——判定の action が challenge で、かつアプリに エスカレーションアクションが設定されているときに実行されます。

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // 追加の検証が訪問者に表示されています
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // 訪問者が追加チェックをクリアしました — detail.token をバックエンドで検証してください
    } else {
      // クリアされなかった — 元の判定の推奨を維持してください
    }
  },
  onVerdict: function (verdict) {
    // 訪問者がエスカレーションをクリアした場合、verdict.is_bot は false に更新されます
  },
});

注意点：

• エスカレーションは、判定の action が challenge のときにのみトリガーされます。それ以外の すべてのアクセスでは何も表示されず、訪問者の体験はそのまま保たれます。
• デフォルトでは、SDK は verdict.escalate 内のバックエンド発行の資格情報を使います（ゼロコンフィグ）。 独自の { appKey, serverToken } を渡したりエスカレーションをスキップしたりするには onChallenge を、 外観を制御するには challengeConfig を使ってください。
• パスの後は、detail.token（および challenge_id/cid）をあなた自身のバックエンドで 検証してください——クライアント側の passed フラグだけを信用しないでください。
• 訪問者が追加検証をクリアすると、onVerdict に渡される判定はそれを反映します （人間として扱われます）。
• エスカレーションは フェイルオープン です。追加検証を読み込めない・表示できない場合、 SDK はあなたのページをブロックせず、元の判定を保持します。

INFO

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

耐障害性

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

次のステップ

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