SDK内部与极验监控交互接口

重点备注

接口路径 说明 重点
/v1/bypass_status.php 极验监控接口 1、该接口是独立于行为验证现有通讯流程之外的服务可用性监控接口,可以通过轮询机制请求该接口,通过接口返回的状态标识确认当前验证服务可用性。
2、当向极验监控接口发送请求出现返回的状态码为非200或出现请求超时的情况时,请将验证服务可用性状态标识字段置为fail。
  • 当能够提供数据存储条件时
    在sdk的demo中通过轮询机制向极验监控接口(bypass接口)发送请求,将获取的bypass状态存入数据库中(demo示例中使用的是redis,可自行设计存储架构)。当客户端向SDK服务器发起请求时,从数据库中取出状态标识字段,根据状态标识字段来决定后续向极验发起请求还是进入宕机模式不与极验发生任何交互。当获取到监控接口返回的状态为fail时,也可以选择直接放弃加载验证码,保证原有的业务流程不被阻塞。
  • 当无法提供数据存储条件时
    当实际部署环境无法满足 bypass 状态标识字段存储条件时,可以在sdk每次向极验发送请求之前,先向极验监控接口发送请求获取当前验证服务的可用性,再根据验证服务的可用性来判断后续将向极验发起请求还是进入宕机模式不与极验发生任何交互。当获取到监控接口返回的状态为fail时,也可以选择直接放弃加载验证码,保证原有的业务流程不被阻塞。

API文档概述

条目 监控接口
说明 1.该接口用于检测极验服务运行是否正常,检测范围覆盖极验服务提供的所有 API 接口;
2.该接口传入用户验证 ID,针对性检测该用户是否能正常访问极验服务,用户通过此接口的返回状态控制业务是否进入 bypass 模式;
3.可针对用户验证 ID 对该用户访问 bypass 接口后的返回状态进行配置,保证突发情况下能使业务立即切换到 bypass 模式;
域名 bypass.geetest.com
接口路径名 /v1/bypass_status.php
完整地址示例 http://bypass.geetest.com/v1/bypass_status.php
请求方式 GET/POST
请求头 (POST)Content-Type: application/x-www-form-urlencoded
请求参数格式 GET: 键值对, urlEncode
POST: 表单, urlEncode
响应头 Content-Type: application/json;charset=UTF-8
响应结果类型 json格式

bypass 请求参数

名称 类型 必填 说明
gt string Y 向极验申请的验证id

请求参数示例

gt=c9c4facd1a6feeb80802222cbb74ca8e

bypass 响应参数

名称 类型 必填 说明
status string Y success: 极验云服务正常
fail: 极验云服务异常

响应结果示例

请求响应正常时:
{"status": "success"} 表示当前极验服务状态正常
{"status": "fail"} 表示当前极验服务状态异常

请求响应异常时:
如果发送请求后出现请求超时或者返回状态码为非 200 时,请将极验服务状态标识为异常

客户端与SDK服务器交互接口

API文档概述

条目 验证初始化接口 二次验证接口
接口路径名 /register /validate
完整地址示例 http://localhost:8080/register http://localhost:8080/validate
请求方式 GET POST
请求头 Content-Type:
application/x-www-form-urlencoded
请求参数格式 键值对,urlEncode 表单,urlEncode
响应头 Content-Type:
application/json;charset=UTF-8
Content-Type:
application/json;charset=UTF-8
响应结果类型 json格式 json格式

/register 验证初始化请求参数

名称 类型 必填 说明
t string Y 时间戳

请求参数示例

t=1592814394125

/register 验证初始化响应参数

名称 类型 必填 说明
success int Y 流程状态标识(1表示正常模式,0表示宕机模式)
new_captcha bool Y 新版验证码标识,固定不变
challenge string Y 流水号,一次完整验证流程的唯一标识
gt string Y 向极验申请的账号id

响应结果示例

{
"success": 1,
"new_captcha": true,
"challenge": "2b36836f0b4ec6e6e0225e1da4ccdeb2",
"gt": "c9c4facd1a6feeb80802222cbb74ca8e"
}

/validate 二次验证请求参数

名称 类型 必填 说明
geetest_challenge string Y 流水号,一次完整验证流程的唯一标识
geetest_validate string Y 待校验的核心数据,客户端向极验请求的http://api.geetest.com/ajax.php 接口返回得到
geetest_seccode string Y 待校验的核心数据,geetest_validate加上|jordan组成的字符串

