- 验证码申请
当前应用
应用名称: 网站验证码
产品域名: www.***.com
验证码 App ID
用于客户端接入验证码服务
App Secret Key
用于服务器端校验验证码票据的验证密钥，请妥善保密，请勿泄露给第三方。
- 客户端接入
a、在Head的标签内最后加入以下代码引入验证JS文件（建议直接在html中引入）
b、在你想要激活验证码的DOM元素（eg. button、div、span）内加入以下id及属性
<button id=“TencentCaptcha”
data-appid="***"
data-cbfn=“callback”
验证
c、为验证码创建回调函数，注意函数名要与data-cbfn相同
window.callback = function(res){
console.log(res)
// res（未通过验证）= {ret: 1, ticket: null}
// res（验证成功） = {ret: 0, ticket: “String”, randstr: “String”}
if(res.ret === 0){
alert(res.ticket) // 票据
}
}
完成以上操作后，点击激活验证码的元素，即可弹出验证码。
- 服务器接入
在验证完成后，客户端收到获得一个验证票据(ticket)。将票据上传至服务器，并发送GET请求到下方接口可以校验验证码的票据，判断当次验证是否成功。
URL: https://ssl.captcha.qq.com/ticket/verify
字段名 描述
aid (必填) ***
AppSecretKey (必填) *****
Ticket (必填) 验证码客户端验证回调的票据
Randstr (必填) 验证码客户端验证回调的随机串
UserIP (必填) 提交验证的用户的IP地址（eg: 10.127.10.2）
返回值
Json格式，eg：{response:1, evil_level:70, err_msg:""}
字段名 描述
response 1:验证成功，0:验证失败，100:AppSecretKey参数校验错误[required]
evil_level [0,100]，恶意等级[optional]
err_msg 验证错误信息[optional]，查看详细说明
至此，验证码接入已完成，如需对验证码进行定制请往下阅读详细配置，更多配置项可访问配置中心。
附：前后端调用时序图
定制接入
验证码会在全局注册一个TencentCaptcha类，业务方可以使用这个类自行初始化验证码，并对验证码进行显示或者隐藏。
默认的，验证码的js（TCaptcha.js）在加载完成后会检测页面中是否存在id="TencentCaptcha"的元素，如果有则会自动将验证码的触发事件绑定在该元素上。如不希望默认绑定请避免使用id="TencentCaptcha"的元素。
构造函数
TencentCaptcha支持多种参数的重载。
- 手动初始化
new TencentCaptcha(appId, callback, options);
参数说明：
appId：String, 申请的场景Id
callback：Function, 回调函数
options：Object, 更多配置参数, 详见配置参数 - 绑定到一个元素
new TencentCaptcha(element);
参数说明：
element: HTMLElement, 验证码将绑定click事件到该元素上。该方式需要确保元素上有data-appid和data-cbfn属性 - 绑定到一个元素
new TencentCaptcha(element, appId, callback, options);
参数说明：
element: HTMLElement, 需要绑定click事件的元素
appId: String, 申请的场景Id
callback: Function, 回调函数
options: Object, 更多配置参数, 详见配置参数
示例代码
// 直接生成一个验证码对象
var captcha1 = new TencentCaptcha(‘appid’, function(res) {/* callback */});
captcha1.show(); // 显示验证码
// 绑定一个元素并手动传入场景Id和回调
new TencentCaptcha(
document.getElementById(‘TencentCaptcha’),
‘appid’,
function(res) {/* callback */},
{ bizState: ‘自定义透传参数’ }
);
// 绑定一个元素并自动识别场景id和回调
// 验证码会读取dom上的data-appid和data-cbfn以及data-biz-state(可选)自动初始化
new TencentCaptcha(document.getElementById(‘TencentCaptcha’));
回调内容
前端验证成功会验证码会调用业务传入的回调函数，并在第一个参数中传入回调结果。结果字段说明如下：
字段名 值类型 说明
ret Int 验证结果，0-验证成功，2-用户主动关闭验证码
ticket String 验证成功的票据，当且仅当ret=0时ticket有值
appid String 场景Id
bizState Any 自定义透传参数
实例方法
TencentCaptcha的实例提供一些常用操作验证码的方法：
方法名 说明 传入参数 返回内容
show 显示验证码 无 无
destroy 隐藏验证码 无 无
getTicket 获取验证码验证成功后的ticket 无 Object:{“appid”:"",“ticket”:""}
- show与destroy可以反复调用
配置参数
options提供以下配置参数：
配置名 值类型 说明
bizState Any 自定义透传参数，业务可用该字段传递少量数据，该字段的内容会被带入callback回调的对象中
