Web和H5客户端V3架构接入_验证码(Captcha)-阿里云帮助中心

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

前提条件

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

方法概述

业务客户端接入验证码2.0只需要3步：

添加全局变量AliyunCaptchaConfig。
动态引入验证码JS。
调用初始化方法进行验证码初始化。

说明

如果您的业务架构是V2版本，请参见Web和H5客户端V2架构接入。
微信小程序目前仅支持接入V2架构，暂不支持接入V3架构。

操作步骤

步骤一：添加全局变量AliyunCaptchaConfig

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

<script>
  window.AliyunCaptchaConfig = {
    // 必填，验证码示例所属地区，支持中国内地（cn）、新加坡（sgp）
    region: "cn",
    // 必填，身份标。开通阿里云验证码2.0后，您可以在控制台概览页面的实例基本信息卡片区域，获取身份标
    prefix: "ab5cde",
  };
</script>

步骤二：动态引入验证码JS

Web页面需动态引入验证码JS，在业务需要验证时，唤起验证码进行验证。

说明

必须动态引入验证码JS，若通过其他方式规避动态加载（例如拉取JS代码本地部署），会导致验证码无法正常更新，无法保证安全能力，甚至引起误拦截或者产生兼容性问题。

<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>

步骤三：调用初始化方法进行验证码初始化。

初始化方法initAliyunCaptcha除了在必要场景下（如初始化参数发生变化）外，不支持重复调用。初始化过程中如果返回失败，请参见客户端初始化报错说明进行排查。

<script type="text/javascript">
  var captcha;
  // 除region和prefix以外的参数
  window.initAliyunCaptcha({...});
</script>

代码示例

说明

验证码JS加载尽量前置，目的是采集更完整的环境和设备信息，验证码JS加载和验证请求之间间隔需要大于2s。
为保障图片资源加载更快，初始化加载的时机尽量前置，初始化和验证请求间隔大于2s，目的是加载验证码相关资源，使图片资源加载更快。
在客户端的源代码中预留验证码页面元素，即element、button参数所指向的DOM元素，如下例中的<div id="captcha-element"></div>。

<!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>
    <div id="captcha-element"></div>
    // 预留的验证码元素，用于配置初始化函数中的element参数
    <button id="button" class="btn">登录</button>
    弹出式下，用于触发验证码弹窗的元素
    <!--3.新建一个<script>标签，用于调用验证码初始化函数initAliyunCaptcha-->
    <script type="text/javascript">
      var captcha;
      // 弹出式，除region和prefix以外的参数
      window.initAliyunCaptcha({
        // 场景ID。根据步骤二新建验证场景后，您可以在验证码场景列表，获取该场景的场景ID
        SceneId: "******",
        // 验证码模式，popup表示弹出式，embed表示嵌入式。无需修改
        mode: "popup",
        // 页面上预留的渲染验证码的元素，与原代码中预留的页面元素保持一致。
        element: "#captcha-element",
        // 触发验证码弹窗或无痕验证的元素
        button: "#button",
        // 验证码验证通过回调函数
        success: function (captchaVerifyParam) {
          // 入参为验签captchaVerifyParam
          // 1.向后端发起业务请求进行验证码验签captchaVerifyParam校验
          // 2.根据校验结果来进行业务处理
          // 3.如业务需要重新进行验证码验证，调用验证码初始化方法initAliyunCaptcha重新初始化验证码
        },
        // 验证码验证不通过回调函数
        fail: function (result) {
          // 入参为不通过信息
          // 正常验证有效期内不需要做任何操作，验证码自动刷新，重新进行验证
          console.error(result);
        },
        // 绑定验证码实例回调函数，该回调会在验证码初始化成功后调用
        getInstance: function (instance) {
          captcha = instance;
        },
        // 滑块验证和一点即过的验证形态触发框体样式，支持自定义宽度和高度，单位为px。
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...其他参数，参考initAliyunCaptcha参数说明
      });
    </script>
  </body>
</html>

参数说明

AliyunCaptchaConfig参数说明

参数

类型

是否必填

默认值

描述

region

String

是

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

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

重要

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

prefix

String

是

无

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

initAliyunCaptcha参数说明

在页面加载完成后尽早调用验证码初始化方法。

参数	类型	是否必填	默认值	描述
SceneId	String	是	无	验证码场景ID，新建验证场景后可获取该值。
mode	String	是	无	验证码模式，可选项： popup：表示弹出式。 embed：表示嵌入式。
element	String	是	无	页面上预留渲染验证码的元素，与源代码中预留的页面元素保持一致。
button	String	是	无	触发验证码弹窗或无痕验证的元素，点击后弹出验证码或触发无痕验证。具体取值与客户端body中的button参数值一致。
success	Function	是	无	验证码验证通过回调函数，透出验证参数，客户可在该回调函数中获取`CaptchaVerifyParam`，请求客户服务端进行验证`CaptchaVerifyParam`校验。
fail	Function	否	无	验证码验证失败回调函数，透出验证失败错误码。
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支持的语言类型。
timeout	Number	否	5000	验证码初始化请求单次请求超时时间，单位为毫秒（ms）。
rem	Number	否	1	对验证码UI进行整体缩放。请传入正数，如0.5是缩小一倍，2是放大一倍。说明参数rem主要针对移动端浏览器使用。
onError	Function	否	无	验证码初始化接口请求和验证码资源加载失败、超时的错误回调函数。
onClose	Function	否	无	验证码弹窗关闭时触发的回调函数。
captchaLogoImg	String	否	无	一点即过、拼图验证或图像复原嵌入式触发按钮右侧的企业Logo更换参数，为图片URL链接或者base64格式数据。

rem参数代码示例

function initCaptcha(rem) {
  window.initAliyunCaptcha({
    SceneId: "xxxxxx",
    mode: "popup",
    element: "#captcha-element",
    button: "#captcha-button",
    success: success,
    fail: fail,
    getInstance: getInstance,
    slideStyle: {
      width: 360,
      height: 40,
    },
    language: "cn",
    rem: rem,
  });
}

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

方法调用说明

调用验证码实例对应方法，其中，无痕模式首次验证不支持下列方法。

方法名

说明

示例

使用场景

show

显示验证码元素、蒙板。

captcha.show()

需要自动弹出（不需要点击按钮）验证码弹框时可以使用。

hide

隐藏或关闭验证码元素、蒙板。

captcha.hide()

需要自动关闭（不需要点击按钮）验证码弹框时可以使用。

返回数据

在验证码2.0接入客户端V3架构的行为验证中，验证码服务端会在验证答案是否正确以及判断是否为机器请求后，将验证码Code和其他参数返回给业务客户端，您可以通过浏览器的Network功能查看返回数据，请参见客户端V3架构返回数据说明。

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140