Web 应用集成SDK

您必须在应用中集成JSSDK，才能配置网页防爬场景化规则。本文介绍了如何为Web应用集成WAF防护JSSDK（以下简称JSSDK）。

组件

Web JSSDK集成包括JavaScript挑战、异步接口响应两个组件。

JavaScript挑战组件

JavaScript挑战组件是JavaScript挑战能力的Web集成模块。当在控制台配置开启了网页防爬场景化的JavaScript挑战能力之后，WAF会对访问了该配置路径的流量发起JavaScript挑战，若客户端未通过挑战，则不会返回真实页面，会对拒绝的请求并返回JavaScript挑战验证页。

JavaScript挑战组件会在客户端页面的域名下植入cookie，以帮助客户端完成JavaScript挑战，站长可以通过自动集成或者手动集成的情况下接入该组件，在自动集成的情况下，WAF会为站点所有页面在最前方注入该组件，而在手动集成的情况下，客户需要手动将该组件写在页面最前方位置。

在客户端中，若发起的页面请求，WAF会返回一个可以执行JavaScript代码中间页，并在中间页中加载并执行该组件种下cookie，之后刷新页面。若客户端发起的是异步请求，WAF会在该异步请求所在页面的最前方注入并执行该组件，以种下cookie。 JavaScript挑战植入的cookie是有有效期的，在页面集成该组件的情况下，定期刷新这个cookie，以保证cookie在有限期内。

异步接口响应组件

在防爬场景化配置页面中，可以配置对指定条件下的接口开启了动态签名功能，以及滑块验证码功能，这两个功能需要通过自动或者手动方式集成异步接口响应组件来完成。 异步响应组件包含两个能力，客户端签名能力和验证码弹出能力，自动集成了异步响应组件之后，组件将接管Web应用的异步请求，在请求发起与请求响应时，完成指定挑战任务（动态签名挑战与验证码挑战），待客户端完成挑战任务之后，客户端才会执行后续动作。

异步接口响应组件自动集成工作原理：

1、Hook异步API：在自动集成异步接口响应组件的情况下，组件会全局重写XMLHttpRequest（xhr）、Fetch两个异步请求的Web API，在API接口请求对象上额外封装一层代码，通常情况不会影响原始对象的各种特性。

2、动态签名注入：对通过XMLHttpRequest、Fetch这两个Web API发起的所有异步接口的请求URL中添加一个query参数作为动态签名。

3、验证码挑战：当异步请求响应式，组件会通过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会再次返回验证码挑战标识

部署方式

1、自动集成

可在配置网页防爬场景化的防护场景定义时，选择自动集成，此时网站HTML页面由WAF接管，WAF会在页面请求响应时，向页面注入组件script标签，客户网页无需进行代码改造即可完成部署，同时享受线上组件的热更新。

2、手动集成 适合于无法满足自动集成的场景，或者当前站点与组件产生冲突的情况，手动集成必须满足以下条件

• 所有依赖配置了防护场景的 API 接口所在的页面，都必须接入特定组件
• 在页面使用组件功能之前，必须先完成组件script代码的注入

JavaScript挑战组件

<script>window.__noxImd = 1</script>
<script src="https//sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/nox_20241230.js"></script>

异步接口响应组件

<script src="https//sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/tox_20241230.js"></script>

如内容安全策略csp不允许从sec-captcha-waf.cdn.bcebos.com加载资源，可将组件资源下载至服务本地进行本地化部署

3、JSAPI

在手动集成了异步接口响应组件之后，可通过一下JSAPI生成动态签名和验证码挑战。

动态签名生成：

1、通过Tox.getToken获取动态签名，若网络波动导致异步接口响应组件加载失败，可以使用错误码 499 作为降级签名

var toxToken = typeof Tox !== 'undefined' ? Tox.getToken() : '499';

2、将toxToken添加到防护场景的API接口的URL Query参数中，query的key为tox_token，value为toxToken，如下

/path/to/request?query1=value1&tox_token={toxToken}

验证码挑战：

1、通过 Tox.isCaptchaResponse 先判断当前response是否为WAF发起的验证码挑战标识。

// 传入响应状态码status、响应类型content-type、响应体body
const isWafCaptchaFlag = Tox.isCaptchaResponse(status, contentType, responseBody);

2、然后通过 Tox.getCaptchaToken 发起验证码挑战，并通过回调获取验证码通过之后的token。

// 传入响应体body、回调函数callback
Tox.getCaptchaToken(responseBody, function (captchaToken) {
    // 处理captchaToken
});

3. 将captchaToken添加到防护场景的API接口的URL Query参数中，query的key为svcp_stk，value为captchaToken，如下：

/path/to/request?query1=value1&svcp_stk={captchaToken}

常见问题

兼容性说明

1.浏览器环境兼容性：兼容IE10内核以上各类浏览器与客户端容器。

2.兼容性依赖：客户端需要支持cookie功能。容器或请求本身不支持cookie，则JavaScript挑战组件功能会被影响。

3.Hook兼容。

第三方组件冲突：异步接口响应组件会对所有异步请求的query中添加参数，这会与不支持多余query参数的第三方组件产生冲突

非标异步请求冲突：异步接口响应组件在添加query参数过程中，会按照标准对请求的URL进行解析并编码，若服务器接口解析URL的方式不标准，则会产生冲突

关于Hook兼容冲突问题，可通过手动接入的形式避免冲突的产生。

组件副作用说明

性能增加

1、自动集成情况下，会在页面head标签中注入组件script，若网络波动导致组件加载过慢，会导致页面出现白屏。

2、自动集成情况下，异步接口响应组件会为页面接口无差别添加动态签名tox_token，这会消耗部分计算资源