- 验证码申请
 当前应用
 应用名称: 网站验证码
 产品域名: www.***.com
 验证码 App ID
 用于客户端接入验证码服务
App Secret Key
 用于服务器端校验验证码票据的验证密钥,请妥善保密,请勿泄露给第三方。
- 客户端接入
 a、在Head的标签内最后加入以下代码引入验证JS文件(建议直接在html中引入)
<script src="https://ssl.captcha.qq.com/TCaptcha.js"></script>
b、在你想要激活验证码的DOM元素(eg. button、div、span)内加入以下id及属性
<!--点击此元素会自动激活验证码-->
<!--id : 元素的id(必须)-->
<!--data-appid : AppID(必须)-->
<!--data-cbfn : 回调函数名(必须)-->
<!--data-biz-state : 业务自定义透传参数(可选)-->
<button id="TencentCaptcha"
data-appid="***"
data-cbfn="callback"
>验证</button>
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回调的对象中 | 
程序员交流qq群:782974737 










