如何将验证码1.0升级到2.0

更新时间:

本文将为您介绍如何将已集成的阿里云验证码1.0平滑升级到验证码2.0,提升安全性和用户体验。

前提条件

客户端升级步骤

说明

完整验证码2.0客户端代码请参见WebH5客户端V3架构接入

资源引入替换

  1. 删除验证码1.0JS资源引用代码

    <script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>
  2. HTMLhead标签中添加全局变量配置,并动态引入验证码2.0JS资源

    <script>
      window.AliyunCaptchaConfig = {
        // 必填,验证码示例所属地区,支持中国内地(cn)、新加坡(sgp)
        region: "cn",
        // 必填,身份标。开通阿里云验证码2.0后,您可以在控制台概览页面的实例基本信息卡片区域,获取身份标
        prefix: "xxxxxx",
      };
    </script>
    <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"></script>

初始化代码升级

验证码1.0初始化代码示例(旧)

<div id="nc"></div>
<script>
  // 实例化nc
  AWSC.use("nc", function (state, module) {
    // 初始化
    window.nc = module.init({
      // 应用类型标识。它和使用场景标识(scene字段)一起决定了滑动验证的业务场景与后端对应使用的策略模型。您可以在阿里云验证码控制台的配置管理页签找到对应的appkey字段值,请务必正确填写。
      appkey: "CF_APP_1",
      //使用场景标识。它和应用类型标识(appkey字段)一起决定了滑动验证的业务场景与后端对应使用的策略模型。您可以在阿里云验证码控制台的配置管理页签找到对应的scene值,请务必正确填写。
      scene: "register",
      // 声明滑动验证需要渲染的目标ID。
      renderTo: "nc",
      //前端滑动验证通过时会触发该回调参数。您可以在该回调参数中将会话ID(sessionId)、签名串(sig)、请求唯一标识(token)字段记录下来,随业务请求一同发送至您的服务端调用验签。
      success: function (data) {
        window.console && console.log(data.sessionId);
        window.console && console.log(data.sig);
        window.console && console.log(data.token);
      },
      // 滑动验证失败时触发该回调参数。
      fail: function (failCode) {
        window.console && console.log(failCode);
      },
      // 验证码加载出现异常时触发该回调参数。
      error: function (errorCode) {
        window.console && console.log(errorCode);
      },
    });
  });
</script>

验证码2.0初始化代码示例(新)

<div id="captcha-element"></div>
<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>

参数映射对照表

验证码1.0参数

验证码2.0对应参数

验证码2.0参数说明

appkey

prefix

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

scene

SceneId

验证码场景ID,新建验证场景后可获取该值。image

renderTo

element

渲染容器选择器。

success

success

验证通过回调函数。

fail

fail

验证失败回调函数。

error

onError

验证码加载出现异常时触发该回调参数。验证码2.0中在初始化接口请求和验证码资源加载失败、超时触发该回调。

foreign

region

地域配置,验证码2.0中通过全局变量AliyunCaptchaConfig.region设置。

width

slideStyle

滑块宽度,验证码2.0中建议最小值320px,通过slideStyle对象配置。

服务端升级步骤

推荐您使用SDK集成的方式接入验证码2.0,具体操作,请参见下载并安装SDK

调用API对照表

验证码1.0接口

验证码2.0接口

AuthenticateSig :滑动验证和智能验证服务端调用接口。

统一调用VerifyIntelligentCaptcha接口,不区分形态。

AnalyzeNvc:无痕验证服务端调用接口。

入参对照表

验证码1.0入参

验证码2.0入参

名称

描述

示例值

名称

描述

示例值

Token

请求唯一标识。您可以从前端sucess回调中获取,更多信息,请参见前端接入代码示例前端接入代码集成

123e4567-e89b-12d3-a456-426655440000

CaptchaVerifyParam

由验证码脚本回调的验证参数,直接将全部参数信息由客户端传给服务端即可。

eyJjZXxxxxxxxxxxxxxxnVlfQ==

Sig

签名串。您可以从前端successs回调中获取,更多信息,请参见前端接入代码示例前端接入代码集成

1

SessionId

会话ID。您可以从前端success回调中获取,更多信息,请参见前端接入代码示例前端接入代码集成

3D13211111111

Scene

使用场景标识,与前端页面填写数据一致。在统计报表中将根据该字段的内容进行分类展示。

Scene

SceneId

由您服务端写入本次验证对应的场景ID,建议传入,尤其在多场景下,防止前端被篡改为其他场景。

Udw***d72

AppKey

阿里云验证码配置对应的Appkey。

CF_APP_1

/

RemoteIp

客户端IP。

192.168.XX.XX

返回信息对比

验证码1.0返回信息

名称

类型

描述

示例值

RequestId

string

请求ID。

B0AEA6F4-14B3-5B94-8E8B-04889C1C1336

Msg

string

调用返回信息。

pass_1

Code

string

阿里云验证码结果编码,取值:

  • 100:表示验证通过。

  • 900:表示验证不通过。

100

验证码2.0返回信息

名称

类型

描述

HTTP Status Code

Integer

HTTP状态码。更多信息,请参见返回参数说明

