验证流程

  1. 创建验证单元,获取VIDKey点击创建

  2. https://v.vaptcha.com/v3.js引入到你的页面。

  3. 将VAPTCHA初始化到你需要的位置,具体web端部署请查看:Web客户端部署

  4. 用户验证通过得到token,与表单数据一同提交到服务端。

  5. 服务端得到token后,向VAPTCHA服务器验证token的有效性,验证通过说明此次请求有效,服务端验证流程请查看:服务端二次验证

PC网页部署

web客户端部署VAPTCHA所需的配置和接口说明文档

环境

兼容性 IE8+(IE8及以上)、Chrome、Firefox、Safari、Opera、主流手机浏览器、iOS 及 Android上的内嵌Webview

安装

  1. 准备工作:创建验证单元,获取验证单元id(初始化验证码的必填参数)。

  2. 引入前端sdk:

  3. 初始化VAPTCHA

    • 使用初始化初始函数进行初始化,并调用验证示例加载验证按钮

      加载效果图:

完整实例

获取实例
  • 嵌入式:

  • 点击式:

  • 隐藏式:

配置参数

初始化验证码所需要的配置参数,vaptcha初始化函数的第一参数

通用参数

必填参数

参数名类型说明
vid字符串验证单元的VID
type字符串可选值click,embed,invisible
scene数值验证单元场景,默认 0
offline_server字符串离线模式地址(离线模式配置)

type参数说明

此参数决定了验证码的类型,不一样的类型也有不同的参数,对应的效果如下

可选参数

参数名类型默认值说明
lang字符串zh-CN可选值zh-CN,en,zh-TW
https布尔值true协议类型,是否为https
类型参数
适用类型参数名参数类型必填默认值说明
点击式、嵌入式containerElementselector
点击式style字符串dark按钮样式,可选dark,light
点击式color字符串#57ABFF按钮颜色

API方法

render

仅供点击式和嵌入式使用。执行初始化操作,将按钮或者图片插入到配置参数中的容器中去。示例代码如下:

listen

用于监听验证事件。支持的事件如下:

  • pass 事件,验证通过时触发

  • close 事件,关闭验证弹窗时触发

validate

仅供隐藏式使用。由开发者决定何时调用该方法进行验证,比如在表单提交时调用该方法。

使用方式: VAPTCHA实例初始化完成后,等到用户点击登录按钮时执行validate()方法,执行验证,验证成功后,触发验证通过事件

getToken

token的有效期为3分钟,验证通过后3分钟此接口返回空。建议用户根据token是否为空来判断验证码是否通过验证。

所有模式均可用,推荐使用此接口来获取验证结果。用于获取验证结果, 返回token,由于token只可使用一次,所以调用getResult接口获取token后,token将被置空。

推荐的用法:

renderTokenInput

如果你是以直接提交表单的方式发起请求,推荐使用此函数向表单添加token值

此函数用于向表单添加一个名为vaptcha_tokeninput标签,如下

函数有一个参,数默认值为参数配置中的container容器,使用隐藏式时为必填,input将添加到配置的容器中,参数类型为selector或者Element

示例代码:

reset

所有模式均可用。验证码重置操作,例如可在登录失败时调用。

示例代码:

 

iOS-HTML5部署

  1. 在您的iOS App工程的.h文件中,导入框架的依赖库。
  1. 在您(需要人机验证的地方)添加webview,把webview设置为隐藏.
  1. webViewconfiguration中的userContentController属性中添加js的messageHandlername为“signal”;
  1. 在需要使用时,把webview显示出来并加载业务页面和按照格式配置参数vidlangoffline_server
  1. 通过WKScriptMessageHandler协议回调方法 获取验证数据:

6.上面messagebody属性返回结果为字符串,这里的字符串参数返回了验证是否通过和用户点击关闭等信息,需要在这里实现用户验证通过、失败或者取消的后续操作,具体字段为

Android-HTML5部署

  1. AndroidManifest.xml配置文件中,设置网络连接权限的权限。
  1. 布局文件(需要人机验证的地方)添加webview,把webview设置为隐藏(android:visibility="invisible"),再使用时设置为显示(visible).
  1. activity文件中设置webview
  1. 首先调用setVaptcha()设置webview,然后再需要验证的地方调用以下方法

