API 请求域名
认证方式
服务端查询接口需要进行签名校验,签名算法使用HMAC-SHA256
。HMAC
所使用的KEY
为APP_ID
所定义的PRIVATE_KEY
,需要在后台进行创建以及获取。
签名的消息为 APP_ID 与时间戳。
sign_token = hmac(key=private_key, msg=app_id+gen_time, digestmod='SHA256').hexdigest() |
GeeToken 查询接口
POST /g2/api/{version}/token_query
URL 参数
参数名 | 是否必选 | 类型 | 说明 |
---|---|---|---|
version | 是 | String | v1:返回下方data参数中的env_check 和 is_risk_device v1.1:不返回下方data参数中的env_check 和 is_risk_device |
BODY 请求参数
格式 : JSON
参数名 | 是否必选 | 类型 | 说明 |
---|---|---|---|
app_id | 是 | String | 极验后台创建应用后生成的应用 id |
gen_time | 是 | integer | 时间戳,用于签名,精确到秒 |
gee_token | 是 | String | 客户端 sdk 收集的数据,Geetoken 有效期 10 分钟 |
scene | 否 | String | 本次查询场景: 1. login 2. sign_up 3. activity 默认为 activity |
sign_token | 是 | String | 数据签名,签名方式见 认证方式 |
attr | 是 | Object | 用于提交账号数据,获得账号画像标签,具体参见下文 attr 参数说明 |
attr 参数说明
名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
user_ip | 是 | String | 用户 IP,支持 ipv4 和 ipv6 格式, ip_type 目前只支持国内 ipv4 的 ip |
op_timestamp | 否,当需要获取账号画像标签为必传 | Integer | C 端用户发起业务操作(注册、领奖、下单等)的时间戳,精确到秒 |
user_id | 否,当需要获取账号画像标签为必传 | String | 账户 id,根据 user_id_type 传入对应的值 比如 user_id_type 为 2 时传入明文手机号 user_id_type 为 102 时,则传入 MD5 加密后的手机号 |
user_id_type | 否,当需要获取账号画像标签为必传 | Integer | 0: 自定义 1: Email 2: 手机号 102: MD5 加密手机号 3: QQOpenID 4: WechatOpenID 当需要获取账号画像标签应为[2,102,3,4]中一种, 自定义与 Email 暂时不支持 |
user_id_detail | 否,仅当 user_id_type 为 3 或者 4 时为必选 | Object,具体见下文 user_id_detail 参数说明 | 账户详细信息,仅仅在账户 id 类型为 QQOpenID 或者 WechatOpenID(user_id_type 为 3 或者 4)时需要,详见下文 user_id_detail 参数说明 |
user_id_detail 参数说明
当 user_id_type
为 3 时
名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
app_id_user | 是 | String | QQ 分配给网站或者应用的唯一 ID |
associate_account | 否 | String | 用于标识 QQ 用户登录后所关联业务自身的账号 ID |
mobile | 否 | String | 账号绑定的手机号 |
device_id | 否 | String | 设备 ID,即 IMEI 或 IDFA |
当 user_id_type
为 4 时
名称 | 是否必选 | 类型 | 说明 |
---|---|---|---|
associate_account | 否 | String | 用于标识微信用户登录后所关联业务自身的账号 ID |
wechat_sub_type | 否 | Integer | 微信开放账号类型 1. 公众号、微信第三方登录 2. 小程序 |
rand_str | 否,仅当 type 为 2 时必传 | String | 签名用随机字符串,建议 16 字符 |
wechat_access_token | 否 | String | 如果传入的微信开放账号类型为 1,则传入授权用的 access_token;如果微信开放账号类型为 2,则传入密钥为 session_key,使用 hmac_sha256 算法对 nonce 字段签名的字符串结果 |
mobile | 否 | String | 账号绑定的手机号 |
device_id | 否 | String | 设备 ID,即 IMEI 或 IDFA |
参数示例
{ |
返回参数
名称 | 类型 | 说明 |
---|---|---|
status | String | 返回结果的状态说明,success 为成功 |
code | Integer | 返回结果的状态码 0 为成功 |
data | Object | 具体见下文 data 参数说明 |
data 参数说明
名称 | 类型 | 说明 |
---|---|---|
local_id | String | sdk 本地生成的设备指纹 |
root_id | String | 服务端生成的设备指纹 |
env_check | Object | 风险检测项结果,如果对应的 key 为 true 表示命中该规则,否则为没有命中 v1.1不返回 |
risk_code | Array(Integer) | 当前请求命中的风险码 |
risk_level | String | 当前结果的处置建议 pass:无恶意,直接通过 review:结合业务处理或观察 reject:高风险,封禁拒绝 此字段可能返回 null,表示取不到有效值 |
ip_type | Integer | IP 类型,只支持国内 IPv4 的 IP 1 表示数据中心 2 表示专用出口 3 表示普通宽带 4 表示移动宽带 5 表示媒体方 IP 6 表示已知爬虫 7 表示中小运营商 -1 表示未查询到 |
is_risk_device | Boolean | 当前流量所使用的设备是否有风险 v1.1不返回 |
sign | String | 客户端提交的用户业务数据的签名,用于校验或关联业务数据和安全结果。签名规则为sign = sha256(具有唯一性的业务数据).hexdigest() ,唯一性的业务数据一般为业务流水号或凭据。如果在客户端上未提供业务数据则返回为空字符串。 |
ts | Integer | 服务端时间戳 |
client_ts | Integer | 客户端数据生成的时间戳 |
参数示例
{ |
env_check 参数说明
说明:此参数在 POST /g2/api/v1.1/token_query 不返回
名称 | 类型 | 客户端类型 | 说明 |
---|---|---|---|
is_simulator | Boolean | Android, iOS, Web | 是否为模拟器 |
is_debug | Boolean | Android, iOS, Web, MiniApp | 是否为调试模式 |
is_hook | Boolean | Android, iOS, Web | 是否篡改 |
is_risk_app | Boolean | Android, iOS | 是否安装风险应用 |
is_proxy | Boolean | Android, iOS, MiniApp | 是否开启代理 |
is_multi_open | Boolean | Android, iOS | 是否多开应用 |
is_vpn | Boolean | Android, iOS | 是否开启 VPN |
is_root | Boolean | Android | 是否为 Root 机器 |
is_jailbreak | Boolean | iOS | 是否为越狱机器 |
is_blacklist_device | Boolean | Android, iOS | 是否为黑名单机器 |
is_incognito | Boolean | Web | 是否匿名模式 |
risk_code 参数说明
设备风险码
客户端风险码 | 风险码说明 | 场景风险说明 | 适用的端类型 |
---|---|---|---|
10001 | 检测到包名篡改或重打包 | 部分黑产会篡改程序包加入广告或修改业务逻辑后,重新打包发布 | Android, iOS |
10002 | GeeToken 过期或者重复使用,GeeToken 有效期 10 分钟 | 黑产可能会缓存堆积令牌,在活动开始短时间内利用缓存令牌大批量请求业务接口 | Android, iOS, Web |
20100 | 检测到传统模拟器风险 | 黑产利用传统模拟器可以大批量完成黑产操作,比如规模化的注册、大批量登录撞库等等 | Android, iOS, Web |
20101 | 检测到 ARM 模拟器(或云手机)风险 | 黑产利用 ARM 模拟器(或云手机)可以相较于以往的技术能更高效、自动化完成黑产操作,比如可规模化的注册、大批量登录撞库等等 | Android |
20103 | 检测到 Mac 运行 App 风险 | 黑灰产利用 M 芯片的 Mac 运行 App 更容易自动化、篡改的特点,从而进行相关的黑灰产行为 | iOS |
20200 | 设备存在使用多开工具风险 | 如羊毛党会在裂变活动在同一设备上制作多个 App 分身,登录多个账号,协同完成邀请流程 | Android |
20201 | 检测到设备安装了改机工具风险 | 黑产为了躲避风控工具检测,会更改部分设备信息和属性,比如更改 IMEI 等设备标识以逃逸设备指纹的标记 | Android, iOS |
20202 | 检测到设备安装了群控/自动化工具风险,可规模化黑产操作 | 高效率的控制多台设备,完成规模化操作,比如点赞转发,群发广告等 | Android, iOS |
20203 | 检测到设备安装逆向工具风险 | 黑产会使用一些逆向工具,逆向应用的业务逻辑,进而篡改代码 | Android, iOS, Web |
20204 | 设备存在使用网络篡改工具风险 | 黑产通常会利用此类工具篡改网络以达到攻击的目的,比如躲避风控系统在网络标识层面的追踪和检测 | Android, iOS |
20205 | 设备存在使用游戏修改器工具风险 | 打金工作室或者玩家作弊会使用此类工具完成游戏作弊 | Android, iOS |
20206 | 检测到设备安装了虚拟定位风险 | 黑产通常会篡改位置信息,躲避业务在位置上的限制,或者伪造轨迹模拟真人轨迹行为 | Android, iOS |
20207 | 当前处于安卓虚拟机环境中 | 黑产可在安卓设备上虚拟出一个新的安卓环境,可以完成大多数自动化攻击,比如自动下单,自动升级,自动加好友等等 | Android |
20210 | 当前处于处于多开环境中 | 黑产可以在设备自带的分身应用上 ,开多个应用分身,完成多账号登录和协作 | Android, iOS |
20211 | 当前正使用改机或风险工具 | 黑产为了躲避风控工具检测,会更改部分设备信息和属性,比如更改 IMEI 等设备标识以逃逸设备指纹的标记 | Android |
20212 | 当前正使用群控或自动化工具 | 高效率的控制多台设备,完成规模化操作,比如点赞转发,群发广告等 | Android, iOS |
20213 | 当前正使用逆向篡改工具 | 黑产会使用一些逆向工具,逆向应用的业务逻辑,进而篡改代码 | Android |
20216 | 当前正使用虚拟定位工具 | 黑产通常会篡改位置信息,躲避业务在位置上的限制,或者伪造轨迹模拟真人轨迹行为 | Android, iOS |
20300 | 设备有代码篡改低风险,使用该标签需要排除自身开发篡改的行为 | 有代码篡改嫌疑,可能是黑产的篡改行为,也可能是开发人员在开发中使用了篡改技术 | iOS, Web |
20301 | 设备有代码篡改中风险,可篡改代码逻辑 | 有代码篡改行为,黑产篡改代码逻辑后会攻击业务接口,以达到某种牟利的目的 | Android,iOS |
20302 | 设备有代码篡改高风险 | 有高风险代码篡改行为,使用了较危险的篡改技术 | Android, iOS |
20303 | 设备存在信息伪造风险,设备属性或指纹不匹配 | 黑产会伪造一些设备信息,可将当前设备伪装成另一个新的设备,进而绕过业务限制进行和灰产行为 | Android, iOS |
20400 | 设备存在被调试风险,可进行逆向分析、破解、群控自动化 | 通常黑产使用调试技术用于逆向分析、破解接口等场景 | Android, iOS, Web, MiniApp |
20401 | 设备开启了调试模式或使用 debug 版本的应用包 | 通常调试、群控或者破解会有该特征,也有部分正常用户无意中打开发者模式也会导致命中。 | Android, iOS |
20402 | 设备正在进行屏幕分享 | 网络诈骗人员可能以哄骗方式引导用户开启屏幕共享,从而泄露个人信息,最终导致财产损失 | iOS |
20500 | 设备开启 VPN 中 | 设备开启了 VPN,存在网络层面的篡改风险,通过 VPN 可躲避网络标识的追踪,甚至篡改网络 | Android, iOS |
20501 | 设备开启网络代理中 | 设备存在网络代理行为,通过系统代理从指定的出口访问,躲避风控系统的检测和限制 | Android, iOS, MiniApp |
20600 | iOS 设备存在越狱行为 | iOS 设备越狱能获取更高的权限,更进一步的对业务进行篡改 | iOS |
20601 | Android 设备存在 Root 行为 | 黑产通常会 Root Android 设备,获取更高的权限,更进一步的对业务进行篡改 | Android |
20602 | Android 设备使用可疑定制 ROM | 部分黑灰产设备在 Android 开源项目上定制的 ROM,有较好的伪装能力,能对业务较大的破坏性,设备系统不可信 | Android |
20603 | Android 设备 ROM 为安卓开源项目 | 正常的安卓设备都是自带厂商特性原生系统,部分黑灰产设备使用 Android 开源系统,能对业务有一定的破坏性,设备系统风险可疑 | Android |
20604 | 浏览器cookie不可用 | 浏览器环境cookie被禁用 | Web |
20605 | 伪造的浏览器环境用 | 黑产通常会脱离容器伪造出与正常浏览器一致的运行环境进行协议破解 | Web |
20606 | 浏览器处于隐私模式 | 网页运行在隐私模式的浏览器环境下 | Web |
20610 | 设备系统版本过低 | 大多数灰黑产使用的的手机比较陈旧,设备性能较低,系统版本也较低,如:系统版本保持在 Android 9 和 iOS 11 以下。 | Android, iOS |
21000 | 检测到设备未插 SIM 卡 | 正常用户的设备都会使用运营商 SIM 卡,无卡设备访问业务,往往来自灰黑产的设备墙和设备农场 | Android, iOS |
40003 | 设备指纹黑名单 | 在后台添加的设备指纹黑名单 | Android, iOS, Web |
60113 | 设备指纹白名单 | 在后台添加的设备指纹白名单 | Android, iOS, Web |
IP 风险码
说明:建议参考上方 risk_level
和 ip_type
参数,结合业务进行处置
客户端风险码 | 风险码说明 | 场景风险说明 | 适用的端类型 |
---|---|---|---|
40002 | IP 黑名单 | 在后台添加的 ip 黑名单 | Android, iOS, Web |
40201 | IP 存在恶意破解或爬虫行为 | IP 曾经有过恶意破解或爬虫行为 | Android, iOS, Web |
40202 | IP 存在恶意攻击行为 | IP 曾经有过恶意攻击行为 | Android, iOS, Web |
40204 | IP 疑似代理IP | IP 疑似代理IP | Android, iOS, Web |
60112 | IP 白名单 | 在后台添加的 ip 白名单 | Android, iOS, Web |
账号风险码
(以下风险码需正确传入 attr 参数 才会返回)
账号风险码 | 一级说明 | 二级说明 |
---|---|---|
40001 | 用户账号黑名单 | 在后台添加的账号黑名单,如手机号黑名单、微信 Openid 黑名单等 |
60111 | 用户账号白名单 | 在后台添加的账号白名单,如手机号白名单、微信 Openid 白名单等 |
90101 | 账号信用低 | 账号近期存在因恶意被处罚历史,网络低活跃,被举报等因素 |
90102 | 疑似低活跃账号 | 账号活跃度与正常用户有差异 |
90103 | 垃圾账号 | 疑似批量注册小号,近期存在严重违规或大量举报 |
90104 | 疑似小号 | 账号有疑似线上养号,小号等行为 |
90105 | 疑似违规账号 | 账号曾有违规行为、曾被举报过、曾因违规被处罚过等 |
90106 | 无效账号 | 无效账号 送检账号参数无法成功解析,请检查微信 openid 是否有误/QQopenid 是否与 QQ 开发平台的 appid 关联,手机号是否为中国大陆手机号 |
4 | 黑名单 | 该账号在业务侧有过拉黑记录 |
5 | 白名单 | 业务自行有添加过白名单记录 |
90401 | 批量操作 | 存在 ip/设备/环境等因素的聚集性异常 |
90402 | 疑似 IP 属性聚集 | 出现 IP 聚集 |
90403 | 疑似设备属性聚集 | 出现设备聚集 |
90404 | 自动机 | 疑似自动机批量请求 |
90405 | 恶意行为-网赚 | 疑似网赚 |
90107 | 微信登录态无效 | 检查 wxtoken 参数,是否已经失效 |
90201 | 环境异常 | 操作 ip/设备/环境存在异常。当前 ip 为非常用 ip 或恶意 ip 段 |
90202 | 疑似非常用 IP 请求 | 当前请求 IP 非该账号常用 IP |
90203 | 疑似 IP 异常 | 使用 idc 机房 ip 或 使用代理 ip 或 使用恶意 ip 等 |
90204 | 非公网有效 ip | 传进来的 IP 地址为内网 ip 地址或者 ip 保留地址; |
90301 | 设备异常 | 该设备存在异常的使用行为 |
90302 | 疑似非常用设备 | 当前请求的设备非该账号常用设备 |
90303 | 疑似虚拟设备 | 请求设备为模拟器、脚本、云设备等虚拟设备 |
90304 | 疑似群控设备 | 请求设备为猫池、手机墙等群控设备 |