HTTP Body

RequestId

String

请求ID。

Success

Boolean

请求是否成功。

  • true:表示请求成功。

  • false:表示请求失败。

Code

String

返回码。更多信息,请参见返回参数说明

Message

String

返回详细信息。更多信息,请参见返回参数说明

Result

VerifyResult

Boolean

验证结果。

  • true:表示验证通过。

  • false:表示验证不通过。

VerifyCode

String

T001

服务端校验通过。

T005

控制台开启测试模式,且配置了验证通过。如有疑问,请登录验证码2.0控制台查看对应场景的策略状态的配置。具体操作请参见接入指引

F001

疑似攻击请求,风险策略不通过。如有疑问,您可以提交工单进行排查。

F002

您传入的CaptchaVerifyParam参数为空,CaptchaVerifyParam是由前端自动获取并传给您的服务端,服务端不能做任何更改,直接传给阿里云。请参考发起认证请求检查您的集成代码。

F003

您传入的CaptchaVerifyParam格式不合法,CaptchaVerifyParam是由前端自动获取并传给您的服务端,服务端不能做任何更改,直接传给阿里云。请参考发起认证请求检查您的集成代码。

F004

控制台开启测试模式,且配置了验证不通过。如有疑问,请登录验证码2.0控制台查看对应场景的策略状态配置。具体操作请参见场景管理

F005

CaptchaVerifyParam中的场景ID(sceneId)不合法,CaptchaVerifyParam是由前端自动获取并传给您的服务端,服务端不能做任何更改,直接传给阿里云。请参考发起认证请求检查您的集成代码。

F006

CaptchaVerifyParam中的场景ID(sceneId)不合法,前端集成需要传入您账户创建的场景ID,请登录验证码2.0控制台查看场景配置。

F008

验证数据重复提交。同一笔验证码请求只允许提交一次。

F009

检测到虚拟设备环境,请检查是否使用vmware、virtualbox、hyper-v、parallels等虚拟机,avd、blue stacks、vbox/hyper-v等模拟器,桌面浏览器模拟移动设备等。如不需要拦截,请登录验证码2.0控制台自定义策略中关闭,具体操作请参见设置自定义策略

F010

IP访问频率超出限制。如果需要自定义频率阈值,请登录验证码2.0控制台自定义策略进行配置,具体操作请参见设置自定义策略

F011

同设备访问频率超出限制。如果需要自定义频率阈值,请登录验证码2.0控制台自定义策略进行配置,具体操作请参见设置自定义策略

F012

您服务端参数里传入的SceneID需要与前端配置的场景ID(SceneId)保持一致。

F013

您传入的CaptchaVerifyParam缺少参数,CaptchaVerifyParam是由前端自动获取并传给您的服务端,服务端不能做任何更改,直接传给阿里云。请参考发起认证请求检查您的集成代码。

F014

无初始化记录,可能存在两种原因:

  • 验证请求和初始化请求间隔超出20分钟时间,后端会删除初始化记录,请重新发起初始化请求进行尝试。

  • 不存在初始化记录,疑似攻击请求,或者接入异常,发起验证请求前需先发起客户端初始化请求。

F015

验证交互不通过。例如拼图没有滑动到正确位置,可以刷新验证码重新完成交互。

F016

控制台自定义策略配置URL验证导致不通过,请登录验证码2.0控制台自定义策略中URL验证策略进行调整,具体操作请参见设置自定义策略

F017

疑似攻击请求,协议或参数异常不通过。

F018

V3架构下,业务验签请求入参CaptchaVerifyParam重复使用。

F019

V3架构下,行为验证请求和业务验签请求间隔超出90秒或未发起行为验证就直接进行业务验签请求。

F020

V3架构下,业务验签请求的CaptchaVerifyParam与场景ID或用户不匹配。

返回参数HTTP Status CodeCodeMessage的详细说明,如下表所示。

HTTP Status Code

Code

Message

200

Success

成功。

400

MissingParameter

缺少必须参数。

401

InvalidParameter

参数不合法。

403

Forbidden.AccountAccessDenied

无权限,可能是未开通服务,或已欠费。

403

Forbidden.RAMUserAccessDenied

RAM用户无权限,请授权 AliyunYundunAFSFullAccess。具体操作,请参见RAM角色授权

500

InternalError

系统内部错误,建议重试。如果仍然报错,请提交工单联系我们。

测试说明

在将前端接入代码集成至Web页面后,建议您在正式上线前进行充分测试。对于客户端接入测试,可以参考接入验证进行验证;对于验证通过/不通过的测试,可使用验证码2.0场景管理中的测试模式功能进行测试验证。image

升级后验证清单

  1. 前端组件渲染:确认验证码弹出式/嵌入式组件正常显示,交互无异常。

  2. 回调函数触发:验证通过或失败时,successfail回调正确返回参数。

  3. 风险策略验证:模拟异常行为(如快速滑动、重复提交),确认拦截机制生效。

  4. 服务端结果返回符合预期。

通过以上步骤,可完成从阿里云验证码1.02.0的平滑升级,享受验证码2.0在验证形态、安全防护、性能优化上的升级能力。