前提条件
客户端接入前，需完成新建验证，并在验证列表获取所需的 CaptchaAppId 以及 AppSecretKey。步骤如下：
1. 登录 验证码控制台，左侧导航栏选择图形验证 > 验证管理，进入验证管理页面。
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://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js"></script></head><body><div id="cap_iframe"></div><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 本次验证的随机串，后续票据校验时需传递该参数。console.log('callback:', res);// res（用户主动关闭验证码）= {ret: 2, ticket: null}// res（验证成功） = {ret: 0, ticket: "String", randstr: "String"}// res（请求验证码发生错误，验证码自动返回terror_前缀的容灾票据） = {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 查看。\\n2. 打开浏览器控制台，查看完整返回结果。');}}// 定义验证码js加载错误处理函数function loadErrorCallback() {var appid = 'CaptchaAppId';// 生成容灾票据或自行做其它处理var ticket = 'terror_1001_' + appid + '_' + Math.floor(new Date().getTime() / 1000);callback({ret: 0,randstr: '@'+ Math.random().toString(36).substr(2),ticket,errorCode: 1001,errorMessage: 'jsload_error',});}// 定义验证码触发事件window.onload = function(){document.getElementById('CaptchaId').onclick = function(){try {// 生成一个验证码对象// CaptchaAppId：登录验证码控制台，从【验证管理】页面进行查看。如果未创建过验证，请先新建验证。//callback：定义的回调函数var captcha = new TencentCaptcha(document.getElementById('cap_iframe'), '你的验证码CaptchaAppId', callback, {});// 调用方法，显示验证码captcha.show();} catch (error) {// 加载异常，调用验证码js加载错误处理函数loadErrorCallback();}}}</script></html>
接入说明
步骤1：动态引入验证码 JS
Web 页面需动态引入验证码 JS，在业务需要验证时，唤起验证码进行验证。
<!-- 动态引入验证码JS示例 --><script src="https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js"></script>
注意：
必须动态引入验证码 JS。如通过其他手段规避动态加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。
步骤2：创建验证码对象
引入验证码 JS 后，验证码会在全局注册一个
TencentCaptcha类，业务方可以使用这个类自行初始化验证码，并对验证码进行显示或者隐藏。注意：
触发验证码的元素不要使用
id="TencentCaptcha"，TencentCaptcha 属于系统默认 id，不可使用。 构造函数
new TencentCaptcha(DOM, CaptchaAppId, callback, options);
参数说明
参数名 | 值类型 | 说明 |
DOM | Element Nodes | 承载 Robot 勾选框的容器。 |
CaptchaAppId | String | 注意：不可使用客户端类型为小程序的 CaptchaAppId，会导致数据统计错误。 |
callback | Function | |
options | Object |
callback 回调函数
验证结束后，会调用业务传入的回调函数，并在第一个参数中传入回调结果。回调结果字段说明如下：
字段名 | 值类型 | 说明 |
ret | Int | 验证结果，0：验证成功。2：用户主动关闭验证码。 |
ticket | String | 验证成功的票据，当且仅当 ret = 0 时 ticket 有值。 |
CaptchaAppId | String | 验证码应用 ID。 |
bizState | Any | 自定义透传参数。 |
randstr | String | 本次验证的随机串，后续票据校验时需传递该参数。 |
errorCode | Number | |
errorMessage | String | 错误信息。 |
回调函数 errorCode 说明
errorCode | 说明 |
1001 | TJNCaptcha-global.js 加载错误。 |
1002 | 调用 show 方法超时 |
1003 | 中间 js 加载超时 |
1004 | 中间 js 加载错误 |
1005 | 中间 js 运行错误 |
1006 | 拉取验证码配置错误/超时 |
1007 | iframe 加载超时 |
1008 | iframe 加载错误 |
1009 | jquery 加载错误 |
1010 | 滑块 js 加载错误 |
1011 | 滑块 js 运行错误 |
1012 | 刷新连续错误3次 |
1013 | 验证网络连续错误3次 |
options 外观配置参数
options 参数用于对验证码进行定制外观设置，默认可以设置为空。
注意：
验证码弹窗内部不支持调整样式大小，如果需要调整，可在弹窗最外层用
class=tcaptcha-transform 的元素设置 transform:scale();。验证码更新可能会改变元素的 id，class 等属性，请勿依赖其他验证码元素属性值覆盖样式。如果手机原生端有设置左右滑动手势，需在调用验证码 show 方法前禁用，验证完成后再打开，防止与验证码滑动事件冲突。
配置名 | 值类型 | 说明 |
bizState | Any | 自定义透传参数，业务可用该字段传递少量数据，该字段的内容会被带入 callback 回调的对象中。 |
enableDarkMode | Boolean/String | 开启自适应深夜模式或强制深夜模式。 开启自适应深夜模式: {"enableDarkMode": true} 强制深夜模式: {"enableDarkMode": 'force'} |
ready | Function | 验证码加载完成的回调，回调参数为验证码实际的宽高： {"sdkView": {<br>"width": number,<br>"height": number<br>}} 该参数仅为查看验证码宽高使用，请勿使用此参数直接设定宽高。 |
needFeedBack | String | 自定义帮助链接: {"needFeedBack": 'url地址' } |
loading | Boolean | 是否在验证码加载过程中显示loading框。不指定该参数时，默认显示 loading 框。 显示loading框: {"loading": true} 不显示loading框: {"loading": false} |
userLanguage | String | 指定验证码提示文案的语言，优先级高于控制台配置。 支持传入值同 navigator.language 用户首选语言，大小写不敏感。 |
userLanguage 配置参数
参数名 | 说明 |
zh-cn | 简体中文 |
zh-hk | 繁体中文（中国香港） |
zh-tw | 繁体中文（中国台湾） |
en | 英文 |
ar | 阿拉伯语 |
my | 缅甸语 |
fr | 法语 |
de | 德语 |
he | 希伯来语 |
hi | 印地语 |
id | 印尼语 |
it | 意大利语 |
ja | 日语 |
ko | 朝鲜语 |
lo | 老挝语 |
ms | 马来语 |
pl | 波兰语 |
pt | 葡萄牙语 |
ru | 俄语 |
es | 西班牙语 |
th | 泰语 |
tr | 土耳其语 |
vi | 越南语 |
步骤3：调用验证码实例方法
TencentCaptcha 的实例提供一些操作验证码的常用方法：
方法名 | 说明 | 传入参数 | 返回内容 |
show | 显示验证码，可以反复调用。 | 无 | 无 |
destroy | 隐藏验证码，可以反复调用。 | 无 | 无 |
getTicket | 获取验证成功后的 ticket。 | 无 | Object:{"CaptchaAppId":"","ticket":""} |
reload | 重新初始化勾选框，可以反复调用。 | 无 | 无 |
步骤4：容灾处理
为保障验证码 Captacha 服务端异常时不阻塞客户网站正常业务流程，建议参考如下方式接入验证码。
1. 定义 JS 加载错误处理函数。
// 错误处理函数作用：在JS加载或初始化错误时，保障事件流程正常// 函数定义需在script加载前function loadErrorCallback() {var appid = ''// 生成容灾票据或自行做其它处理var ticket = 'terror_1001_' + appid + Math.floor(new Date().getTime() / 1000);callback({ret: 0,randstr: '@'+ Math.random().toString(36).substr(2),ticket,errorCode: 1001,errorMessage: 'jsload_error',});}
2. 调用验证码实例 catch 到错误时，调用 JS 加载错误处理函数。
try {// 生成一个验证码对象var captcha = new TencentCaptcha(document.getElementById('cap_iframe'), '你的验证码CaptchaAppId', callback, {});// 调用方法，显示验证码captcha.show();} catch (error) {// 加载异常，调用验证码js加载错误处理函数loadErrorCallback();}
3. 定义验证码 callback 回调函数时，根据 ticket 和 errorCode （而非 ret）的情况做处理。errorCode 的定义参考步骤2中"回调函数 errorCode 说明"。
function callback(res) {// res（用户主动关闭验证码）= {ret: 2, ticket: null}// res（验证成功） = {ret: 0, ticket: "String", randstr: "String"}// res（请求错误，返回terror_前缀的容灾票据） = {ret: 0, ticket: "String", randstr: "String", errorCode: Number, errorMessage: "String"}if (res.ticket){//根据errorCode情况做特殊处理if(res.errorCode === xxxxx){//自定义容灾逻辑（例如跳过这次验证）}}}
注意：
是
否
本页内容是否解决了您的问题？