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