验证码 App 客户端接入

一、前提条件

2. 单击创建验证码，根据业务场景需求，设置验证名称、客户端类型、验证方式等参数。

3. 单击确定，完成新建验证，即可在验证列表中查看验证码 CaptchaAppId 及 AppSecretKey。

二、代码示例

以下代码示例，单击验证，激活验证码，并弹窗展示验证结果。

注意：该示例未展示调用票据校验 API 的逻辑。业务客户端完成验证码接入后，业务服务端需二次核查验证码票据结果（未接入票据校验，会导致黑产轻易伪造验证结果，失去验证码人机对抗效果），详情请参见：接入票据校验（Web 及 App）。

<!doctype html><html lang="en"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Web 前端接入示例</title> <!– 验证码程序依赖(必须)。请勿修改以下程序依赖，如通过其他手段规避加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。 –> <script src="https://turing.captcha.qcloud.com/TJCaptcha.js"></script> </head> <body> <button id="CaptchaId" type="button">验证</button> </body> <script> // 定义回调函数 function callback(res) { // 第一个参数传入回调结果，结果如下： // ret Int 验证结果，0：验证成功。2：用户主动关闭验证码。 // ticket String 验证成功的票据，当且仅当 ret = 0 时 ticket 有值。 // CaptchaAppId String 验证码应用ID。 // bizState Any 自定义透传参数。 // randstr String 本次验证的随机串，后续票据校验时需传递该参数。 // verifyDuration Int 验证码校验接口耗时（ms）。 // actionDuration Int 操作校验成功耗时（用户动作+校验完成）(ms)。 // sid String 链路sid。 console.log('callback:', res); // res（用户主动关闭验证码）= {ret: 2, ticket: null} // res（验证成功） = {ret: 0, ticket: "String", randstr: "String"} // res（请求验证码发生错误，验证码自动返回trerror_前缀的容灾票据） = {ret: 0, ticket: "String", randstr: "String", errorCode: Number, errorMessage: "String"} // 此处代码仅为验证结果的展示示例，真实业务接入，建议基于ticket和errorCode情况做不同的业务处理 if (res.ret === 0) { // 复制结果至剪切板 var str = '【randstr】->【' + res.randstr + '】 【ticket】->【' + res.ticket + '】'; var ipt = document.createElement('input'); ipt.value = str; document.body.appendChild(ipt); ipt.select(); document.execCommand('Copy'); document.body.removeChild(ipt); alert('1. 返回结果（randstr、ticket）已复制到剪切板，ctrl+v 查看。2. 打开浏览器控制台，查看完整返回结果。'); } } // 定义验证码js加载错误处理函数 function loadErrorCallback() { var appid = '你的CaptchaAppId'; // 生成容灾票据或自行做其它处理 var ticket = 'trerror_1001_' + appid + '_' + Math.floor(new Date().getTime() / 1000); callback({ ret: 0, randstr: '@' + Math.random().toString(36).substr(2), ticket: ticket, errorCode: 1001, errorMessage: 'jsload_error', }); } // 定义验证码触发事件 window.onload = function () { document.getElementById('CaptchaId').onclick = function () { try { // 生成一个验证码对象 // CaptchaAppId：登录验证码控制台，从【验证管理】页面进行查看。如果未创建过验证，请先新建验证。注意：不可使用客户端类型为小程序的CaptchaAppId，会导致数据统计错误。 //callback：定义的回调函数 var captcha = new TencentCaptcha('你的验证码CaptchaAppId', callback, { userLanguage: 'zh-cn', showFn: (ret) => { const { duration, // 验证码渲染完成的耗时(ms) sid, // 链路sid } = ret; }, verifyFn: (data) => { // 校验结果+sid 回调函数 const { pass, sid } = data; // pass: true 校验通过, false 校验未通过 // sid: 此次校验的sid }, }); // 调用方法，显示验证码 captcha.show(); } catch (error) { // 加载异常，调用验证码js加载错误处理函数 loadErrorCallback(); } }; }; </script></html>

三、步骤1：动态引入验证码 JS

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

<!– 动态引入验证码JS示例 –><script src="https://turing.captcha.qcloud.com/TJCaptcha.js"></script>

注意：必须动态引入验证码 JS。如通过其他手段规避动态加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。

注意：如果使用验证码1.0，请将 JS 地址改为 https://turing.captcha.qcloud.com/TCaptcha.js，其他无需变更。

四、步骤2：创建验证码对象

引入验证码 JS 后，验证码会在全局注册一个TencentCaptcha类，业务方可以使用这个类自行初始化验证码，并对验证码进行显示或者隐藏。

注意：触发验证码的元素请勿使用id="TencentCaptcha"，TencentCaptcha 属于系统默认 id，用来兼容验证码旧接入方式。

五、构造函数

new TencentCaptcha(CaptchaAppId, callback, options);

参数说明

六、callback 回调函数

验证结束后，会调用业务传入的回调函数，并在第一个参数中传入回调结果。回调结果字段说明如下：

回调函数 errorCode 说明

七、options 外观配置参数

options 参数用于对验证码进行定制外观设置，默认可以设置为空。

注意：.tcaptcha-transform{
transform: scale(0.9);
}

嵌入式验证码参数配置示例

<!doctype html><html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>验证码-内嵌接入</title> <script src="https://turing.captcha.qcloud.com/TJCaptcha.js"></script> </head> <body> <!– 验证码指定的内嵌容器 可自定义到任何位置 –> <div id="targetEmbed"></div> <script> function globalCallback(res) { console.log('captcha success', res); } function errorCallback(res) { console.log('errorCallback', res); } window.onload = function () { try { const captcha = new TencentCaptcha(document.getElementById('targetEmbed'), '用户CaptchaAppid', globalCallback, { type: 'embed', }); captcha.show(); } catch (error) { console.log('error', error); errorCallback(error); } }; </script> </body></html>

