Web和H5客户端V2架构接入-阿里云帮助中心

在控制台添加验证场景后，您需要在使用验证功能的Web或H5页面中，集成验证码初始化代码，实现客户端接入。本文介绍如何集成验证码初始化代码。

前提条件

已开开通阿里云验证码2.0服务。
已新建客户端类型为Web或H5的验证场景。

V2验证架构时序图

滑块验证、拼图验证、一点即过和图像复原

时序图说明：

客户在业务客户端初始化验证码，业务客户端会请求验证码服务端，获取验证码资源（例如图片、题目等）。
如果请求失败，客户可以通过业务客户端获取的请求报错信息来排查失败具体原因并进行相应调整或修复。
用户在网页完成验证码交互（例如滑块、拼图、一点即过和图像复原）和应用业务交互（例如登录、注册等）。
完成后，业务客户端会发送验证码参数和业务参数到业务服务端。
业务服务端调用VerifyIntelligentCaptcha接口后，会向验证码服务端发起验证请求，进行风险咨询。
验证码服务端判断验证风险，并将验证结果返回给业务服务端。
业务服务端结合业务逻辑处理业务。完成后，向业务客户端返回验证结果和业务处理结果。
客户端页面显示提示信息，进行业务处理。
如果验证不通过，验证码会刷新，流程返回步骤1。

无痕验证

时序图说明：

客户在业务客户端初始化验证码，业务客户端会请求验证码服务端，获取验证码资源（例如图片、题目等）。
如果请求失败，客户可以通过业务客户端获取的请求报错信息来排查失败具体原因并进行相应调整或修复。
用户在业务客户端完成应用业务交互（例如登录、注册等）。
完成后，业务客户端会发送无痕验证参数和业务参数到业务服务端。
业务服务端调用VerifyIntelligentCaptcha接口后，会向阿里云服务端发起验证请求，进行风险咨询。
阿里云服务端判断验证风险，并将验证结果返回给业务服务端。
业务服务端结合业务逻辑处理业务。
- 如果用户无风险，验证流程结束。
- 如果用户存在风险，触发二次验证。
  1. 用户在网页完成验证码交互（例如滑块、拼图、一点即过和图像复原）和应用业务交互（例如登录、注册等）。
    完成后，业务客户端会发送验证码参数和业务参数到业务服务端。
  2. 业务服务端调用VerifyIntelligentCaptcha接口后，会向阿里云服务端发起验证请求，进行风险咨询。
  3. 阿里云服务端判断验证风险，并将验证结果返回给业务服务端。
  4. 业务服务端结合业务逻辑处理业务。完成后，向业务客户端返回验证结果和业务处理结果。
  5. 客户端页面显示提示信息，进行业务处理。
    如果验证不通过，客户端页面会重新唤起验证码，流程返回步骤i。

集成验证码初始化代码

Web或H5页面支持弹出式、嵌入式两种形态。下文以登录场景为例，介绍如何在客户端源代码中集成验证码。

在客户端的源代码中预留验证码页面元素，即element、button参数所指向的DOM元素，如下例中的<div id="captcha-element"></div>。建议将业务模块容器的高度设置为自适应，以免后续切换验证码类型时因为验证码高度变化而造成元素超出容器高度。这里以登录场景为例。

重要

集成后，如果您在控制台修改场景配置（例如验证码形态），无需再次调整初始化参数和页面结构，程序会根据配置按需加载。

// 客户端原代码举例
 const button = document.getElementById('button');
 button.onclick = function () {
   // 请求后端接口...
   const result = await getWithParams('xx', { 
       yourBizParam... // 业务参数
   });                
   const { bizResult } = result;
   if (bizResult) {
     // 跳转到对应页面。此处以跳转到https://www.aliyun.com/页面为例
     window.location.href = 'https://www.aliyun.com/';
   }
 }

// 客户端body中的代码
<div id="space-semantic">
    <div id="embed-wrapper">
        <h2>弹出式</h2>
        <div class="embed-wrapper">
            <div>
                <label>用户名：</label>
                <input id="username-embed" class="biz-input">
            </div>
            <div>
                <label>密码：</label>
                <input id="password-embed" type="password" class="biz-input">
            </div>
            <div id="captcha-element"></div>  //预留的验证码页面元素，用于配置初始化函数中的element参数
            <button id="button" class="login-btn">登录</button>
        </div>
    </div>
