通过前端代码为Web页面接入AI验证码-边缘安全加速-阿里云

以在登录页面test.example.com/login添加一点即过验证场景为例，通过两步完成AI验证码的接入。

第一步：配置验证码规则

首先需要配置需要验证的URI、验证码类型等基本信息。

登录ESA控制台，点击进入AI验证码配置页面。
在配置页面，单击新增规则按钮。
在新增规则页面填下以下内容：
- 规则名称：填写自定义名称，如login。
- 需验签的接口：填写需要接入验证码的URI，本例中填写test.example.com/login。
- 需验签的请求方法：选择需要验证码验证的请求方法，本例中选择GET、POST。
- 验证码类型：选择验证码类型，本例中选择一点即过。
  其他类型可参见验证码形态与选择建议。

第二步：集成前端代码

在控制台添加验证规则后，需要在使用验证功能的Web或H5页面中，集成验证码初始化代码，实现客户端接入。

获取身份校验信息

ESA通过身份标和场景ID信息进行身份校验，在进行前端代码添加前需要先获取：

身份标：在配置页面右上角可获取对应信息。
场景ID：在配置页面的相应规则条目的场景ID列可获取对应信息。

添加script脚本

在需要添加验证码的前端代码，如login.html中添加下述3段script脚本：

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

<script>
  window.AliyunCaptchaConfig = {
    region: "cn",  //必填，验证码示例所属地区，支持中国内地（cn）、新加坡（sgp）
    prefix: "IDENTITY",   //必填，身份标。将IDENTITY更换为上一步中获取的身份标，如:esa-q2*****cqb
  };
</script>

