设备指纹
接入指南

服务端 API

查询设备指纹识别结果的服务端接口文档

接口用途

fp_query 用于查询设备指纹识别结果。

调用方需要先通过 client_report 获取服务端返回的 gee_token，再将该 gee_token 传给 fp_query，获取最终的：

  • fp 指纹值
  • risk_code 风险码
  • risk_label 风险标签
  • client_ip 客户端 IP
  • client_type 客户端类型
  • access_list 名单命中信息

接入流程

标准调用顺序如下：

  1. 客户端采集指纹数据，调用 client_report
  2. 服务端返回新的 gee_token
  3. 调用方将该 gee_token、private_key、ts 传给 fp_query
  4. 服务端返回最终查询结果

注意：

  • fp_query 只接受 client_report 返回的 gee_token
  • 不要将客户端原始 token 直接传给 fp_query

请求信息

请求方式

POST

请求地址

/api/v1/fp_query/{app_id}

Path 参数

参数类型必填说明
app_idstring是应用 ID

请求体

{
  "gee_token": "string",
  "private_key": "string",
  "ts": 1712345678
}

字段说明：

字段类型必填说明
gee_tokenstring是client_report 返回的 token
private_keystring是应用密钥，必须与 app_id 对应
tsinteger是当前请求时间戳，建议使用秒级 Unix 时间戳

成功响应

响应格式

{
  "status": "success",
  "code": 0,
  "data": {
    "fp": "fp-value",
    "risk_code": [20400, 20606],
    "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"],
    "client_ip": "1.1.1.1",
    "client_type": "Web/H5",
    "access_list": {
      "hit": false,
      "list_type": "none",
      "identity_type": ""
    }
  }
}

字段说明

字段类型说明
statusstring成功时固定为 success
codeinteger成功时固定为 0
data.fpstring指纹值
data.risk_codeinteger[]风险码列表
data.risk_labelstring[]风险标签列表，与 risk_code 一一对应
data.client_ipstring客户端 IP
data.client_typestring客户端类型
data.access_listobject名单命中结果

access_list 字段说明

access_list 结构如下：

{
  "hit": false,
  "list_type": "none",
  "identity_type": ""
}

字段说明：

字段类型说明
hitboolean是否命中名单
list_typestring名单类型；未命中时通常为 none
identity_typestring命中的身份类型；未命中时通常为空字符串

常见示例：

  • 未命中：{"hit": false, "list_type": "none", "identity_type": ""}
  • 命中黑名单：{"hit": true, "list_type": "black", "identity_type": "fingerprint"}

client_type 返回值

当前接口会将内部客户端类型编码转换为可读文本：

编码返回值
1Android
3Web/H5
4iOS

调用示例

请求示例

curl -X POST 'https://your-domain/api/v1/fp_query/test-app' \
  -H 'Content-Type: application/json' \
  -d '{
    "gee_token": "output-gee-token-from-client-report",
    "private_key": "private-key",
    "ts": 1712345678
  }'

响应示例

{
  "status": "success",
  "code": 0,
  "data": {
    "fp": "GEE3-01-xxxxxxxx",
    "risk_code": [20400, 20606],
    "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"],
    "client_ip": "1.1.1.1",
    "client_type": "Web/H5",
    "access_list": {
      "hit": false,
      "list_type": "none",
      "identity_type": ""
    }
  }
}

risk_code 说明

risk_code 表示设备或环境命中的风险项，可能同时返回多个值。

返回规则：

  • risk_code 是整数数组
  • risk_label 与 risk_code 按顺序一一对应
  • 同一次查询可能命中多个风险码
  • 未命中风险时，risk_code 可能为空数组 []

示例：

{
  "risk_code": [20400, 20606],
  "risk_label": ["BEING_DEBUGGED", "BROWSER_INCOGNITO_MODE"]
}

以下 risk_code 列表用于帮助业务理解常见风险标签及其适用场景，便于将查询结果接入放行、二次验证、限流或审核策略。

当前风险码说明如下。

基础类

risk_coderisk_label说明场景风险说明适用的端类型
10001INVALID_PACKAGE应用包信息校验异常部分黑产会篡改程序包加入广告或修改业务逻辑后，重新打包发布Android, iOS
10002TOKEN_EXPIREDtoken 已过期黑产可能会缓存堆积令牌，在活动开始短时间内利用缓存令牌大批量请求业务接口Android, iOS, Web

设备 / 运行环境类