</div>

集成验证码初始化代码，包含全局变量和验证码JS脚本，在引入阿里云验证码JS脚本的位置之前，或在html的head标签最前的位置添加一个script脚本，保存一个含有region和prefix参数的全局变量AliyunCaptchaConfig即可。

重要

必须动态引入验证码JS，若通过其他方式规避动态加载（例如拉取JS代码本地部署），会导致验证码无法正常更新，无法保证安全能力，甚至引起误拦截或者产生兼容性问题。
验证码JS加载尽量前置，目的是采集更完整的环境和设备信息，验证码JS加载和验证请求之间间隔需要大于2s。
为保障图片资源加载更快，初始化加载的时机尽量前置，初始化和验证请求间隔大于2s，目的是加载验证码相关资源，使图片资源加载更快。
初始化方法initAliyunCaptcha除了在必要场景下（如初始化参数发生变化）外，不支持重复调用。

弹出式

<!doctype html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="data-spm" />
        <!--1.在引入阿里云验证码JS脚本的位置之前，或者在html的head标签最前的位置添加一个script脚本，里面保存一个含有region和prefix参数的全局变量AliyunCaptchaConfig即可-->
        <script>
            window.AliyunCaptchaConfig = {
                // 必填，验证码示例所属地区，支持中国内地（cn）、新加坡（sgp）
                region: "cn",
                // 必填，身份标。开通阿里云验证码2.0后，您可以在控制台概览页面的实例基本信息卡片区域，获取身份标
                prefix: "xxxxxx",
            };
        </script>
        <!--2.集成主JS-->
        <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js">
        </script>
    </head>
    
    <body>
        <!--3.新建一个<script>标签，用于调用验证码初始化函数initAliyunCaptcha-->
        <script type="text/javascript">
            var captcha;
            // 弹出式，除region和prefix以外的参数
            window.initAliyunCaptcha({
                // 场景ID。根据步骤二新建验证场景后，您可以在验证码场景列表，获取该场景的场景ID
                SceneId: 'c9h3****',
                // 验证码模式。popup表示要集成的验证码模式为弹出式。无需修改
                mode: 'popup',
                //页面上预留的渲染验证码的元素，与原代码中预留的页面元素保持一致。
                element: '#captcha-element',
                // 触发验证码弹窗的元素。button表示单击登录按钮后，触发captchaVerifyCallback函数。您可以根据实际使用的元素修改element的值
                button: '#button',
                // 业务请求(带验证码校验)回调函数，无需修改
                captchaVerifyCallback: captchaVerifyCallback,
                // 业务请求结果回调函数，无需修改
                onBizResultCallback: onBizResultCallback,
                // 绑定验证码实例函数，无需修改
                getInstance: getInstance,
                // 滑块验证码样式，支持自定义宽度和高度，单位为px。其中，width最小值为320 px
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // 验证码语言类型，支持简体中文（cn）、繁体中文（tw）、英文（en）
                language: 'cn',
            });
            function getInstance(instance) {
                captcha = instance
            }
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1.向后端发起业务请求，获取验证码验证结果和业务结果
                const result = await xxxx('http://您的业务请求地址', {
                    // 验证码参数
                    captchaVerifyParam: captchaVerifyParam,
                   // 业务参数
                    yourBizParam... 
                });

                // 2.构造标准返回参数
                const verifyResult = {
                    // 验证码验证是否通过，boolean类型，必选。
                    captchaResult: result.captchaVerifyResult,
                    // 业务验证是否通过，boolean类型，可选；若为无业务验证结果的场景，bizResult可以为空。
                    bizResult: 从result获取您的业务验证结果,

                };
                return verifyResult;
            }

            // 业务请求验证结果回调函数
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // 如果业务验证通过，跳转到对应页面。此处以跳转到https://www.aliyun.com/页面为例
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // 如果业务验证不通过，给出不通过提示。此处不通过提示为业务验证不通过！
                    alert('业务验证不通过！');
                }
            }
        </script>
    </body>
</html>

嵌入式

