反欺诈 Web SDK

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

快速开始

<!-- 加载反欺诈 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——两者拿到的是同一个裁决对象。

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

选项

option	type	default	说明
appKey	string	—	必填。你的反欺诈应用 Key。
domain	string	signal-v1.world-dynamic.com	SDK 上报的 Signal 域名。
tokenParam	string	_ctk	SDK 从该 URL 查询参数读取点击 token。
onVerdict	(v) => void	—	在拿到最终裁决时调用一次。主要的接入点。init() 同时返回 Promise<BotVerdict>。
onError	(err) => void	—	任何失败时调用。SDK 绝不会向你的页面抛出异常。
onChallenge	(v) => creds | null | Promise<…>	—	覆盖升级验证所用的凭据:返回你自己的 { appKey, serverToken }(serverToken 由你的后端签发),或返回 null 跳过升级。不设置时使用 verdict.escalate 里后端签发的默认凭据(零配置)。
challengeConfig	object	—	验证码外观/位置:product(popup/float/embed)、container、theme、lang。
onEscalate	(displayType) => void	—	展示升级验证码时调用。
onEscalateDone	(passed, detail) => void	—	升级验证结束后调用。passed = 访客是否通过;detail = { token, challengeId, cid },用于在服务端校验本次通过。

升级是服务端驱动的。 只有当服务端裁决的 action 为 challenge,且该 app 配置了 对应的升级处理动作时,SDK 才会弹出验证码——不存在客户端开关来控制它。可通过 onChallenge 传入你自己的凭据或跳过升级,通过 challengeConfig 控制其样式。访客通过后,用 detail.token(以及 challenge_id/cid)在你自己的后端校验——不要只信客户端的 passed 标志。

流量来源场景

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

使用裁决

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

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

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

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

升级验证

当一次访问看起来高风险时,反欺诈可以在你把访客当作真人之前,要求其完成 一次额外验证。这由服务端裁决驱动,而非客户端开关——只要裁决的 action 为 challenge 且该 app 配置了升级处理动作,它就会运行。

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // 正在向访客展示一次额外验证
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // 访客通过了额外验证 —— 在你的后端校验 detail.token
    } else {
      // 未通过 —— 沿用原裁决的建议
    }
  },
  onVerdict: function (verdict) {
    // 若访客通过了升级验证,verdict.is_bot 会被更新为 false
  },
});

注意:

• 升级验证仅在裁决的 action 为 challenge 时触发。其它访问不会展示任何东西, 访客体验完全不受影响。
• 默认情况下 SDK 使用 verdict.escalate 里后端签发的凭据(零配置)。可通过 onChallenge 传入你自己的 { appKey, serverToken } 或跳过升级,通过 challengeConfig 控制其样式。
• 通过后,用 detail.token(以及 challenge_id/cid)在你自己的后端校验—— 不要只信客户端的 passed 标志。
• 若访客通过了额外验证,交给 onVerdict 的裁决会随之更新(当作真人)。
• 升级验证失败放行:如果额外验证无法加载或展示,SDK 会沿用原裁决,而不会阻断你的页面。

INFO

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

容错

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

下一步

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