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

重点备注

接口路径 说明 重点
/register 验证初始化接口 1、代码里会将标识接口正常、异常的status存入session,在二次验证接口里取出session里的该值并进行判断,1就进入正常二次验证逻辑,0就进入宕机模式逻辑。
2、返回参数success字段与代码里status含义对应,控制前端的表现形式,1就展现正常页面,0就展示宕机页面。
3、本demo应用的session是单机模式,格外注意分布式环境下session的应用;建议可使用数据库存储分布式session。
/validate 二次验证接口 1、当session中取出status=0时表示验证初始化接口异常,此时流程进入宕机模式,后续逻辑都是在本地服务器完成,不会再向极验服务器发送网络请求。
2、本demo中,宕机模式只对请求参数做了简单的校验,也可自行设计。
3、模拟宕机模式:在配置文件中将极验账号id替换为123456789

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内部与极验服务器交互接口

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,可支持md5、sha256、hmac-sha256,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": "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"
}

引用

服务端常见问题

服务端常见错误码