验证流程

  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

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

示例代码:

 

VAPTCHA-iOS SDK部署

VAPTCHA-iOS SDK提供给集成iOS原生客户端开发的开发者使用,SDK不依赖任何第三方库。

环境需求

条目资源
开发目标iOS9+
开发环境Xcode 10.0
demo依赖UIKit.framework,Foundation.framework

资源下载

条目资源地址
SDK下载链接地址
SDK接口文档查看头文件注释
Demo工程下载地址

配置

1.获取SDK

使用git命令从Github获取:

手动下载获取:Github: vaptcha iOS

2.导入SDK

1.从Github上获取的SDK手动添加,将下载获取的Vaptcha.framework文件拖拽到工程中,确保Copy items if needed已经被勾选。

请使用Linked Frameworks and Libraries方式导入framework。在拖入Vaptcha.framework到工程时后, 还要检查.framework是否被添加到PROJECT -> Build Phases -> Linked Frameworks and Libraries

2.针对静态库中的Category, 需要在对应target的Build Settings->Other Linker Flags添加-all_load编译选项。建议先添加-ObjC,如果依然有问题,再添加-all_load

3.在拖入Vaptcha.framework的同时,需要将仓库中的资源文件VPResource.bundle同时拖入到项目中,这里以 bundle 外嵌的方式单独管理 SDK 所需资源文件。

配置接口

集成用户需要使用iOS SDK 中提供的以下接口完成验证流程:

  1. 配置验证初始化;
  2. 启动验证;
  3. 获取验证凭证(token);
  4. 验证凭证(需集成用户使用服务器端SDK后自行校验)

配置说明:在用户集成SDK前,需要到VAPTCHA开发平台获取对应的vid和scene以初始化SDK配置。以及需要配置宕机模式的服务器,具体参考宕机服务器设置—>宕机服务器连接

代码示例

1. 嵌入式

使用VPEmbedManager获取嵌入视图,添加到集成用户的图层上。下图为demo样式:

 

2. 点击式

使用VPClickManager获取点击按钮视图,添加到集成用户的图层上。下图为demo样式:

 

3. 隐藏式

使用VPInvisibleManager管理类开始隐藏式验证。下图为demo样式:

 

参数说明

 

以上为VAPTCHA SDK提供的三种验证方式,具体更多参数设置详见 Demo

备注:该SDK目前暂不支持bitcode。

 

VAPTCHA-Android SDK部署

行为验证 Android SDK提供给集成Android原生客户端开发的开发者使用, SDK不依赖任何第三方库。

环境需求

条目资源
开发目标API 18+
开发环境android studio
demo依赖okgo

资源下载

条目资源地址
jar下载vaptcha_android_libary
Demo工程下载vaptcha_android

配置

1.获取JAR包

通过git命令获取:

手动下载JAR包:Github: vaptcha android

2.studio导入

模式分类

模式type描述
嵌入式embed自定义验证视图 在xml中直接引入
点击式popup自定义按钮 在xml中直接引
隐藏式invisible定义了java方法 在用户需要的地方直接调用

manifest中加入加入权限:

代码示例

1. 嵌入式

参数说明

参数名描述 
vaptcha_typeembed(嵌入式)必填
vaptcha_vidvaptcha获取到的vid必填
vaptcha_scene描述必填
vaptcha_isOutAgetrue进入宕机模式选填
vaptcha_outage_url宕机模式的服务器地址选填
vaptcha_lang语言(简体中文 zh-Hans)(繁体中文 zh-Hant)(英文 en)选填

效果图

嵌入式     效果图

2.点击式

参数说明

参数名描述 
vaptcha_typepopup(点击式)必填
vaptcha_vidvaptcha获取到的vid必填
vaptcha_scene描述必填
vaptcha_isOutAgetrue进入宕机模式选填
vaptcha_outage_url宕机模式的服务器地址选填
vaptcha_color按钮颜色选填
vaptcha_lang语言(简体中文 zh-Hans)(繁体中文 zh-Hant)(英文 en)选填

效果图

点击式 效果图

3.隐藏式

参数说明

参数名描述 
Context上下文必填
vaptcha_typeinvisible必填
vaptcha_vidvaptcha获取到的vid必填
vaptcha_scene描述必填
vaptcha_isOutAgetrue进入宕机模式选填
vaptcha_outage_url宕机模式的服务器地址选填
vaptcha_lang语言(简体中文 zh-Hans)(繁体中文 zh-Hant)(英文 en)选填

效果图

隐藏式 效果图

以上为VAPTCHA SDK提供的三种验证方式,具体更多参数设置详见 Demo

 

 

服务端二次验证

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

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