Web/H5 接入

整体介绍验证码服务的客户端与服务端通讯过程：

1. 业务客户端集成验证码 SDK，拉起验证并完成人机验证；
2. 验证通过后客户端获得验证码 token 数据 stk；
3. 前端将 stk 传给业务服务端（可通过 query 参数、header 等方式，业务自定义）；
4. 业务服务端拿到 stk，进行 AES 加密，生成加密数据；
5. 调用验证码平台 /v1/webapi/verint/verifystk 接口发起验签；
6. 获取接口返回结果并解密，根据解密后的 pass 字段判断是否校验通过。

1. 接入准备

• 在控制台添加验证场景，获取场景分配的 AccessKey（下文 ak 参数）。
• 确认业务页面运行环境：使用验证码功能的页面须为 Web 或 H5 页面，可运行于 Chrome、Firefox、Safari 等主流桌面与移动端浏览器。

2. 安装

第一步：下载 BiocFacade.js，点击下载，将 BiocFacade.js 部署到服务器本地。

第二步：在 Web 页面引入 BiocFacade.js。

1<script src="/path/to/BiocFacade.js"></script>

3. 快速开始

本节通过简单示例，演示如何创建并展示验证码。

为便于快速上手，此处省略细节，仅展示最基本的用法（全部采用默认参数调用）。

如需深入了解全部 API 方法、配置参数及更复杂的功能，请参考 5. JSAPI。

3.1 全局浮窗验证码

全局浮窗验证码以独立浮层展示，覆盖于页面内容之上。业务前端无需改动页面结构，直接调用 JS 即可获取验证码 Token。

调用 BiocFacade.createCaptcha 创建验证码实例，再通过返回对象的 showPopup 方法以全局浮窗形式展示。

1const ak = 'xxx'; // 在控制台中获取 AccessKey
2
3// 创建验证码实例
4const captcha = window.BiocFacade.createCaptcha({ak});
5
6// 监听验证码成功回调函数
7captcha.onSuccess(tokenInfo => {
8    const stk = tokenInfo.stk;
9    // TODO: 处理token，如在接口请求中传递至后端
10});
11
12// 通过全局浮窗弹出验证码
13captcha.showPopup();

3.2 嵌入式验证码

嵌入式验证码将验证码内容嵌入页面的指定区域，与其他页面内容一同展示。

调用 BiocFacade.createCaptcha 创建验证码实例，再通过返回对象的 appendTo 方法将其嵌入到指定容器中。

1const ak = 'xxx'; // 在控制台中获取 AccessKey
2
3// 展示验证码的容器
4const container = document.getElementById('container');
5
6// 创建验证码实例
7const captcha = window.BiocFacade.createCaptcha({ak});
8
9// 监听验证码成功回调函数
10captcha.onSuccess(tokenInfo => {
11    var stk = tokenInfo.stk;
12    // TODO: 处理token，如在接口请求中传递至后端
13});
14
15// 将验证码嵌入到指定容器
16captcha.appendTo(container);
17// 或者类似document.querySelector形式
18// captcha.appendTo('#container');

4. 验证码 Token

验证码触发 onSuccess 事件后，即可获取验证码 Token，其数据格式如下：

1export type Token = {
2    pass: boolean; // 验证码通过情况
3    stk: string; // 验证码 token 数据
4    v: string; // 版本号
5};

业务方无需关注 pass 等内部字段，只需将 stk 传递至服务端完成验签即可。服务端验签流程详见《服务端接入》。

5. JSAPI

本节提供更详细的信息，包括所有的 API 方法、配置参数和回调函数。

5.1 BiocFacade.createCaptcha

BiocFacade.createCaptcha：创建验证码。使用返回对象的 showPopup 进行全局浮窗展示，使用返回对象的 appendTo 嵌入到指定容器。

1// 全局浮窗
2// 创建验证码
3const captcha = BiocFacade.createCaptcha(config);
4// 浮窗验证码
5captcha.showPopup();

1// 嵌入式
2// 创建验证码
3const captcha = BiocFacade.createCaptcha(options);
4// 嵌入式验证码
5captcha.appendTo(container);

5.2 options 配置参数

5.3 返回对象实例事件 API

6. language 列表

验证码提示文案支持的语言列表：

7. 客户端容灾

安全验证码自带了资源&请求的主备切换、自动重试机制，提升整体服务的可用性，同时BiocFacade内置了一个脱离服务器的本地验证码token生成机制，这代表着当安全验证码在服务器出现宕机时，客户端会自动切换到离线验证的机制，保证业务方页面可以正常运行不受影响。

当安全验证码的容灾机制被触发时，弹窗的验证码将变成容灾验证码，展示如下：

用户点击区域即可完成验证生成验证码token，业务前端直接获取到。

8. 服务端验签

客户端验证通过拿到 stk 后，业务服务端需调用 verifystk 接口完成二次校验，详见《服务端接入》。