webview显示出来并加载业务页面和按照格式配置参数vidlangoffline_server

  1. 需要把webview设置为透明并关闭硬件加速
  1. 在建立JavaScript调用Java接口的桥梁的时候 在这里传过去的名字固定为vaptchaInterface

在接口里面需要实现固定名字为(signal)的方法,这里的字符串参数返回了验证是否通过和用户点击关闭等信息,需要在这里实现用户验证通过、失败或者取消的后续操作,具体字段为

服务端二次验证

服务端验证的接口与返回结果说明 服务端SDK地址:https://github.com/vaptcha

API请求数据

地址: http://0.vaptcha.com/verify

POST参数说明
id验证单元的VID
secretkey验证单元的Key
scene验证单元场景,e.g: 0
token客户端验证成功得到的token
ip获取用户的remote address

API响应结果

返回json字符串

错误消息说明

错误消息说明
id-emptyid为空
id-errorid错误
scene-error场景号错误
token-errortoken错误
token-expiredtoken过期,token三分钟有效期
over-user-limit超过VIP用户自定义的频率上限
bad-request请求错误

离线模式

此文档的示例代码使用Node.js,仅供参考,部分方法需用户自己实现,具体实现可根据实际情况作调整。离线模式为可选配置项,请根据需要自行配置。(离线模式原理

offline接口说明

用户服务器端应增加offline接口,此接口为jsonp类型, 接口地址以参数的形式传入前端验证码初始化函数中,进入离线模式后由sdk调用。

前端初始化示例代码:

接口参数

参数名参数类型说明
callbackstringjsonp回调函数名
offline_actionstring值为get获取验证图片,值为verify进行人机验证
vstring轨迹参数
knockstring流水号

get 获取图片操作

offline_actionget 时的操作 获取流程:

  1. 获取服务器离线 key

请求 http://channel.vaptcha.com/config/ + vid ,此接口返回json数据,格式

示例代码:

offline_state1表示进入离线模式。

  1. 生成随机数randomStr

从“0123456789abcdef”中取4位16进制数的字符串randomStr,示例代码:

  1. 生成验证图imgid

offline_keyrandomStrmd5值作为验证图的imgid,示例代码:

  1. 生成流水号knock

服务器端生成唯一字符串knock,用于标识本次验证操作,如:uuid ,自增数等,官方的示例操作是将字符串作为键,imgid作为值存入session中,示例代码

同一次验证多次请求图片,所以会带上上一次的knockget接口接受到参数knock后,不用再次生成knock,只需重新生成imgid 示例代码:

  1. 返回jsonp格式数据,code为返回码,0103表示获取成功,0104表示获取失败。

verify 手势验证操作

offline_actionverify 时的操作

用户在浏览器上完成人机验证后,前端sdk向offline_server接口发起验证请求。

验证流程:

  1. 生成手势验证validatekey

首先通过请求参数knock获取session中缓存的imgid,再取请求参数vimgidmd5值作为用于验证的validatekey,示例代码:

  1. 服务器端发起手势验证请求

请求地址 http://offline.vaptcha.com/,接口返回json数据,示例代码:

  1. 验证成功,返回token

验证成功后生成一个唯一的token,存在服务端用于提交表单的验证,并将token返回,同时清除chalengesession信息,示例代码:

  1. 返回验证结果,返回jsonp格式数据,正确返回:

服务器端验证token

前端完成验证提交表单数据时,将token一并提交,服务器端验证通过token内容判断用户验证操作是否有效,token只可验证一次,验证通过后应清除token。示例代码:

短信接口

接口说明 自定义短信模板调用接口。

方法: httppost

格式: json

接口地址:http://sms.vaptcha.com/send

参数说明

参数说明类型
id短信账户idstring
smskey短信账户keystring
token由vaptcha验证码验证成功后返回的tokenstring
data短信模板数据string[]
countrycode国别码,如:‘86’string
phone手机号string
templateid模板idstring

返回码列表

返回码详情
200成功
201发送失败
202用户验证失败/smskey不正确
203剩余短信条数不足
204发送频率过快,换号码或稍后再试
205token验证失败
206手机号码格式错误
207验证码格式错误
208验证次数上限
209验证码过期
210验证码不匹配
211模板数据错误
212模板编号错误
230系统维护