---
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));否则应用你自己的拦截。 |

## `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) —— 拉取裁决与统计用于结算