Verdict リファレンス
すべての不正対策の判定は——Web SDK の onVerdict コールバックに渡されるものでも、 Data API から取得するものでも——同じ BotVerdict オブジェクトです。このページでは、 各フィールドと、その対処方法を説明します。
{
"is_bot": false,
"score": 18,
"level": "low",
"action": "record_only",
"reasons": [],
"consistency": { "ok": true },
"degraded": false,
"verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
"verdict_token": "vt1.eyJ2Ijoi...",
"verdict_token_exp": 1767225600
}フィールド
| フィールド | 型 | 説明 |
|---|---|---|
is_bot | boolean | 見出しとなる判定。true = アクセスが自動化または無効トラフィックと判定されたこと、false = 実在の人間に見えることを表します。ほとんどの連携が分岐に使う、唯一最も重要なフィールドです。 |
score | number (0–100) | アクセスがどの程度疑わしいか。高いほど疑わしい ことを意味します。これを使って独自のしきい値を設定できます——例えば、自分で選んだ基準値を超えるアクセスを除外する、など。正確な値は当方のリスクモデルによって生成されるもので、リバースエンジニアリングを意図したものではありません。 |
level | enum | score の大まかな帯：low、medium、high、critical。生の数値ではなくバケット単位で扱いたいときに便利です。 |
action | enum | そのアクセスに対する当方の 推奨処理：record_only、challenge、flag、または deny。以下を参照してください。新しい値が追加されても連携が動作し続けるよう、未知の値は flag として扱ってください。 |
reasons | string[] | リスクのある判定を説明する、最大 3 つの大まかな理由カテゴリ。クリーンなアクセスでは空です。 |
consistency | object | クロスシグナルの整合性に関する結論。consistency.ok（boolean）を読みます。true = アクセスのシグナルが想定どおり一致していること、false = 何かが噛み合わず、追加の精査に値することを表します。この結論の背後にある内部内訳は公開されません。 |
degraded | boolean | 判定を完全に算出できず（サービス到達不可、エラーなど）、保守的なフォールバックが返された場合に true です。degraded 判定は「クリーン」ではなく「不明」として扱ってください。 |
verdict_id | string | この判定の一意な ID。後で Data API で判定を照会するのに使います。 |
verdict_token | string | この判定の署名付き証明で、あなたの サーバー が検証するためのものです。サーバーサイド検証を参照してください。フォールバック判定には含まれません。 |
verdict_token_exp | number | verdict_token が失効する Unix 時刻（秒）。 |
action — どうするか
action は当方の推奨です。最終的な決定の主導権はあなたにあります。
action | 意味 | どうするか |
|---|---|---|
record_only | アクセスは正常に見えます。 | 通常どおり進めます。レポーティングと突き合わせのために判定をログに残すだけです。 |
flag | アクセスは疑わしいが、決定的に悪いとまでは言えません。 | ページの提供は続けつつ、そのアクセスを低品質として印を付けます——指標から除外する、下流フローからセグメント分離する、独自の判断（例：コンバージョンのアトリビューションや、そのアクセスをどの程度信頼するか）の中で重み付けする、といった対応をします。 |
challenge | アクセスがチャレンジのしきい値に達しました（デフォルトでは高リスク）。 | 訪問者を人間として扱う前に、もう 1 つの追加検証を求めます。アプリの処理アクションが challenge に設定されている場合は、Web SDK がこれを自動で実行します（エスカレーション を参照）。そうでなければ、独自のゲートを適用します。 |
deny | アクセスがブロックルール（例：ブロックリストのエントリや、ブロックするよう設定したポリシー）に一致しました。 | 保護されたコンテンツを提供しないでください。チャレンジは提示されません。古い SDK バージョンはこの値をそのまま渡すため、onVerdict で処理してください。 |
処理アクションの設定
高リスク のアクセスに対して action が何を報告するかは、アプリごとの設定 であり、 ダッシュボードのアプリケーション詳細で設定します。判定は サーバー権威 です。action が challenge または flag になるのは、アクセスが高リスク帯に達し、かつ あなたのアプリが 該当するアクションで設定されている場合のみです。その帯より下では、判定は record_only の ままです。
| 設定 | 高リスク時に返る action | 意味 |
|---|---|---|
record_only（デフォルト） | record_only | 記録のみ。判定はレポーティングと突き合わせのためにログされ、訪問者には何も求めません。 |
challenge | challenge | 再検証 CAPTCHA をトリガーします。Web SDK がチャレンジをポップアップします（スタイルは SDK の challengeConfig で制御されます）。 |
flag | flag | アクセスに印を付けます。判定は flag を帯び、それにどう対処するか（ブロック / セグメント分離 / 処理）はあなたの連携が決めます。 |
決定はサーバーサイドで行われるため、あなたのコードはシンプルなままで済みます。onVerdict で verdict.action を読み、それに対処するだけです——進める、ブロックする、あるいは SDK に チャレンジを提示させる。リスクを自分で再導出する必要はありません。
チャレンジのしきい値と種類
処理アクションが challenge の場合、ダッシュボードの同じ場所にさらに 2 つの設定が表示されます。
- チャレンジのしきい値 — 設定したアクションを返すリスクレベル。デフォルトは高リスク以上です。厳格モードでは中リスクの訪問にも適用されます。スクレイパーや AI エージェントをより多く止められますが、チャレンジが表示される実ユーザーも増えます。
- チャレンジの種類 — エスカレーション時に表示する最低限の CAPTCHA 種類：スライダー（デフォルト）、回転、クリック、3D クリック。強い種類ほど自動化・AI ツールが解きにくくなります。
escalate_result
マネージド captcha のエスカレーションが実行された後に存在します——つまり action が challenge で、SDK が captcha を実行したときです。エスカレーションが実行されなかった場合は null。onEscalateDone(passed, detail) にも渡されます。
| フィールド | 説明 |
|---|---|
passed | 訪問者が captcha を通過したかどうか |
token | captcha の pass token —— 通過を確認するため サーバー側で検証してください(クライアントの passed だけを信用しないでください) |
challenge_id | captcha の challenge id |
cid | このエスカレーションに紐づく click id(click token があった場合) |
reasons — 理由カテゴリ
reasons は、アクセスがリスクありと見なされた理由を大まかに示します。最大 3 つの カテゴリを、強いものから順に含みます。個々のシグナルやスコアの内訳は含みません。
| カテゴリ | 意味 |
|---|---|
automation | スクリプト化されたブラウザやヘッドレスブラウザなど、自動化ツールの兆候。 |
network | プロキシ、データセンター、匿名化ネットワーク、ブロック済みアドレスなど、ネットワークがリスクありまたは不整合に見える。 |
abnormal_requests | リクエストが多すぎる、失敗の繰り返し、自動化トラフィックの履歴など、通常と異なるリクエストパターン。 |
device | デバイスまたはその環境を信頼できない、または認識できない。 |
behavior | 操作がまったくない、再利用されたリンクなど、アクセスが人間らしい振る舞いをしていない。 |
other | 独自ルールやフォールバック判定を含む、その他の理由。 |
このリストはレポーティング用の説明として扱い、ルール構築用のシグナルとしては使わないで ください。代わりに is_bot、action、score で分岐します。今後カテゴリが追加される 可能性があります。
サーバーサイド検証
ページが受け取るものはすべて訪問者が改ざんできます。コンテンツをゲートする場合（実在の人間 だけがページ、API レスポンス、ダウンロードを見られるようにする場合）、ブラウザ内の is_bot フラグを信用しないでください。verdict_token を自社サーバーに送り、そこで検証します。
onVerdictでverdict.verdict_tokenをバックエンドに送ります（例：ヘッダーや Cookie で）。- バックエンドがトークンと訪問者の IP アドレスを付けて
POST /v1/bot/verdict/verifyを呼び出します。 - レスポンスが
valid: trueで、判定が許容できる場合（例：verdict.is_botがfalse）にのみコンテンツを提供します。
トークンはあなたのアプリ、この判定、訪問者のネットワークに紐づき、短時間（デフォルト 10 分）で 失効します。デフォルトではトークンは何度でも検証できるため、1 つのトークンで 1 回の訪問中の 複数ページビューをカバーできます。フォーム送信など、トークンを 1 回だけ使わせたい場合は consume: true を渡してください。
訪問者がその後エスカレーションのチャレンジを通過しても、トークンは元の判定を示したままです。 escalate_result の captcha pass token も、captcha のサーバーサイド API で検証してください。
level と score
level は score を帯に分けただけのもので、利便性のために提供されています。
level | こういうときに使う |
|---|---|
low | クリーンなトラフィックとして扱います。 |
medium | 境界線上——記録は問題なし、高価値ファネルからの除外を検討します。 |
high | 強く疑わしい——フラグを立てて除外します。 |
critical | ほぼ確実に無効——フラグ／除外し、可能ならエスカレーションします。 |
パイプラインに合うフィールドを選ぶ
- シンプルな yes/no ゲート →
is_botで分岐。 - 推奨ベース →
actionで分岐。 - 独自のしきい値 →
score（またはバケットならlevel）で分岐。
degraded 判定の扱い
degraded が true のとき、判定は完全には算出されていません。フォールバックは意図的に 保守的（is_bot: false、action: record_only）なので、実在のユーザーがブロックされることは 決してありません。レポーティングでは、これらを確定クリーンなトラフィックとして数えるのではなく、 不明 として扱ってください。