userLanguage 配置参数（除滑动拼图验证外，其他验证形式只支持中英文）

八、步骤3：调用验证码实例方法

TencentCaptcha 的实例提供一些操作验证码的常用方法：

九、步骤4：容灾处理

为保障验证码 Captcha 服务端异常时不阻塞客户网站正常业务流程，建议参考如下方式接入验证码。

1. 定义错误处理函数。

// 错误处理函数作用：在脚本加载或初始化错误时，保障事件流程正常// 函数定义需在script加载前function loadErrorCallback() { var appid = '' // 生成容灾票据或自行做其它处理 var ticket = 'trerror_1001_' + appid + Math.floor(new Date().getTime() / 1000); callback({ ret: 0, randstr: '@'+ Math.random().toString(36).substr(2), ticket:ticket, errorCode: 1001, errorMessage: 'jsload_error', });}

2. 验证码返回错误时，调用错误处理函数。

try { // 生成一个验证码对象 var captcha = new TencentCaptcha('你的验证码CaptchaAppId', callback, {}); // 调用方法，显示验证码 captcha.show(); } catch (error) { // 加载异常，调用验证码js加载错误处理函数 loadErrorCallback();}

3. 回调函数根据 ticket 和 errorCode （而非 ret）的情况做处理。

function callback(res) { // res（用户主动关闭验证码）= {ret: 2, ticket: null} // res（验证成功） = {ret: 0, ticket: "String", randstr: "String"} // res（请求错误，返回trerror_前缀的容灾票据） = {ret: 0, ticket: "String", randstr: "String", errorCode: Number, errorMessage: "String"} if (res.ticket){ //根据errorCode情况做特殊处理 if(res.errorCode === xxxxx){ //自定义容灾逻辑（例如跳过这次验证） } }}

完整容灾方案，详情请见业务容灾方案。

注意：业务客户端完成验证码接入后，服务端需二次核查验证码票据结果（未接入票据校验，会导致黑产轻易伪造验证结果，失去验证码人机对抗效果），详情请参见：接入票据校验（Web 及 App）。

十、步骤5：CaptchaAppid 鉴权

CaptchaAppid 鉴权通过前端传递加密符（aidEncrypted 参数），可有效防止因 CaptchaAppid 泄露导致的资源盗刷风险。详情参见 验证码 CaptchaAppid 鉴权升级指引。

十一、React 架构接入示例

1. 在 HTML 模板文件中引入验证码 JS。

<!– 验证码程序依赖(必须)。请勿修改以下程序依赖，如使用本地缓存，或通过其他手段规避加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。 –><script src="https://turing.captcha.qcloud.com/TJCaptcha.js"></script>

2. 调用验证码。

import React from 'react';import logo from './logo.svg';import './App.css';interface ICaptchaResult { ret: number; ticket: string; randstr: string; CaptchaAppId?: string; bizState?: string; errorCode?: number; errorMessage?: string;}function App() { // 定义回调函数 function callback(res: ICaptchaResult) { // 第一个参数传入回调结果，结果如下： // ret Int 验证结果，0：验证成功。2：用户主动关闭验证码。 // ticket String 验证成功的票据，当且仅当 ret = 0 时 ticket 有值。 // CaptchaAppId String 验证码应用ID。 // bizState Any 自定义透传参数。 // randstr String 本次验证的随机串，后续票据校验时需传递该参数。 console.log('callback:', res); // res（用户主动关闭验证码）= {ret: 2, ticket: null} // res（验证成功） = {ret: 0, ticket: "String", randstr: "String"} // res（请求验证码发生错误，验证码自动返回trerror_前缀的容灾票据） = {ret: 0, ticket: "String", randstr: "String", errorCode: Number, errorMessage: "String"} // 此处代码仅为验证结果的展示示例，真实业务接入，建议基于ticket和errorCode情况做不同的业务处理 if (res.ret === 0) { // 复制结果至剪切板 var str = '【randstr】->【' + res.randstr + '】 【ticket】->【' + res.ticket + '】'; var ipt = document.createElement('input'); ipt.value = str; document.body.appendChild(ipt); ipt.select(); document.execCommand('Copy'); document.body.removeChild(ipt); alert('1. 返回结果（randstr、ticket）已复制到剪切板，ctrl+v 查看。 2. 打开浏览器控制台，查看完整返回结果。'); } } // 定义验证码js加载错误处理函数 function loadErrorCallback() { var appid = '你的CaptchaAppId'; // 生成容灾票据或自行做其它处理 var ticket = 'trerror_1001_' + appid + '_' + Math.floor(new Date().getTime() / 1000); callback({ ret: 0, randstr: '@' + Math.random().toString(36).substr(2), ticket: ticket, errorCode: 1001, errorMessage: 'jsload_error', }); } function onCaptchaShow() { try { // 生成一个验证码对象 // CaptchaAppId：登录验证码控制台，从【验证管理】页面进行查看。如果未创建过验证，请先新建验证。注意：不可使用客户端类型为小程序的CaptchaAppId，会导致数据统计错误。 // callback：定义的回调函数 const captcha = new TencentCaptcha('你的CaptchaAppId', callback, {}); // 调用方法，显示验证码 captcha.show(); } catch (error) { // 加载异常，调用验证码js加载错误处理函数 loadErrorCallback(); } } return ( <div className='App'> <button className='captcha-btn' onClick={onCaptchaShow}> 弹出验证码 </button> </div> );}export default App;

十二、常见问题

详情参见 接入相关问题。

十三、更多信息

你可以登录 验证码控制台，在页面右下角单击快速咨询，了解更多详细信息。