裁決欄位參考
每一份反詐欺裁決——無論是透過 Web SDK 的 onVerdict 回呼送達, 還是從資料 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 | 列舉 | score 的粗分檔:low、medium、high、critical。當你想用分桶而非原始數值時很方便。 |
action | 列舉 | 我們對該次訪問的建議處理:record_only、challenge 或 flag。見下文。 |
consistency | 物件 | 一個跨訊號一致性結論。讀取 consistency.ok(布林值):true = 該次訪問的各訊號如預期般吻合;false = 有訊號對不上,值得額外審視。該結論背後的內部拆分不對外暴露。 |
degraded | boolean | 當裁決無法完整計算(服務無法連線、出錯等)而回傳了保守兜底值時為 true。請把降級裁決當作「未知」而非「乾淨」。 |
action —— 該怎麼做
action 是我們的建議;最終決定權仍在你手裡。
action | 含義 | 該怎麼做 |
|---|---|---|
record_only | 訪問看起來正常。 | 照常放行。僅記錄裁決用於報表與對帳。 |
flag | 可疑但未確鑿。 | 繼續展示頁面,但把該次訪問標為低品質——從你的指標中剔除,從下游流程裡切出,並在你自己的決策中納入權重(例如轉換歸因或你對該次訪問的信任度)。 |
challenge | 高風險。 | 在把訪客當作真人之前要求其額外做一次驗證。配合 Web SDK 的 escalate: true 會自動處理(見升級驗證);否則套用你自己的攔截。 |
可設定的處理動作
對於高風險訪問,action 回傳什麼是按應用程式設定的,在主控台的應用程式詳情裡設定。 裁決是伺服器端權威的:只有當訪問達到高風險檔且你的應用程式設定了對應動作時, action 才會是 challenge 或 flag。未達該檔時,裁決始終為 record_only。
| 設定 | 高風險時回傳的 action | 含義 |
|---|---|---|
record_only(預設) | record_only | 僅記錄。裁決被記錄用於報表與對帳;不向訪客提出任何要求。 |
challenge | challenge | 觸發驗證碼複驗。Web SDK 會彈出一次驗證碼(樣式由 SDK 的 challengeConfig 控制)。 |
flag | flag | 標記該次訪問。裁決攜帶 flag;由你的整合自行決定如何處理(攔截 / 切分 / 處理)。 |
因為決策在伺服器端完成,你的程式碼可以保持簡單:在 onVerdict 裡讀取 verdict.action 並據此處理——放行、攔截,或讓 SDK 彈出驗證碼。你無需自己重新推導風險。
level 與 score
level 只是 score 的分檔,為方便而提供:
level | 何時使用 |
|---|---|
low | 當作乾淨流量。 |
medium | 臨界——記錄無妨,可考慮從高價值漏斗中剔除。 |
high | 強可疑——標記並剔除。 |
critical | 幾乎確定無效——標記/剔除,並最好觸發升級驗證。 |
選擇適合你流水線的欄位
- 簡單是/否攔截 → 用
is_bot分支。 - 按建議驅動 → 用
action分支。 - 自訂閾值 → 用
score分支(或用level分桶)。
處理降級裁決
當 degraded 為 true 時,裁決未被完整計算。兜底值刻意保守 (is_bot: false、action: record_only),因此真實使用者絕不會被誤攔。 在報表裡請把這類訪問當作未知,而不要計入「確認乾淨」的流量。