risk_coderisk_label说明场景风险说明适用的端类型
20100EMULATOR模拟器环境黑产利用传统模拟器可以大批量完成黑产操作，比如规模化的注册、大批量登录撞库等等Android, iOS, Web
20101CLOUD_PHONE云手机环境黑产利用云手机（或 ARM 服务器）可以相较于以往的技术能更高效、自动化完成黑产操作，比如可规模化的注册、大批量登录撞库等等Android
20103RUNNING_ON_MACOS运行在 macOS 环境黑灰产利用 M 芯片的 Mac 运行 App 更容易自动化、篡改的特点，从而进行相关的薅羊毛行为iOS
20207RUNNING_IN_VIRTUAL_MACHINE运行在虚拟机环境黑产可在设备上虚拟出一个新的环境，可以完成大多数自动化攻击，比如自动下单，自动升级，自动加好友等等Android, iOS, Web
20220RUNNING_IN_SYSTEM_CLONED运行在系统分身环境黑产可能利用设备系统多开技术，在单一设备上同时运行多个APP实例，进行批量注册、频繁登录撞库等操作，从而规避平台风控检测并牟取非法利益。Android
21000DEVICE_WITHOUT_SIM设备无 SIM 卡正常用户的设备都会使用运营商 SIM 卡，无卡设备访问业务，往往来自灰黑产的设备墙和设备农场Android, iOS

篡改 / 自动化 / 逆向类

risk_coderisk_label说明场景风险说明适用的端类型
20200APP_CLONE_TOOL_INSTALLED安装了应用分身工具如羊毛党会在裂变活动在同一设备上制作多个 App 分身，登录多个账号，协同完成邀请流程Android, Web
20201TAMPERING_TOOL_INSTALLED安装了篡改工具黑产为了躲避风控工具检测，会更改部分设备信息和属性，比如更改 IMEI 等设备标识以逃逸设备指纹的标记Android, iOS
20202AUTOMATION_TOOL_INSTALLED安装了自动化工具高效率的控制多台设备，完成规模化操作，比如点赞转发，群发广告等Android, iOS
20203REVERSE_ENGINEERING_TOOL_INSTALLED安装了逆向工具黑产会使用一些逆向工具，逆向应用的业务逻辑，进而篡改代码Android, iOS, Web
20204NETWORK_TAMPER_TOOL_INSTALLED安装了网络篡改工具黑产通常会利用此类工具篡改网络以达到攻击的目的，比如躲避风控系统在网络标识层面的追踪和检测Android, iOS
20205GAME_TAMPER_TOOL_INSTALLED安装了游戏篡改工具打金工作室或者玩家作弊会使用此类工具完成游戏作弊Android, iOS
20206VIRTUAL_LOCATION_TOOL_INSTALLED安装了虚拟定位工具黑产通常会篡改位置信息，躲避业务在位置上的限制，或者伪造轨迹模拟真人轨迹行为Android, iOS
20210RUNNING_IN_CLONED_APP运行在应用分身环境黑产可以在设备自带的分身应用上，开多个应用分身，完成多账号登录和协作Android, iOS
20211USING_DEVICE_TAMPERING_TOOL正在使用设备篡改工具黑产为了躲避风控工具检测，会更改部分设备信息和属性，比如更改 IMEI 等设备标识以逃逸设备指纹的标记Android
20212USING_AUTOMATION_TOOL正在使用自动化工具高效率的控制多台设备，完成规模化操作，比如点赞转发，群发广告等Android, iOS
20213USING_REVERSE_ENGINEERING_TOOL正在使用逆向工具黑产会使用一些逆向工具，逆向应用的业务逻辑，进而篡改代码Android
20216USING_VIRTUAL_LOCATION正在使用虚拟定位黑产通常会篡改位置信息，躲避业务在位置上的限制，或者伪造轨迹模拟真人轨迹行为Android, iOS

Hook / 信息篡改类

risk_coderisk_label说明场景风险说明适用的端类型
20300HOOK_TAMPERING_LOW低风险 Hook 篡改有代码篡改嫌疑，可能是黑产的篡改行为，也可能是开发人员在开发中使用了 hook 技术iOS, Web
20301HOOK_TAMPERING_MEDIUM中风险 Hook 篡改有代码篡改行为，黑产篡改代码逻辑后会攻击业务接口，以达到某种牟利的目的Android, iOS, Web
20302HOOK_TAMPERING_HIGH高风险 Hook 篡改有高风险代码篡改行为，使用了较危险的篡改技术Android, iOS
20303SUSPICIOUS_DEVICE_INFO_TAMPERED设备信息疑似被篡改黑产会伪造一些设备信息，可将当前设备伪装成另一个新的设备，进而绕过业务限制进行和灰产行为Android, iOS

调试 / 交互风险类

risk_coderisk_label说明场景风险说明适用的端类型
20400BEING_DEBUGGED设备或页面处于被调试状态通常黑产使用调试技术用于逆向分析、破解接口等场景Android, iOS, Web
20401DEBUG_MODE_OR_TEST_APP调试模式或测试应用环境通常调试、群控或者破解包会有该特征，也有部分正常用户无意中打开发者模式也会导致命中。Android, iOS
20402SCREEN_SHARING存在投屏或共享屏幕行为网络诈骗人员可能以哄骗方式引导用户开启屏幕共享，从而泄露个人信息，最终导致财产损失Android, iOS
20403VOICE_CONNECTED存在语音连线行为网络诈骗人员可能通过语音通话实施诈骗行为，导致财产损失Android, iOS

网络环境类

