API

VAPTCHA

验证流程

  1. 创建验证单元,获取VIDKey点击创建
  2. https://v-cn.vaptcha.com/v3.js引入到你的页面。
  3. 将 VAPTCHA 初始化到你需要的位置,具体 web 端部署请查看:Web 客户端部署
  4. 用户验证通过得到token,与表单数据一同提交到服务端。
  5. 服务端得到token后,向 VAPTCHA 服务器验证token的有效性,验证通过说明此次请求有效,服务端验证流程请查看:服务端二次验证

网页部署

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

环境

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

安装

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

  2. 引入前端 sdk:

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

完整实例

点击式:

加载效果图:

img

隐藏式:

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

 

嵌入式:

配置参数

 

必填参数
参数名类型说明
vid字符串验证单元的VID
mode字符串可选值click,invisible,embedded
scene数值验证单元场景,默认 0
可选参数
参数名类型默认值说明
lang字符串auto可选值,auto,zh-CN,en,zh-TW,jp
area字符串auto验证节点区域,可选值 sea(东南亚),na(北美),cn(中国大陆),auto(根据用户区域自动匹配就近节点)

类型参数
适用类型参数名类型必填默认值说明
点击式、嵌入式containerstring或HTMLElement容器元素或容器元素选择器
点击式stylestringdark按钮样式,可选dark,light
点击式colorstring#57ABFF按钮颜色
嵌入式guideboolfalse是否在嵌入式图片底部显示操作提示文字,默认 不显示

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标签的容器,默认值为参数配置中的container容器,使用隐藏式时为必填,input将添加到配置的容器中。

  • 示例代码:

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

  • 示例代码:

 

iOS-HTML5 部署

DEMO下载: https://github.com/vaptcha/VAPTCHA-iOS-v3.git

注意: 请将DEMO中www文件夹内的ios.html与v3.js下载到本地,并替换为自己的资源地址.

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

ios.html

Android-HTML5 部署

DEMO下载: https://github.com/vaptcha/VAPTCHA-Android-v3.git

注意: 请将DEMO中www文件夹内的android.html与v3.js下载到本地,并替换为自己的资源地址.

  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)的方法,这里的字符串参数返回了验证是否通过和用户点击关闭等信息,需要在这里实现用户验证通过、失败或者取消的后续操作,具体字段为

android.html

插件

Discuz插件

人机验证:https://addon.dismall.com/plugins/vaptcha.html

手机注册:https://addon.dismall.com/plugins/phone_auth.html

Wordpress插件

人机验证:https://wordpress.org/plugins/vaptcha/

手机注册:https://wordpress.org/plugins/vaptcha-sms/

UniAPP插件

人机验证:https://ext.dcloud.net.cn/plugin?id=5879#detail

VUE

人机验证:https://www.vaptcha.com/document/vaptcha-vue-click.html

微信小程序插件

1.添加插件

请在小程序管理后台的“设置-第三方服务-插件管理”中添加插件。搜索VAPTCHA查找插件并添加,或者直接在app.json中声明插件,填入provider: wx07ad1b2dea6b6215 ,按提示添加插件。

2.获取VID及KEY

登录VAPTCHA官网,创建验证单元,免费获取VID及KEY。

详细参考验证流程

3.小程序使用

1>使用插件前,使用者要在 app.json 中声明插件,如下:

如上例所示,在plugins字段中声明插件。其中,引用名(如上例中的 vaptcha)由使用者自定义,无需和插件开发者保持一致或与开发者协调。在后续的插件使用中,该引用名将被用于表示该插件。

2>在页面.json中引入自定义组件,如下:

3>在wxml页面中使用插件并在对应的js文件中监听事件

 

后端代码部署

服务端二次验证

服务端验证的接口与返回结果说明

请求

参数名参数值说明
HTTP URL前端人机验证成功后获取的 server 参数如 https://*.vaptcha.net/verify。服务器端请增加 *.vaptcha.com 和 *.vaptcha.net 域名白名单
HTTP MethodPOST 

请求头

参数名参数值
Content-Typeapplication/json

请求参数

请求参数为JSON对象

参数名类型必填说明
idString验证单元的VID
secretkeyString验证单元的Key
sceneInt配置验证单元的场景ID,e.g.0
tokenString用户在前端验证成功后取得的token
ipString获取用户的remote address

响应结果

返回json字符串

当验证得分较低,或存在某些扣分项时,站长可自定义处理策略,如:让用户验证手机、邮箱等。

错误消息说明

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

 

V-SMS

短信接口

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

请求

参数名参数值
HTTP URLhttp://sms.vaptcha.com/send
HTTP MethodPOST

请求头

参数名参数值
Content-Typeapplication/json

请求参数

请求参数为JSON对象

参数说明

参数类型说明
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模板编号错误
213敏感词错误
230接口错误
600验证通过
601验证失败

设备校验

接口文档

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

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

设备查询

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

请求
参数名参数值说明
HTTP URL在前端验证成功后获取的 server 参数上追加/device例如:前端 server 为 https://*.vaptcha.net/verify,最终 URL为 https://*.vaptcha.net/verify/device
HTTP MethodGET 
请求参数
参数名类型必填说明
idstring用户唯一 ID,用于关联设备,无需提交用户名、手机号等隐私信息。
tokenstringVAPTCHA 人机验证成功后获取的 Token

响应数据:

设备登记

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

请求
参数名参数值说明
HTTP URL在前端验证成功后获取的 server 参数上追加/device例如:前端 server 为 https://*.vaptcha.net/verify,最终 URL为 https://*.vaptcha.net/verify/device
HTTP MethodPUT 
请求头
参数名参数值
Content-Typeapplication/json
请求参数

请求参数为JSON对象

参数名类型必填说明
idstring登记设备时的用户 ID
tokenstringVAPTCHA 验证 Token
regeditint1 登记当前设备,0 由 VAPTCHA 自动判断是否登记

响应数据:

退出设备

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

请求
参数名参数值
HTTP URLhttps://user.vaptcha.com/api/v1/device
HTTP MethodDELETE
请求参数
参数名类型必填说明
idstring登记设备时的用户 ID
deviceIdstring删除单条设备信息,不传值时删除用户id下的全部设备信息

响应数据:

查询全部设备

获取当前用户的全部登录设备

请求
参数名参数值
HTTP URLhttps://user.vaptcha.com/api/v1/device
HTTP MethodGET
请求参数
参数名类型必填说明
idstring登记设备时的用户ID

响应数据:

常见错误

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