Web 应用集成SDK
更新时间：2026-06-03
基于 JavaScript 的 SDK 用以提升 web 浏览器场景下的防护效果并避免一些不兼容问题。开启自动集成后将自动在相应防护对象的 HTML 页面中引用它们，并采集相关的浏览器环境信息、黑产工具探针、操作行为等（不涉及个人敏感信息）。
Web JSSDK 集成包括 JavaScript 挑战、异步接口响应两个组件。
JavaScript 挑战组件
JavaScript 挑战组件是 JavaScript 挑战能力的 Web 集成模块。当在控制台配置开启了网页防爬场景化的 JavaScript 挑战能力之后，WAF 会对访问了该配置路径的流量发起 JavaScript 挑战，若客户端未通过挑战，则不会返回真实页面，会拒绝该请求并返回 JavaScript 挑战验证页。
JavaScript 挑战组件会在客户端页面的域名下植入 cookie，以帮助客户端完成 JavaScript 挑战。站长可以通过自动集成或手动集成的方式接入该组件：自动集成时，WAF 会为站点所有页面在最前方注入该组件；手动集成时，需要手动将该组件写在页面最前方位置。
在客户端中，若发起的是页面请求，WAF 会返回一个可执行 JavaScript 代码的中间页，并在中间页中加载并执行该组件种下 cookie，之后刷新页面。若客户端发起的是异步请求，WAF 会在该异步请求所在页面的最前方注入并执行该组件，以种下 cookie。JavaScript 挑战植入的 cookie 有有效期，在页面集成该组件的情况下，定期刷新这个 cookie，以保证 cookie 在有效期内。
JavaScript 挑战组件会在客户端页面的域名下植入 cookie，以帮助客户端完成 JavaScript 挑战。站长可以通过自动集成或手动集成的方式接入该组件：自动集成时，WAF 会为站点所有页面在最前方注入该组件；手动集成时，需要手动将该组件写在页面最前方位置。
在客户端中，若发起的是页面请求，WAF 会返回一个可执行 JavaScript 代码的中间页，并在中间页中加载并执行该组件种下 cookie，之后刷新页面。若客户端发起的是异步请求，WAF 会在该异步请求所在页面的最前方注入并执行该组件，以种下 cookie。JavaScript 挑战植入的 cookie 有有效期，在页面集成该组件的情况下，定期刷新这个 cookie，以保证 cookie 在有效期内。
异步接口响应组件
在防爬场景化配置页面中，可以配置对指定条件下的接口开启动态签名功能以及滑块验证码功能，这两个功能需要通过自动或手动方式集成异步接口响应组件来完成。异步响应组件包含两个能力：客户端签名能力和验证码弹出能力。自动集成异步响应组件之后，组件将接管 Web 应用的异步请求，在请求发起与请求响应时，完成指定挑战任务（动态签名挑战与验证码挑战），待客户端完成挑战任务之后，客户端才会执行后续动作。
异步接口响应组件自动集成工作原理：
自动集成异步接口响应组件时：
会自动进行 XMLHttpRequest 和 fetch 的 hook，此时 hook 可能会产生兼容性冲突问题（详情见下文兼容性说明章节），若无法处理产生的冲突，则可以选择使用手动集成的形式。手动集成形式不会对 XMLHttpRequest 和 fetch 进行 hook，站长需要通过异步接口响应组件提供的 JSAPI，在防护场景的 API 接口上手动进行动态签名注入和验证码挑战。
手动集成异步接口响应组件时：
异步接口响应组件自动集成工作原理：
- Hook 异步 API：在自动集成异步接口响应组件的情况下，组件会全局重写 XMLHttpRequest（xhr）、Fetch 两个异步请求的 Web API，在 API 接口请求对象上额外封装一层代码，通常情况不会影响原始对象的各种特性。
- 动态签名注入：对通过 XMLHttpRequest、Fetch 这两个 Web API 发起的所有异步接口的请求 URL 中添加一个 query 参数作为动态签名。
- 验证码挑战：当异步请求响应时，组件会通过 Hook 先判断当前 response 是否为 WAF 发起的验证码挑战标识，若 response 为验证码挑战标识，页面会弹出验证码进行验证码挑战，待客户端完成挑战后，携带验证码 Token 对请求进行重试；若 response 并非 WAF 返回的验证码挑战标识，组件不会执行任何动作，将结果传递给站点本身的 JS 代码执行。
异步接口响应组件 Hook 功能只会对 XMLHttpRequest 和 fetch 发起的异步请求添加动态签名挑战与验证码挑战，对于 SSE（Server-Sent Events）、Form 表单提交、Image、script 标签发起的请求，不会自动完成异步接口响应组件的挑战。
自动集成异步接口响应组件时：
会自动进行 XMLHttpRequest 和 fetch 的 hook，此时 hook 可能会产生兼容性冲突问题（详情见下文兼容性说明章节），若无法处理产生的冲突，则可以选择使用手动集成的形式。手动集成形式不会对 XMLHttpRequest 和 fetch 进行 hook，站长需要通过异步接口响应组件提供的 JSAPI，在防护场景的 API 接口上手动进行动态签名注入和验证码挑战。
手动集成异步接口响应组件时：
- 对于动态签名能力，需要确保配置并开启了动态签名场景化保护的接口一定要携带上动态签名，否则 WAF 将会拒绝访问。
- 对于滑块验证码能力，需要确保配置并开启了异常流量处置的场景化保护接口在被 WAF 返回验证码挑战标识之后，若要对接口进行重试，必须携带上验证码验证通过之后的 token，否则 WAF 会再次返回验证码挑战标识。
部署方式
自动集成
可在配置网页防爬场景化的防护场景定义时，选择自动集成，此时网站 HTML 页面由 WAF 接管，WAF 会在页面请求响应时，向页面注入组件 script 标签，客户网页无需进行代码改造即可完成部署，同时享受线上组件的热更新。
自动集成情况下会在页面 head 标签中注入组件 script，若网络波动导致组件加载过慢，可能出现页面白屏。
手动集成
适用于无法满足自动集成的场景，或当前站点与组件产生冲突的情况。手动集成必须满足以下条件：
- 所有依赖配置了防护场景的 API 接口所在的页面，都必须接入特定组件
- 在页面使用组件功能之前，必须先完成组件 script 代码的注入
HTML
1<script>window.__noxImd = 1</script>
2<script src="https://sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/nox_20241230.js"></script>
异步接口响应组件
HTML
1<script src="https://sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/tox_20241230.js"></script>如内容安全策略 CSP 不允许从 sec-captcha-waf.cdn.bcebos.com 加载资源，可将组件资源下载至服务本地进行本地化部署。
JSAPI
在手动集成了异步接口响应组件之后，可通过以下 JSAPI 生成动态签名和发起验证码挑战。
动态签名生成：
1、通过
动态签名生成：
1、通过
Tox.getToken 获取动态签名，若网络波动导致异步接口响应组件加载失败，可以使用错误码 499 作为降级签名：
JavaScript
1var toxToken = typeof Tox !== 'undefined' ? Tox.getToken() : '499';
2、将 toxToken 添加到防护场景的 API 接口的 URL Query 参数中，query 的 key 为
tox_token，value 为 toxToken，如下：
Text
1/path/to/request?query1=value1&tox_token={toxToken}
验证码挑战：
1、通过
1、通过
Tox.isCaptchaResponse 先判断当前 response 是否为 WAF 发起的验证码挑战标识：
JavaScript
1// 传入响应状态码 status、响应类型 content-type、响应体 body
2const isWafCaptchaFlag = Tox.isCaptchaResponse(status, contentType, responseBody);
2、然后通过
Tox.getCaptchaToken 发起验证码挑战，并通过回调获取验证码通过之后的 token：
JavaScript
1// 传入响应体 body、回调函数 callback
2Tox.getCaptchaToken(responseBody, function (captchaToken) {
3 // 处理 captchaToken
4});
将 captchaToken 添加到防护场景的 API 接口的 URL Query 参数中，query 的 key 为
svcp_stk，value 为 captchaToken，如下：
Text
1/path/to/request?query1=value1&svcp_stk={captchaToken}常见问题
兼容性说明
- 浏览器环境兼容性：兼容 IE10 内核以上各类浏览器与客户端容器。
- 兼容性依赖：客户端需要支持 cookie 功能。容器或请求本身不支持 cookie，则 JavaScript 挑战组件功能会被影响。
- Hook 兼容：
- 第三方组件冲突：异步接口响应组件会对所有异步请求的 query 中添加参数，这会与不支持多余 query 参数的第三方组件产生冲突。
- 非标异步请求冲突：异步接口响应组件在添加 query 参数过程中，会按照标准对请求的 URL 进行解析并编码，若服务器接口解析 URL 的方式不标准，则会产生冲突。
组件副作用说明
性能增加
- 自动集成情况下，会在页面 head 标签中注入组件 script，若网络波动导致组件加载过慢，会导致页面出现白屏。
- 自动集成情况下，异步接口响应组件会为页面接口无差别添加动态签名 tox_token，这会消耗部分计算资源。
评价此篇文章