反欺诈 Web SDK

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

快速开始

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

<script>
  BotSignal.init({
    appKey: 'YOUR_AD_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——两者拿到的是同一个裁决对象。

const verdict = await BotSignal.init({ appKey: 'YOUR_AD_APP_KEY' });

选项

选项	类型	默认值	说明
appKey	string	—	你的反欺诈应用 Key(必填)。
domain	string	服务默认值	裁决服务端点。除非你拿到了专用域名,否则保持默认即可。
tokenParam	string	自动识别	URL 查询参数名,用于携带服务商的点击 token(如 click_token)。SDK 会从落地 URL 中读取它,并把裁决与该次点击关联。
escalate	boolean	false	允许反欺诈在访问看起来高风险时,要求访客额外做一次验证。见升级验证。
collectWindowMs	number	1200	SDK 在请求裁决前观察访问的时长(毫秒)。窗口越长裁决越有把握,代价是轻微延迟。
onVerdict	(v) => void	—	在拿到最终裁决时调用一次。主要的接入点。
onError	(err) => void	—	出错时调用。SDK 绝不会向你的页面抛出异常。
onEscalate	(displayType) => void	—	展示额外验证时调用(仅当 escalate: true)。
onEscalateDone	(passed) => void	—	额外验证结束后调用;访客通过则 passed 为 true。

使用裁决

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

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

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

完整字段列表与建议处理方式见裁决字段参考。

升级验证

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

用 escalate: true 开启:

BotSignal.init({
  appKey: 'YOUR_AD_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。

下一步

• 裁决字段参考 —— 每个字段及处理方式
• 数据 API —— 服务端拉取与对账裁决