API

VAPTCHA

验证流程

  1. 创建验证单元,获取VIDKey点击创建
  2. https://v-cn.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(初始化 VAPTCHA 的必填参数)。

  2. 引入前端 sdk:

    请选择就近资源地址或者直接将v3.JS下载到本地使用

  3. 初始化 VAPTCHA

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

    加载效果图:

    img

完整实例

获取实例

  • 点击式:

  • 隐藏式:

    重要: 请在页面加载完成时执行初始化函数,通过按钮触发 validate()方法,不要在按钮的点击事件中执行初始化函数,否则会导致在移动端无法正常验证。

  • 嵌入式

配置参数

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

通用参数

必填参数

参数名类型说明
vid字符串验证单元的VID
type字符串可选值click,invisible
scene数值验证单元场景,默认 0

type参数说明

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

可选参数

参数名类型默认值说明
lang字符串auto可选值,auto,zh-CN,en,zh-TW,jp
https布尔值true协议类型,是否为 https
area字符串cn验证节点区域,默认 cn,可选值 sea(东南亚),na(北美),cn(中国大陆),auto(根据用户区域自动匹配就近节点)

类型参数

适用类型参数名参数类型必填默认值说明
点击式containerElementselector
点击式style字符串dark按钮样式,可选dark,light
点击式color字符串#57ABFF按钮颜色
嵌入式guide布尔值布尔值是否在嵌入式图片底部显示操作提示文字,默认 显示

API 方法

render

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

listen

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

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

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

validate

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

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

getServerToken

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

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

推荐的用法:

renderTokenInput

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

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

函数接收一个参数作为存放input标签的容器,默认值为参数配置中的containe容器,使用隐藏式时为必填,input将添加到配置的容器中,参数类型为selector或者Element

示例代码:

reset

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

示例代码:

iOS-HTML5 部署

  1. 在您的 iOS App 工程的.h 文件中,导入框架的依赖库。
  1. 在您(需要人机验证的地方)添加webview,把webview设置为隐藏.
  1. webViewconfiguration中的userContentController属性中添加 js 的messageHandlername为“signal”;
  1. 在需要使用时,把webview显示出来并加载业务页面和按照格式配置参数vidlang
  1. 通过WKScriptMessageHandler协议回调方法 获取验证数据:
  1. 上面messagebody属性返回结果为字符串,这里的字符串参数返回了验证是否通过和用户点击关闭等信息,需要在这里实现用户验证通过、失败或者取消的后续操作,具体字段为

Android-HTML5 部署

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

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

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

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

后端代码部署

服务端二次验证

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

请求数据

地址: 前端验证成功后获取的 server 参数, 如 https://*.vaptcha.net/verify

注:服务器端请增加 *.vaptcha.com 和 *.vaptcha.net 白名单

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

响应结果

返回json字符串

错误消息说明

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

 

V-SMS

V-SMS短信接口不仅有非常高的到达率,而且对价格进行了补贴,远低于市场价。

 

短信接口

 

接口说明

 

参数说明

参数类型说明
smsidstring短信账户 id
smskeystring短信账户 key
tokenstringVAPTCHA 验证成功返回的token,不带则没有价格补贴
datastring[]填入数据用于替换模板中的对应位置的变量
countrycodestring国别码,如:‘86’
phonestring手机号
templateidstring模板 id

 

验证码代生成

如果你不想自己写短信验证码的校验逻辑,也可以交由 V-SMS 代为处理。

请求验证码

调用时,将对应变量替换成 "_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验证失败

 

设备校验

接口文档

通过 VAPTCHA 智能人机验证对用户的常用设备进行登记和校验,最多为每个用户登记 5 台设备,PC/移动端均支持。可用于免密登录、安全补充验证或站长自定义的其它场景。

URL:https://user.vaptcha.com/api/v1/device

备注:校验中使用的 VAPTCHA Token 需要二次验证成功后才能使用

 

设备查询

通过用户 ID 与 Token 查询该用户设备是否已登记,返回登录次数与最近登录时间。

Method:GET

Request:

参数参数类型require描述
idstringY用户唯一 ID,用于关联设备,无需提交用户名、手机号等隐私信息。
tokenstringYVAPTCHA 验证 Token

Response:

设备登记

为当前用户添加关联设备,最多不超过 5 台,是否登记设备可由站长决定或让 VAPTCHA 自动判断。建议仅登记经过有效身份校验的设备,比如短信/邮箱校验后再登记此设备。

Method:PUT

Request:

参数参数类型require描述
idstringY登记设备时的用户 ID
tokenstringYVAPTCHA 验证 Token
regeditintN1 登记当前设备,0 由 VAPTCHA 自动判断是否登记

Response:

退出设备

删除当前用户最近登录设备

Method:DELETE

Request:

参数参数类型require描述
idstringY登记设备时的用户 ID

Response:

 

常见错误

错误信息描述
device not found设备未登记或未找到此设备
invalid token无效的 VAPTCHA Token
expired tokenVAPTCHA Token 过期, Token 的有效时长为 3min