---
title: 反詐欺 — 裁決欄位參考
---

# 裁決欄位參考

每一份反詐欺裁決——無論是透過 [Web SDK](./web-sdk) 的 `onVerdict` 回呼送達,
還是從[資料 API](./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` | 列舉 | `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` 會自動處理(見[升級驗證](./web-sdk#escalation));否則套用你自己的攔截。 |

## 可設定的處理動作

對於**高風險**訪問,`action` 回傳什麼是**按應用程式設定**的,在主控台的應用程式詳情裡設定。
裁決是**伺服器端權威**的:只有當訪問達到高風險檔**且**你的應用程式設定了對應動作時,
`action` 才會是 `challenge` 或 `flag`。未達該檔時,裁決始終為 `record_only`。

| 設定 | 高風險時回傳的 `action` | 含義 |
| --- | --- | --- |
| `record_only`(預設) | `record_only` | 僅記錄。裁決被記錄用於報表與對帳;不向訪客提出任何要求。 |
| `challenge` | `challenge` | 觸發驗證碼複驗。Web SDK 會彈出一次驗證碼(樣式由 SDK 的 `challengeConfig` 控制)。 |
| `flag` | `flag` | 標記該次訪問。裁決攜帶 `flag`;由你的整合自行決定如何處理(攔截 / 切分 / 處理)。 |

因為決策在伺服器端完成,你的程式碼可以保持簡單:在 `onVerdict` 裡讀取 `verdict.action`
並據此處理——放行、攔截,或讓 SDK 彈出驗證碼。你無需自己重新推導風險。

### `escalate_result`

在託管驗證碼升級跑過之後出現——即 `action` 為 `challenge` 且 SDK 彈了驗證碼時。沒有升級時為 `null`。同時透過 `onEscalateDone(passed, detail)` 回呼下發。

| 欄位 | 說明 |
|---|---|
| `passed` | 訪客是否通過了驗證碼 |
| `token` | 驗證碼 pass token —— **請在伺服器端校驗它**確認真的通過(不要只信用戶端的 `passed`) |
| `challenge_id` | 驗證碼 challenge id |
| `cid` | 本次升級關聯的點擊 id(若本次帶了 click token) |

## `level` 與 `score`

`level` 只是 `score` 的分檔,為方便而提供:

| `level` | 何時使用 |
| --- | --- |
| `low` | 當作乾淨流量。 |
| `medium` | 臨界——記錄無妨,可考慮從高價值漏斗中剔除。 |
| `high` | 強可疑——標記並剔除。 |
| `critical` | 幾乎確定無效——標記/剔除,並最好觸發升級驗證。 |

::: tip 選擇適合你流水線的欄位
- 簡單是/否攔截 → 用 **`is_bot`** 分支。
- 按建議驅動 → 用 **`action`** 分支。
- 自訂閾值 → 用 **`score`** 分支(或用 **`level`** 分桶)。
:::

## 處理降級裁決

當 `degraded` 為 `true` 時,裁決未被完整計算。兜底值刻意保守
(`is_bot: false`、`action: record_only`),因此真實使用者絕不會被誤攔。
在報表裡請把這類訪問當作**未知**,而不要計入「確認乾淨」的流量。

## 下一步

- [Web SDK](./web-sdk) —— 在你的頁面接收裁決
- [資料 API](./data-api) —— 伺服器端拉取裁決與統計