Verdict リファレンス
すべての不正対策の判定は——Web SDK の onVerdict コールバックに渡されるものでも、 Data API から取得するものでも——同じ BotVerdict オブジェクトです。このページでは、 各フィールドと、その対処方法を説明します。
json
{
"is_bot": false,
"score": 18,
"level": "low",
"action": "record_only",
"consistency": { "ok": true },
"degraded": false
}フィールド
| フィールド | 型 | 説明 |
|---|---|---|
is_bot | boolean | 見出しとなる判定。true = アクセスが自動化または無効トラフィックと判定されたこと、false = 実在の人間に見えることを表します。ほとんどの連携が分岐に使う、唯一最も重要なフィールドです。 |
score | number (0–100) | アクセスがどの程度疑わしいか。高いほど疑わしい ことを意味します。これを使って独自のしきい値を設定できます——例えば、自分で選んだ基準値を超えるアクセスを除外する、など。正確な値は当方のリスクモデルによって生成されるもので、リバースエンジニアリングを意図したものではありません。 |
level | enum | score の大まかな帯：low、medium、high、critical。生の数値ではなくバケット単位で扱いたいときに便利です。 |
action | enum | そのアクセスに対する当方の 推奨処理：record_only、challenge、または flag。以下を参照してください。 |
consistency | object | クロスシグナルの整合性に関する結論。consistency.ok（boolean）を読みます。true = アクセスのシグナルが想定どおり一致していること、false = 何かが噛み合わず、追加の精査に値することを表します。この結論の背後にある内部内訳は公開されません。 |
degraded | boolean | 判定を完全に算出できず（サービス到達不可、エラーなど）、保守的なフォールバックが返された場合に true です。degraded 判定は「クリーン」ではなく「不明」として扱ってください。 |
action — どうするか
action は当方の推奨です。最終的な決定の主導権はあなたにあります。
action | 意味 | どうするか |
|---|---|---|
record_only | アクセスは正常に見えます。 | 通常どおり進めます。レポーティングと突き合わせのために判定をログに残すだけです。 |
flag | アクセスは疑わしいが、決定的に悪いとまでは言えません。 | ページの提供は続けつつ、そのアクセスを低品質として印を付けます——指標から除外する、下流フローからセグメント分離する、独自の判断（例：コンバージョンのアトリビューションや、そのアクセスをどの程度信頼するか）の中で重み付けする、といった対応をします。 |
challenge | アクセスは高リスクです。 | 訪問者を人間として扱う前に、もう 1 つの追加検証を求めます。Web SDK の escalate: true を使えばこれが自動で処理されます（エスカレーション を参照）。そうでなければ、独自のゲートを適用します。 |
処理アクションの設定
高リスク のアクセスに対して 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 に チャレンジを提示させる。リスクを自分で再導出する必要はありません。
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）なので、実在のユーザーがブロックされることは 決してありません。レポーティングでは、これらを確定クリーンなトラフィックとして数えるのではなく、 不明 として扱ってください。