<!doctype html>
<html>
    
    <head>
        <meta charset="utf-8" />
        <meta name="data-spm" />
        <!-- 1. 在引入阿里云验证码JS脚本的位置之前，或者在html的head标签最前的位置添加一个script脚本，里面保存一个含有region和prefix参数的全局变量AliyunCaptchaConfig即可
        -->
        <script>
            window.AliyunCaptchaConfig = {
                // 必填，验证码示例所属地区，支持中国内地（cn）、新加坡（sgp）。
                region: "cn",
                // 必填，身份标。开通阿里云验证码2.0后，您可以在控制台概览页面的实例基本信息卡片区域，获取身份标。
                prefix: "xxxxxx",

            };
        </script>
        <!-- 2.集成主JS -->
        <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js">
        </script>
    </head>
    
    <body>
        <!-- 3.新建一个<script>标签，用于调用验证码初始化函数initAliyunCaptcha -->
        <script type="text/javascript">
            var captcha;
            // 嵌入式，除region和prefix以外的参数
            window.initAliyunCaptcha({
                // 场景ID。通过步骤一添加验证场景后，您可以在验证码场景列表，获取该场景的场景ID
                SceneId: 'c9h3****',
                // 验证码模式。embed表示要集成的验证码模式为嵌入式。无需修改
                mode: 'embed',
                // 页面上预留的渲染验证码的元素，与原代码中预留的页面元素保持一致。
                element: '#captcha-element',
                // 触发业务请求的元素。button表示单击登录按钮后，触发captchaVerifyCallback函数。您可以根据实际使用的元素修改element的值
                button: '#button',
                // 业务请求(带验证码校验)回调函数，无需修改
                captchaVerifyCallback: captchaVerifyCallback,
                // 业务请求结果回调函数，无需修改
                onBizResultCallback: onBizResultCallback,
                // 绑定验证码实例函数，无需修改
                getInstance: getInstance,
                // 滑块验证码样式，支持自定义宽度和高度，单位为px。其中，width最小值为320 px
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // 验证码语言类型，支持简体中文（cn）、繁体中文（tw）、英文（en）
                language: 'cn',
                // 完成验证后，是否立即发送验证请求（调用captchaVerifyCallback函数）
                immediate: false,
            });

            // 绑定验证码实例函数。该函数为固定写法，无需修改
            function getInstance(instance) {
                captcha = instance;
            }

            // 业务请求(带验证码校验)回调函数
            /**
              * @name captchaVerifyCallback
              * @function
              * 请求参数：由验证码脚本回调的验证参数，不需要做任何处理，直接传给服务端即可
              * @params {string} captchaVerifyParam
              * 返回参数：字段名固定，captchaResult为必选；如无业务验证场景时，bizResult为可选
              * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}}
              */
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1.向后端发起业务请求，获取验证码验证结果和业务结果
                const result = await xxxx('http://您的业务请求地址', {
                    // 验证码参数
                    captchaVerifyParam: captchaVerifyParam,
                    // 业务参数
                    yourBizParam... 
                });

                // 2.构造标准返回参数
                const verifyResult = {
                    // 验证码验证是否通过，boolean类型，必选。
                    captchaResult: result.captchaVerifyResult,
                    // 业务验证是否通过，boolean类型，可选；若为无业务验证结果的场景，bizResult可以为空。
                    bizResult: 从result获取您的业务验证结果,

                };
                return verifyResult;
            }

            // 业务请求验证结果回调函数
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // 如果业务验证通过，跳转到对应页面。此处以跳转到https://www.aliyun.com/页面为例
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // 如果业务验证不通过，给出不通过提示。此处不通过提示为业务验证不通过！
                    alert('业务验证不通过！');
                }
            }
        </script>
    </body>

</html>

其中的captchaVerifyCallback使用ES6语法，如需要使用ES5语法，则参照以下示例，调用captchaVerifyCallback的第二个参数callback回调，将验证结果传入即可：

/**
 * @name captchaVerifyCallback
 * @function
 * @param {String} captchaVerifyParam - 由验证码脚本回调的验证参数，不需要做任何处理，直接传给服务端即可
 * @param {Function} callback - 回调函数，用于处理验证结果，ES5语法兼容
 */
function captchaVerifyCallback(captchaVerifyParam, callback) {
  // 1.向后端发起业务请求，获取验证码验证结果和业务结果
  requestVerifyResult('http://您的业务请求地址', { 
      captchaVerifyParam: captchaVerifyParam, // 验证码参数
      yourBizParam... // 业务参数
  }, function(result) {
      // 2.构造标准返回参数
      var verifyResult = {
          captchaResult: result.captchaVerifyResult,
          bizResult: result.bizResult,
      };    
      // 调用回调函数，传入验证结果
      callback(verifyResult);
  });
}

