裁決欄位參考
每一份反詐欺裁決——無論是透過 Web SDK 的 onVerdict 回呼送達, 還是從資料 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 | 列舉 | score 的粗分檔:low、medium、high、critical。當你想用分桶而非原始數值時很方便。 |
action | 列舉 | 我們對該次訪問的建議處理:record_only、challenge、flag 或 deny。見下文。遇到不認識的值請按 flag 處理,這樣以後新增取值時你的整合也不會出錯。 |
reasons | string[] | 最多三個原因大類,說明裁決為何有風險。乾淨訪問為空陣列。 |
consistency | 物件 | 一個跨訊號一致性結論。讀取 consistency.ok(布林值):true = 該次訪問的各訊號如預期般吻合;false = 有訊號對不上,值得額外審視。該結論背後的內部拆分不對外暴露。 |
degraded | boolean | 當裁決無法完整計算(服務無法連線、出錯等)而回傳了保守兜底值時為 true。請把降級裁決當作「未知」而非「乾淨」。 |
verdict_id | string | 本次裁決的唯一 ID。之後可用它透過資料 API 查詢這條裁決。 |
verdict_token | string | 本次裁決的簽章憑證,供你的伺服器端校驗。見伺服器端校驗。兜底裁決不帶此欄位。 |
verdict_token_exp | number | verdict_token 的過期時間(Unix 秒)。 |
action —— 該怎麼做
action 是我們的建議;最終決定權仍在你手裡。
action | 含義 | 該怎麼做 |
|---|---|---|
record_only | 訪問看起來正常。 | 照常放行。僅記錄裁決用於報表與對帳。 |
flag | 可疑但未確鑿。 | 繼續展示頁面,但把該次訪問標為低品質——從你的指標中剔除,從下游流程裡切出,並在你自己的決策中納入權重(例如轉換歸因或你對該次訪問的信任度)。 |
challenge | 訪問達到你設定的升級門檻(預設為高風險)。 | 在把訪客當作真人之前要求其額外做一次驗證。應用程式的處理動作設為 challenge 時,Web SDK 會自動彈出驗證(見升級驗證);否則套用你自己的攔截。 |
deny | 命中了攔截規則,例如黑名單,或你設定為攔截的策略。 | 不要提供受保護的內容,也不會彈驗證碼。舊版 SDK 會原樣透傳這個值,請在 onVerdict 裡處理。 |
可設定的處理動作
對於高風險訪問,action 回傳什麼是按應用程式設定的,在主控台的應用程式詳情裡設定。 裁決是伺服器端權威的:只有當訪問達到高風險檔且你的應用程式設定了對應動作時, action 才會是 challenge 或 flag。未達該檔時,裁決始終為 record_only。
| 設定 | 高風險時回傳的 action | 含義 |
|---|---|---|
record_only(預設) | record_only | 僅記錄。裁決被記錄用於報表與對帳;不向訪客提出任何要求。 |
challenge | challenge | 觸發驗證碼複驗。Web SDK 會彈出一次驗證碼(樣式由 SDK 的 challengeConfig 控制)。 |
flag | flag | 標記該次訪問。裁決攜帶 flag;由你的整合自行決定如何處理(攔截 / 切分 / 處理)。 |
因為決策在伺服器端完成,你的程式碼可以保持簡單:在 onVerdict 裡讀取 verdict.action 並據此處理——放行、攔截,或讓 SDK 彈出驗證碼。你無需自己重新推導風險。
升級驗證門檻與題型
處理動作設為 challenge 時，控制台同一位置還會出現兩項設定：
- 升級驗證門檻：達到哪個風險等級就返回所設定的動作。預設為高風險及以上。嚴格模式下中風險訪問也會觸發：能攔下更多爬蟲和 AI 工具，但會有更多真實訪客看到驗證碼。
- 升級驗證題型：升級時至少使用的驗證碼題型，可選滑塊（預設）、旋轉、點選、3D 點選。題型越強，自動化和 AI 工具越難通過。
escalate_result
在託管驗證碼升級跑過之後出現——即 action 為 challenge 且 SDK 彈了驗證碼時。沒有升級時為 null。同時透過 onEscalateDone(passed, detail) 回呼下發。
| 欄位 | 說明 |
|---|---|
passed | 訪客是否通過了驗證碼 |
token | 驗證碼 pass token —— 請在伺服器端校驗它確認真的通過(不要只信用戶端的 passed) |
challenge_id | 驗證碼 challenge id |
cid | 本次升級關聯的點擊 id(若本次帶了 click token) |
reasons —— 原因大類
reasons 用大類說明一次訪問為什麼被判為有風險。最多三個,按強弱排序。不會包含具體訊號或分數構成。
| 大類 | 含義 |
|---|---|
automation | 有自動化工具的跡象,例如腳本驅動或無頭瀏覽器。 |
network | 網路有風險或前後不一致,例如代理、機房或匿名網路,或命中了被封鎖的位址。 |
abnormal_requests | 請求模式異常,例如請求過於頻繁、多次失敗,或有自動化流量的歷史紀錄。 |
device | 裝置或其執行環境不可信,或無法識別。 |
behavior | 訪問行為不像真人,例如完全沒有互動,或連結被重複使用。 |
other | 其他原因,包括你自己設定的規則和兜底裁決。 |
這個列表用於報表和解釋,不建議在它上面寫規則;分支判斷請用 is_bot、action 或 score。以後可能新增大類。
伺服器端校驗
頁面拿到的任何資料都可能被訪客竄改。如果你要做內容牆(只讓真人看到某個頁面、介面回應或下載),不要信任瀏覽器裡的 is_bot,而是把 verdict_token 交給你自己的伺服器端校驗:
- 在
onVerdict裡把verdict.verdict_token傳給你的後端,例如放在請求標頭或 Cookie 裡。 - 後端帶上 token 和訪客 IP 呼叫
POST /v1/bot/verdict/verify。 - 只有回應為
valid: true、且裁決符合你的要求(例如verdict.is_bot為false)時才回傳內容。
token 綁定你的應用程式、本次裁決和訪客所在網路,有效期較短(預設 10 分鐘)。預設可以重複校驗,一個 token 可以涵蓋一次訪問中的多次頁面請求。需要只用一次的場景(例如送出表單)請傳 consume: true。
如果訪客隨後通過了升級驗證碼,token 裡仍是原始裁決。請同時在伺服器端校驗 escalate_result 裡的驗證碼通過憑證。
level 與 score
level 只是 score 的分檔,為方便而提供:
level | 何時使用 |
|---|---|
low | 當作乾淨流量。 |
medium | 臨界——記錄無妨,可考慮從高價值漏斗中剔除。 |
high | 強可疑——標記並剔除。 |
critical | 幾乎確定無效——標記/剔除,並最好觸發升級驗證。 |
選擇適合你流水線的欄位
- 簡單是/否攔截 → 用
is_bot分支。 - 按建議驅動 → 用
action分支。 - 自訂閾值 → 用
score分支(或用level分桶)。
處理降級裁決
當 degraded 為 true 時,裁決未被完整計算。兜底值刻意保守 (is_bot: false、action: record_only),因此真實使用者絕不會被誤攔。 在報表裡請把這類訪問當作未知,而不要計入「確認乾淨」的流量。