请求参数示例

geetest_challenge=31eb57657ac6746f78c4b544a1cd5147k8
&geetest_validate=580ebd155b1283c016fad1928aeff536
&geetest_seccode=580ebd155b1283c016fad1928aeff536%7Cjordan

/validate 二次验证响应参数

名称 类型 必填 说明
result string Y success表示通过;fail表示不通过
version string Y 服务端sdk版本
msg string N 结果为fail的相关信息

响应结果示例

{
"result": "fail",
"version": "jave-servlet:3.1.0",
"msg": "极验二次验证不通过"
}

SDK内部与极验服务器交互接口

重点备注

在SDK内部每次向极验服务器交互接口发送请求之前,都需要对极验服务器状态进行校验。当校验结果正常时,向极验服务器交互接口发送请求;当校验结果异常时,进入宕机模式不与极验发生任何交互。

API文档概述

条目 验证初始化 二次验证
接口路径名 /register.php /validate.php
完整地址 http://api.geetest.com/register.php http://api.geetest.com/validate.php
请求方式 GET POST
请求头 Content-Type:
application/x-www-form-urlencoded
请求参数格式 键值对,urlEncode 表单,urlEncode
响应头 Content-Type:
text/javascript;charset=UTF-8
Content-Type:
text/javascript;charset=UTF-8
响应结果类型 json格式 json格式

/register.php 请求参数

名称 类型 必填 说明
user_id string N user_id作为终端用户的唯一标识,确定用户的唯一性;作用于提供进阶数据分析服务,可在api1 或 api2 接口传入,不传入也不影响验证服务的使用;若担心用户信息风险,可作预处理(如哈希处理)再提供到极验
client_type string N 客户端类型,web(pc浏览器),h5(手机浏览器,包括webview),native(原生app),unknown(未知)
ip_address string N 客户端请求SDK服务器的ip地址
digestmod string Y 生成唯一标识字符串的签名算法,默认暂支持md5
gt string Y 向极验申请的账号id
json_format string Y json格式化标识
sdk string Y sdk代码版本号

请求参数示例

user_id=test
&client_type=web
&ip_address=127.0.0.1
&digestmod=md5
&gt=c9c4facd1a6feeb80802222cbb74ca8e
&json_format=1

/register.php 响应参数

名称 类型 必填 说明
challenge string Y 生成唯一流水号的参考字符串,为”0”表示传参账号id有误
  • 注意:此challenge字段为极验服务器返回的原始串,不可直接使用,后续需结合密钥进行编码加密才可生成唯一流水号。详见极验官方sdk demo项目代码。
  • 建议拉取极验sdk demo项目代码作参考,api文档无法代表sdk全部业务逻辑。

响应结果示例

{
"challenge": "b324874b39840757544e33bf4b60cb80"
}

/validate.php 请求参数

名称 类型 必填 说明
user_id string N user_id作为终端用户的唯一标识,确定用户的唯一性;作用于提供进阶数据分析服务,可在api1 或 api2 接口传入,不传入也不影响验证服务的使用;若担心用户信息风险,可作预处理(如哈希处理)再提供到极验
client_type string N 客户端类型,web(pc浏览器),h5(手机浏览器,包括webview),native(原生app),unknown(未知)
ip_address string N 客户端请求SDK服务器的ip地址
seccode string Y 核心校验数据
challenge string Y 流水号,一次完整验证流程的唯一标识
json_format string Y json格式化标识
sdk string Y sdk代码版本号
captchaid string Y 向极验申请的账号id

请求参数示例

user_id=test
&client_type=web
&ip_address=127.0.0.1
&seccode=f7475f921a41f7ba79ae15e41658627c%7Cjordan
&challenge=5a757e661e70fc8e307326912fee8e2c8u
&json_format=1
&sdk=java-servlet%3A3.1.0
&captchaid=c9c4facd1a6feeb80802222cbb74ca8e

/validate.php 响应参数

名称 类型 必填 说明
seccode string Y 验证结果标识,为”false”表示验证不通过

响应结果示例

{
"seccode": "91f80894e06d04a58b158ad721266b67"
}

引用

服务端常见问题

服务端常见错误码