risk_coderisk_label说明场景风险说明适用的端类型
20500VPN_ENABLED开启了 VPN设备开启了 VPN，存在网络层面的篡改风险，通过 VPN 可躲避网络标识的追踪，甚至篡改网络Android, iOS
20501NETWORK_PROXY存在代理网络设备存在网络代理行为，通过系统代理从指定的出口访问，躲避风控系统的检测和限制Android, iOS

Root / Jailbreak / 系统风险类

risk_coderisk_label说明场景风险说明适用的端类型
20600DEVICE_JAILBREAK设备已越狱iOS 设备越狱能获取更高的权限，更进一步的对业务进行篡改iOS
20601DEVICE_ROOTED设备已 Root黑产通常会 Root Android 设备，获取更高的权限，更进一步的对业务进行篡改Android
20602SUSPICIOUS_CUSTOM_ROM可疑定制 ROM部分黑灰产设备在 Android 开源项目上定制的 ROM，有较好的伪装能力，能对业务较大的破坏性，设备系统不可信Android
20603SUSPICIOUS_OPEN_SOURCE_ROM可疑开源 ROM正常的安卓设备都是自带厂商特性原生系统，部分黑灰产设备使用 Android 开源系统，能对业务有一定的破坏性，设备系统风险可疑Android
20607DEVICE_BOOTLOADER_UNLOCKEDBootloader 已解锁黑产解锁Bootloader后，其保护机制容易被绕过，恶意软件和攻击者更容易获取设备的控制权Android
20608SUSPICIOUS_DEVICE_RESET设备重置行为可疑疑似黑灰产通过重置进行黑灰产活动Android, iOS
20610SYSTEM_VERSION_TOO_LOW系统版本过低大多数灰黑产使用的的手机比较陈旧，设备性能较低，系统版本也较低，如：系统版本保持在 Android 9 和 iOS 11 以下。Android, iOS

浏览器环境类

risk_coderisk_label说明场景风险说明适用的端类型
20604BROWSER_COOKIE_FEATURE_DISABLED浏览器 Cookie 功能关闭浏览器环境cookie被禁用Web
20605PSEUDO_BROWSER_ENV疑似伪造浏览器环境黑产通常会脱离容器伪造出与正常浏览器一致的运行环境进行协议破解Web
20606BROWSER_INCOGNITO_MODE浏览器处于无痕模式网页运行在隐私模式的浏览器环境下Web

说明：

  • 官网后台展示时，建议同时展示 risk_code 和 risk_label
  • 风险码含义会随规则扩展而增加，调用方应按“可能返回多个值”处理
  • 对未知风险码，risk_label 可能为空字符串

错误说明

业务错误返回格式

业务错误时，HTTP 状态码通常仍为 200，响应格式如下：

{
  "status": "error",
  "code": -40000,
  "msg": "param error",
  "desc": {}
}

常见错误码

private_key 不匹配

{
  "status": "error",
  "code": -40003,
  "msg": "private_key mismatch",
  "desc": {
    "app_id": "test-app"
  }
}

排查方向：

  • 检查 private_key 是否与当前 app_id 对应
  • 检查是否调用了错误的应用配置

应用不存在或当前环境不可见

{
  "status": "error",
  "code": -40004,
  "msg": "app not found",
  "desc": {
    "app_id": "test-app"
  }
}

排查方向：

  • 检查 app_id 是否正确
  • 检查应用是否已删除
  • 检查当前部署环境是否允许访问该应用

传入的不是服务端返回的 gee_token

{
  "status": "error",
  "code": -40000,
  "msg": "param error",
  "desc": {
    "field": "token",
    "reason": "geetoken required",
    "crypt_type": 10
  }
}

排查方向：

  • 检查是否把客户端原始 token 直接传给了 fp_query
  • 确认传入的是 client_report 返回的 gee_token

系统内部异常

{
  "status": "error",
  "code": -50000,
  "msg": "runtime error",
  "desc": {
    "type": "异常类型文本"
  }
}

参数校验错误

如果请求体缺字段或字段类型错误，接口会直接返回 422，不会使用业务错误包装。

常见场景：

  • 缺少 gee_token
  • 缺少 private_key
  • ts 不是整数

接入建议

建议按以下方式接入：

  1. 将 client_report 和 fp_query 作为一组接口使用
  2. 只把 client_report 返回的 gee_token 传给 fp_query
  3. 保证 app_id 与 private_key 来自同一个应用
  4. ts 使用服务端生成的当前时间戳，避免明显过旧的数据
  5. 使用 risk_code + risk_label 作为业务判定输入，不建议只依赖单一字段

On this page

接口用途接入流程请求信息请求方式请求地址Path 参数请求体成功响应响应格式字段说明access_list 字段说明client_type 返回值调用示例请求示例响应示例risk_code 说明基础类设备 / 运行环境类篡改 / 自动化 / 逆向类Hook / 信息篡改类调试 / 交互风险类网络环境类Root / Jailbreak / 系统风险类浏览器环境类错误说明业务错误返回格式常见错误码private_key 不匹配应用不存在或当前环境不可见传入的不是服务端返回的 gee_token系统内部异常参数校验错误接入建议