验证流程

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

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

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

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

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


Web客户端部署

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

环境

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

安装

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

  2. 引入前端sdk:

  3. 初始化VAPTCHA

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

    • 方式二:自动初始化并加载验证按钮

      如果你是以直接提交表单的方式发起请求,推荐使用此方法,容器内默认会添加一个name值为vapthca_tokeninput,其值为验证通过后的token

      可选以下两种方式

      配置data-vid,填入验证单元的VID,此种方式默认初始化点击式

      配置data-config,填入配置对象的JSON字符串

  4. 使用点击式时推荐使用官方预加载动画:

    效果图:

    代码如下:

     

配置参数

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

通用参数

必填参数

参数名类型说明
vid字符串验证单元的VID
type字符串可选值click, embed, invisible

可选参数

参数名类型默认值说明
lang字符串zh-CN可选值zh-CN,en,zh-TW
https布尔值false协议类型,是否为https
scene字符串空字符串验证单元场景

type参数说明

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

类型参数
适用类型参数名参数类型必填默认值说明
点击式、嵌入式containerElementselector
点击式style字符串dark按钮样式,可选dark,light
点击式color字符串#57ABFF按钮颜色
隐藏式aiAnimation布尔值true是否显示验证动画

验证码实例

获取实例

调用vaptcha方法,第一个参数传入配置,返回一个对象,该对象提供一个then方法,接受一个回调函数,返回创建成功后的vaptcha实例对象vaptchaObj

实例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

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

示例代码:

 

服务端二次验证

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

API请求数据

地址: http://api.vaptcha.com/v2/validate

POST参数说明
id验证单元的VID(必填)
secretkey验证单元的Key(必填)
scene验证单元场景,需与前端配置参数中的scene一致,e.g: '01'
token客户端验证成功得到的token(必填)
ip获取用户的remote address

API响应结果

返回json字符串

错误消息说明

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

 

宕机模式(服务端配置)

此文档的示例代码使用Nodejs,仅供参考,部分方法需用户自己实现,具体实现可根据实际情况作调整。(宕机模式原理

outage接口说明

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

前端初始化示例代码:

接口参数

接受参数

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

get 获取图片操作

outage接口的aciton值 为 get时的操作

获取流程:

  1. 获取服务器宕机key

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

    其中key即为宕机key,示例代码:

    active表示是否进入宕机,true表示进入宕机。

  2. 生成随机数randomStr

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

  3. 生成验证图imgid

    取宕机keyrandomStrmd5值作为验证图的imgid,示例代码:

  4. 生成流水号challenge

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

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

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

verify 轨迹验证操作

outage接口的aciton值 为 verify时的操作

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

验证流程:

  1. 生成轨迹验证validatekey

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

  2. 服务器端发起轨迹验证请求

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

  3. 验证成功,返回token

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

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

服务器端验证token

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

完整demo

地址: https://github.com/VAPTCHA/vaptcha-donwtime