如果您在接入过程中遇到任何问题，请提交工单联系我们。

参数说明

AliyunCaptchaConfig参数说明

参数

类型

是否必填

默认值

描述

region

String

是

验证码实例所属地域。取值：

cn：表示中国内地。
sgp：新加坡。

重要

客户端接入region参数和服务端接入地址endpoint不一致，会导致验证请求返回错误
产品在中国内地（华东2（上海））和新加坡分别设置了管控中心平面，根据客户自行配置的调用参数，客户端采集的行为数据、设备数据等将回传对应中心处理，主要实现安全验证功能。

prefix

String

是

无

验证码身份标识，开通验证码2.0后，可获取该值。

initAliyunCaptcha参数说明

参数	类型	是否必填	默认值	描述
SceneId	String	是	无	验证码场景ID，新建验证场景后可获取该值。
mode	String	是	无	验证码模式。可选项： popup：表示弹出式。 embed：表示嵌入式。
element	String	是	captcha-element	页面上预留渲染验证码的元素，与源代码中预留的页面元素保持一致。
button	String	是	无	触发验证码弹窗的元素。具体取值与客户端body中的button参数值一致。
captchaVerifyCallback	Function	是	captchaVerifyCallback	业务请求（带验证码校验）回调函数。更多信息，请参见captchaVerifyCallback。
onBizResultCallback	Function	是	onBizResultCallback	业务请求结果回调函数，用于设置验证结果处理逻辑。
getInstance	Function	是	getInstance	绑定验证码实例函数，固定写法为： `function getInstance(instance) { captcha = instance; }`
slideStyle	Object	否	{ width: 360, height: 40 }	滑块验证码样式，支持自定义宽度和高度，单位为px。重要由于验证码需要通过滑动采集足够多的信息用于策略模型判断，所以，建议您将滑块的宽度（width值）最小设置为320 px。如果width值小于320 px，系统会按照320 px进行配置。该参数仅对滑块模式有效，并不适用于拼图验证码。如果您使用的是拼图验证码，由于拼图验证码的图像尺寸和验证答案是预设固定的，请不要复写 CSS 强行修改样式，否则会导致验证异常。
language	String	否	cn	验证码2.0支持的语言类型。
immediate	Boolean	否	false	嵌入式下，完成验证后，是否立即发送验证请求（调用captchaVerifyCallback函数）。
timeout	Number	否	5000	验证码初始化请求单次请求超时时间，单位为毫秒（ms）。
rem	Number	否	1	对验证码UI进行整体缩放。请传入正数，如0.5是缩小一倍，2是放大一倍。说明参数rem主要针对移动端浏览器使用。
autoRefresh	Boolean	否	true	设置验证码验证通过后是否自动刷新验证码。说明设置为false后，需手动调用实例方法刷新验证码，参考常见问题Q4。
onError	Function	否	无	验证码初始化接口请求失败或超时的错误回调函数。
captchaLogoImg	String	否	无	一点即过形态验证码按钮右侧的企业Logo更换参数，为图片URL链接或者base64格式数据。

rem参数代码示例

function initCaptcha(rem) {
  window.initAliyunCaptcha({
    SceneId: 'xxxxxx',
    prefix: 'xxxxxx',
    mode: 'popup',
    element: '#captcha-element',
    button: '#captcha-button',
    captchaVerifyCallback: captchaVerifyCallback,
    onBizResultCallback: onBizResultCallback,
    getInstance: getInstance,
    slideStyle: {
        width: 360,
        height: 40,
    },
    region: 'sgp',
    language: 'cn',
    rem: rem,
  });
}

const pageWidth = window.innerWidth;
if (pageWidth <= 320) {
  const rem = Math.floor(pageWidth / 320);
  initCaptcha(rem);
}

captchaVerifyCallback参数说明

请求参数
参数
类型
是否必填
默认值
描述
captchaVerifyParam
String
是
captchaVerifyParam
验证码参数。由验证码脚本回调的验证参数，不需要做任何处理，直接传给服务端即可
返回参数
参数
类型
默认值
描述
captchaResult
Boolean
无
验证码验证是否通过。
bizResult
Boolean
无
业务验证是否通过。如果为无业务验证结果的场景，bizResult取值可以为空。