动态引入验证码JS：在AliyunCaptchaConfig变量脚本后添加一段动态引入验证码的JS，在业务需要验证时，唤起验证码进行验证。
说明
必须动态引入验证码JS，若通过其他方式规避动态加载（例如拉取JS代码本地部署），会导致验证码无法正常更新，无法保证安全能力，甚至引起误拦截或者产生兼容性问题。
```
<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>
```
添加验证码初始化方法：调用初始化方法initAliyunCaptcha进行验证码初始化。详细说明参见initAliyunCaptcha参数说明。
说明
初始化方法initAliyunCaptcha除了在必要场景下（如初始化参数发生变化）外，不支持重复调用。初始化过程中如果返回失败，请参见客户端初始化报错说明进行排查。
```
<script type="text/javascript">
  var captcha;
  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 = {
        region: "cn",
        prefix: "{{IDENTITY}}",
      };
    </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;
      window.initAliyunCaptcha({
        SceneId: "{{SCENE_ID}}",  // 场景ID。根据步骤二新建验证场景后，您可以在验证码场景列表，获取该场景的场景ID
        mode: "popup",  // 验证码模式，popup表示弹出式，embed表示嵌入式。无需修改
        // 页面上预留的渲染验证码的元素，与原代码中预留的页面元素保持一致。
        element: "#captcha-element", 
        button: "#button",  // 触发验证码弹窗或无痕验证的元素ID
        // 验证码验证通过回调函数
        success: function (captchaVerifyParam) {
          // 入参为验签captchaVerifyParam
          // 1.向后端（即ESA）发起业务请求进行验证码验签captchaVerifyParam校验
          // 2.根据校验结果来进行业务处理
          // 3.如业务需要重新进行验证码验证，调用验证码初始化方法initAliyunCaptcha重新初始化验证码
          console.log('SUCCESS'); // 在控制台打印SUCCESS
        },
        // 验证码验证不通过回调函数
        fail: function (result) {
          // 入参为不通过信息
          // 正常验证有效期内不需要做任何操作，验证码自动刷新，重新进行验证
          console.error(result);
        },
        // 绑定验证码实例回调函数，该回调会在验证码初始化成功后调用
        getInstance: function (instance) {
          captcha = instance;
        },
        // 指定ESA的服务域名，您无需更改
        server: ['captcha-esa-open.aliyuncs.com', 'captcha-esa-open-b.aliyuncs.com'],
        // 滑块验证和一点即过的验证形态触发框体样式，支持自定义宽度和高度，单位为px。
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...其他参数，参考initAliyunCaptcha参数说明
      });
    </script>
  </body>
</html>

调用success: function (captchaVerifyParam)时，客户端会向ESA发起请求，需要携带验签参数captchaVerifyParam。captchaVerifyParam可放在请求参数中，也可以放在Header中，可参考以下两种示例：

验签参数为URI参数

async function captchaVerifyCallback(captchaVerifyParam) {
    // 1.向ESA发起业务请求，获取验证码验证结果和业务结果
    const result = await fetch('${业务验证URI（即在ESA平台验证码配置中的URI）}?captcha_verify_param=' + captchaVerifyParam, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json'},
        body: JSON.stringify({
            //个性化业务参数
            //BizParam:
        }),
        credentials: 'include'
    });
    const verify_code = result.headers.get('X-Captcha-Verify-Code')
    if (verify_code === 'T001') {
        alert('验证码验证通过！');
    } else {
        alert('验证码验证失败: ', verify_code)
    }
    captcha.refresh()
    const data = await result.json()
    return data
}

验签参数为header值

async function captchaVerifyCallback(captchaVerifyParam) {
    // 1.向ESA发起业务请求，获取验证码验证结果和业务结果
    const result = await fetch('${业务验证URI（即在ESA平台验证码配置中的URI）}', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'captcha-verify-param': captchaVerifyParam},
        body: JSON.stringify({
            BizParam: document.getElementById('biz_result').value
        }),
        credentials: 'include'
    });
    const verify_code = result.headers.get('X-Captcha-Verify-Code')
    if (verify_code === 'T001') {
        alert('验证码验证通过！');
    } else {
        alert('验证码验证失败: ', verify_code)
    }
    captcha.refresh()
    const data = await result.json()
    return data
}

实现效果：

Dec-29-2025 16-07-05

ESA服务端验签结果将在响应头中携带原因码x-captcha-verify-code，您的客户端可根据成功或失败结果做对应处理：

原因码Code	原因解释
T001	验证通过
F003	`CaptchaVerifyParam`解析错误
F005	场景ID（`SceneId`）不存在
F017	`VerifyToken`内容被修改
F018	验签数据重复使用
F019	验签超出时间限制（有效期90秒）或未发起验证就验签
F020	验签票据与场景ID或用户不匹配
F021	验证的`SceneId`和验签的`SceneId`不一致

相关参考

`AliyunCaptchaConfig`参数说明

参数

类型

是否必填

默认值

描述

region

String

支持

cn

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

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

验证码产品在中国内地（华东2（上海））和新加坡分别设置了管控中心平面，根据客户自行配置的调用参数，客户端采集的行为数据、设备数据等将回传对应中心处理，主要实现安全验证功能。

prefix

String

支持

无

验证码身份标识。

`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`	验证码支持的语言类型： `cn`：简体中文 `tw`：繁体中文 `en`：英文 `ar`：阿拉伯语 `de`：德语 `es`：西班牙语 `fr`：法语 `in`：印尼语 `it`：意大利语 `ja`：日语 `ko`：韩语 `pt`：葡萄牙文 `ru`：俄语 `ms`：马来西亚 `th`：泰语 `tr`：土耳其 `vi`：越南
timeout	Number	不支持	`5000`	验证码初始化请求单次请求超时时间，单位为毫秒。
rem	Number	不支持	`1`	对验证码UI进行整体缩放。请传入正数，如`0.5`是缩小一倍，`2`是放大一倍。 rem参数主要针对移动端浏览器使用。
onError	Function	不支持	无	验证码初始化接口请求和验证码资源加载失败、超时的错误回调函数。固定写法如下： `function onError(errorInfo) { const {code, msg} = errorInfo; console.log(code, msg); }`
onClose	Function	不支持	无	验证码弹窗关闭时触发的回调函数。
showErrorTip	Boolean	不支持	true	是否显示网络质量不佳时访问异常的错误提醒。
delayBeforeSuccess	Boolean	不支持	true	验证成功后，是否延迟1s触发`success`回调函数。

rem参数代码示例

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

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

无痕模式调用验证码说明

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

方法名	说明	示例	使用场景
show	显示验证码元素、蒙板。	`captcha.show()`	需要自动弹出（不需要点击按钮）验证码弹框时可以使用。
hide	隐藏或关闭验证码元素、蒙板。	`captcha.hide()`	需要自动关闭（不需要点击按钮）验证码弹框时可以使用。