| 日期 | 版本 | 修订内容摘要 |
|---|
| 2023-08-18 | v2.0.0 | 更新接口文档 |
1、注册激活产品
2、接入说明
步骤 1：动态引入验证码 JS
Web 页面需动态引入验证码 JS，在业务需要验证时，唤起验证码进行验证。
<script src="https://captcha.253.com/TCaptcha.js"></script>
注意：
必须动态引入验证码 JS。如使用本地缓存，或通过其他手段规避动态加载，会导致验证码无法正常更新，对抗能力无法保证，甚至引起误拦截。
3、代码示例
以下代码示例，单击验证，激活验证码，并弹窗展示验证结果。
<!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://captcha.253.com/TCaptcha.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 本次验证的随机串，后续票据校验时需传递该参数。
console.log('callback:', res);
}
//初始化对象
var captcha = new TencentCaptcha('你的验证码CaptchaAppId', callback, {});
// 定义验证码触发事件
document.getElementById('CaptchaId').onclick = function(){
captcha.show();
}
</script>
</html>
4、创建验证码对象
引入验证码 JS 后，验证码会在全局注册一个 TencentCaptcha 类，业务方可以使用这个类自行初始化验证码，并对验证码进行显示或者隐藏。
构造函数
new TencentCaptcha(CaptchaAppId, callback, options);
参数说明
| 参数名 | 值类型 | 说明 |
|---|
| CaptchaAppId | String | 验证码 CaptchaAppId 如果未创建过验证，请先新建验证。 注意：不可使用客户端类型为小程序的 CaptchaAppId，会导致数据统计错误。 |
| callback | Function | 验证码回调函数，详情请参见 callback 回调函数。 |
| options | Object | 验证码外观配置参数, 详情请参见 options 外观配置参数。 |
callback 回调函数
验证结束后，会调用业务传入的回调函数，并在第一个参数中传入回调结果。回调结果字段说明如下：
| 字段名 | 值类型 | 说明 |
|---|
| ret | Int | 验证结果，0：验证成功。2：用户主动关闭验证码。 |
| ticket | String | 验证成功的票据，当且仅当 ret = 0 时 ticket 有值。 |
| CaptchaAppId | String | 验证码应用 ID。 |
| bizState | Any | 自定义透传参数。 |
| randstr | String | 本次验证的随机串，后续票据校验时需传递该参数。 |
| errorCode | Number | 错误 code ，详情请参见 回调函数 errorCode 说明。 |
| errorMessage | String | 错误信息。 |
回调函数 errorCode 说明
| errorCode | 说明 |
|---|
| 1001 | TCaptcha.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 参数用于对验证码进行定制外观设置，默认可以设置为空。
*注意：
1、验证码弹窗内部不支持调整样式大小，如果需要调整，可在弹窗最外层用 class=tcaptcha-transform 的元素设置 transform:scale();。验证码更新可能会改变元素的 id，class 等属性，请勿依赖其他验证码元素属性值覆盖样式。
2、如果手机原生端有设置左右滑动手势，需在调用验证码 show 方法前禁用，验证完成后再打开，防止与验证码滑动事件冲突。
| 配置名 | 值类型 | 说明 |
|---|
| bizState | Any | 自定义透传参数，业务可用该字段传递少量数据，该字段的内容会被带入 callback 回调的对象中。 |
| enableDarkMode | Boolean | String | 开启自适应深夜模式: {"enableDarkMode": true} 强制深夜模式: {"enableDarkMode": 'force'} |
| sdkOpts | Object | 示例 {"width": 140, "height": 140} 仅支持移动端原生 webview 调用时传入，用来设置验证码 loading 加载弹窗的大小（注意，并非验证码弹窗大小）。 |
| ready | Function | 验证码加载完成的回调，回调参数为验证码实际的宽高： {"sdkView": { "width": number, "height": number }} 该参数仅为查看验证码宽高使用，请勿使用此参数直接设定宽高。 |
| needFeedBack | Boolean | String | 隐藏帮助按钮或自定义帮助按钮链接。 隐藏帮助按钮: {"needFeedBack": false } 自定义帮助链接: {"needFeedBack": 'url 地址' } |
| userLanguage | String | 指定验证码提示文案的语言，优先级高于控制台配置。 支持传入值同 navigator.language 用户首选语言，大小写不敏感。 详情参见 userLanguage 配置参数。 |
| type | String | 定义验证码展示方式。popup（默认）弹出式，以浮层形式居中弹出展示验证码。embed 嵌入式，以嵌入指定容器元素中的方式展示验证码。 |
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 | 越南语 |
5、调用验证码实例方法
TencentCaptcha 的实例提供一些操作验证码的常用方法：
| 方法名 | 说明 | 传入参数 | 返回内容 |
|---|
| show | 显示验证码，可以反复调用。 | 无 | 无 |
| destroy | 隐藏验证码，可以反复调用。 | 无 | 无 |
| getTicket | 获取验证成功后的 ticket。 | 无 | Object:{"CaptchaAppId":"","ticket":""} |
没有更多了
