如何将验证码1.0升级到2.0-验证码(Captcha)-阿里云帮助中心

前提条件

已开通阿里云验证码2.0服务。
已新建场景管理。

客户端升级步骤

说明

资源引入替换

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

<script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>

在HTML的head标签中添加全局变量配置，并动态引入验证码2.0的JS资源

<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后，可获取该值。在验证码服务概览页面右侧，身份标识字段对应的值即为 appkey 前缀信息。
scene	SceneId	验证码场景ID，新建验证场景后可获取该值。登录验证码服务控制台，在场景管理页面的场景列表中，场景名称/ID列下方显示的数字即为SceneId参数值。
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：无痕验证服务端调用接口。	统一调用VerifyIntelligentCaptcha接口，不区分形态。

入参对照表

验证码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 Code、Code、Message的详细说明，如下表所示。

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场景管理中的测试模式功能进行测试验证。在验证码场景编辑页面中，策略状态区域可选择正式或测试模式。选择测试后，通过下拉菜单指定测试结果为验证通过或验证不通过。

升级后验证清单

前端组件渲染：确认验证码弹出式/嵌入式组件正常显示，交互无异常。
回调函数触发：验证通过或失败时，success或fail回调正确返回参数。
风险策略验证：模拟异常行为（如快速滑动、重复提交），确认拦截机制生效。
服务端结果返回符合预期。

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