---
title: 反欺诈 — Web SDK
---

# 反欺诈 Web SDK

反欺诈 Web SDK 运行在**你的页面**上——落地页、注册或登录页,或任何需要保护的资源。
它为当前访问请求一份裁决,并交回给你的代码,让你决定如何处理这次流量——记录、标记,
或要求访客额外做一次验证。

## 快速开始

```html
<!-- 加载反欺诈 SDK -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot、verdict.score、verdict.action —— 见裁决字段参考
      if (verdict.is_bot) {
        // 把该次访问从漏斗中剔除 / 抑制其转化
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>
```

`BotSignal.init()` 同时返回 `Promise<BotVerdict>`,所以你也可以用 `await` 代替
`onVerdict`——两者拿到的是同一个裁决对象。

```js
const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });
```

## 选项

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `appKey` | string | — | 你的反欺诈应用 Key(必填)。 |
| `domain` | string | 服务默认值 | 裁决服务端点。除非你拿到了专用域名,否则保持默认即可。 |
| `escalate` | boolean | `false` | 允许反欺诈在访问看起来高风险时,要求访客**额外做一次验证**。见[升级验证](#escalation)。 |
| `collectWindowMs` | number | `1200` | SDK 在请求裁决前观察访问的时长(毫秒)。窗口越长裁决越有把握,代价是轻微延迟。 |
| `onVerdict` | `(v) => void` | — | 在拿到最终裁决时调用一次。主要的接入点。 |
| `onError` | `(err) => void` | — | 出错时调用。SDK 绝不会向你的页面抛出异常。 |
| `onEscalate` | `(displayType) => void` | — | 展示额外验证时调用(仅当 `escalate: true`)。 |
| `onEscalateDone` | `(passed) => void` | — | 额外验证结束后调用;访客通过则 `passed` 为 `true`。 |

::: tip 流量来源场景
若由第三方把访客送给你,且双方需要就一份逐点击的结论对账,SDK 还能从页面 URL 读取
一个点击 token。这是付费流量场景特有的——见[广告反作弊](./scenarios/ad-fraud)指南。
:::

## 使用裁决

`onVerdict` 收到一个 `BotVerdict` 对象。你最常用到的两个字段:

- **`verdict.is_bot`** —— 当访问被判定为自动化/无效流量时为 `true`。
- **`verdict.action`** —— 我们建议你怎么做:`record_only`、`challenge` 或 `flag`。

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // 看起来正常的流量 —— 正常放行,记录裁决即可
        break;
      case 'flag':
        // 可疑 —— 继续展示页面,但把该次访问标为低质量
        markLowQuality(verdict);
        break;
      case 'challenge':
        // 高风险 —— 若开启升级验证则自动处理(见下文)
        break;
    }
  },
});
```

完整字段列表与建议处理方式见[裁决字段参考](./verdict-reference)。

## 升级验证 {#escalation}

当一次访问看起来高风险时,反欺诈可以在你把访客当作真人之前,要求其完成
**一次额外验证**。这是可选项。

用 `escalate: true` 开启:

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // 正在向访客展示一次额外验证
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // 访客通过了额外验证 —— 当作真人处理
    } else {
      // 未通过 —— 沿用原裁决的建议
    }
  },
  onVerdict: function (verdict) {
    // 若访客通过了升级验证,verdict.is_bot 会被更新为 false
  },
});
```

注意:

- 升级验证仅在裁决的 `action` 为 `challenge` 时触发。其它访问不会展示任何东西,
  访客体验完全不受影响。
- 若访客通过了额外验证,交给 `onVerdict` 的裁决会随之更新(当作真人)。
- 升级验证**失败放行**:如果额外验证无法加载或展示,SDK 会沿用原裁决,而不会阻断你的页面。

::: info
反欺诈从不替你做决定。即便在 `challenge`/`flag` 下,是否放行该次访问仍由你的代码
掌控——SDK 只负责呈现裁决,并(可选地)运行额外验证。
:::

## 容错

如果裁决服务不可达或发生任何错误,SDK 会返回一份**降级(degraded)**裁决
(`degraded: true`),而不是让你的页面失败。降级裁决是保守的(`is_bot: false`、
`action: record_only`),因此永远不会误伤真实用户。若你想对这类访问特殊处理,
检查 `verdict.degraded`。

## 下一步

- [裁决字段参考](./verdict-reference) —— 每个字段及处理方式
- [数据 API](./data-api) —— 服务端拉取与对账裁决