裁决字段参考
每一份反欺诈裁决——无论是通过 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),因此真实用户绝不会被误拦。 在报表里请把这类访问当作未知,而不要计入"确认干净"的流量。