VAPTCHA

验证流程

  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

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

    加载效果图:

    img

完整实例

获取实例

  • 点击式:

  • 隐藏式:

  • 嵌入式(企业版)

配置参数

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

通用参数

必填参数

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

type参数说明

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

可选参数

参数名类型默认值说明
lang字符串auto可选值,auto,zh-CN,en,zh-TW,jp
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协议回调方法 获取验证数据:
  1. 上面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://channel2.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

参数说明

参数说明类型
smsid短信账户 idstring
smskey短信账户 keystring
token由 vaptcha 验证码验证成功后返回的 tokenstring
data填入数据用于替换模板中的对应位置的变量string[]
countrycode国别码,如:‘86’string
phone手机号string
templateid模板 idstring

验证码代生成

请求短信验证码

VAPTCHA 提供了代生成短信验证码的接口,调用时,将对应变量替换成 "_vcode" 提交即可,如: 模板编号: 0, 短信签名: 【身份验证】, 模板内容: 验证码{变量},您正在进行{变量}身份验证,打死不要告诉别人哦! 请求(json 传参):

短信验证码验证接口

验证码有效期为 15 分钟,有效期内同一个验证码最多允许验证 3 次,请提交如下参数进行结果校验:

接口地址:https://sms.vaptcha.com/verify

返回码列表

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