新版本 设备标识服务 v3/v4 开放测试,Web / Android 已接入,iOS 规划中 申请测试额度

开发文档

设备标识服务对外开放。客户端采集后换取 token,业务后端用 token 换取设备标识;原始特征不经过业务系统。

快速开始

一次完整的接入分为三段:客户端取 token,前端把 token 交给自家后端,后端带签名换取标识。

1. 引入 SDK

线上产物经过压缩与混淆,文件名带构建版本号。升级时只改版本号,旧版本文件保留以便回滚。

<script src="https://fp.mima-code.com/sdk/core.js"></script>

2. 初始化并获取 token

const app = AppSDK.init({ appKey: '<APP_KEY>', server: 'https://fp.mima-code.com', timeout: 6000, }); const { code, token } = await app.getTokenAsync(); if (code === 200 || code === 201) { await post('/api/device-token', { token }); // 交给自家后端 }

3. 服务端换取标识

POST /sdk/v1/check { "app_id": "<APP_ID>", "timestamp": 1730000000000, "nonce": "<32 位随机串>", "version": "1.0", "sign": "<md5>", "token": "<客户端 token>" }
接口返回 device_id 与标识版本 version(当前固定为 v3),device_id 固定 32 位,可用「设备标识鉴别」接口验证是否为该应用签发的有效标识;业务后端按现有规则拼出 fp 头:{device_id}|{version}|{md5(device_id . '$originalFingerprint')}。请原样使用返回的 version,不要自行固定。

客户端接入

三端共用同一套接口契约,SDK 按平台分别提供。选择平台查看依赖、初始化与取 token 的方式。

引入 SDK

<script src="https://fp.mima-code.com/sdk/core.js"></script>

初始化

只使用公开的应用标识,不携带任何密钥。真正的鉴权在服务端由来源白名单与配额承担。

AppSDK.init({ appKey: '<APP_KEY>', // 必填,公开标识 server: 'https://fp.mima-code.com', // 可选,默认公网地址 timeout: 6000, // 可选,采集上报超时(毫秒) callback(code, msg) {} // 可选,初始化回调 })
code含义
200初始化完成
109重复初始化,沿用已有实例
199应用标识无效或已停用

获取 token

同步接口返回当前状态;异步接口优先返回本地缓存。凭证有效期 30 分钟,SDK 本地缓存 20 分钟,缓存有效时不采集、不请求,到期后自动重新获取。

// 同步 const { code, token } = app.getToken(); // 异步 app.getTokenAsync().then((result) => { if (result.code === 200 || result.code === 201) { // result.token 交给业务后端 } });
code状态处理
200正常模式,数据已上报,token 长度固定直接送检
201离线模式,上报失败,token 为本地加密载荷同样送检,效果一致
202获取异常,token 为空串本次不送检,稍后重试
尚未获取 token(例如初始化后未调用 getTokenAsync)时同步接口返回 202。需要稳定结果请使用异步接口。
Android SDK 已接入(联调版本)。使用 a1 算法,与 Web 的 v3/v4 隔离;token / check 与 Web 共用同一组接口。以下是当前联调接入方式。

添加依赖

// libs/ 下放入 AAR,随应用打包 implementation files('libs/mima-sdk-x.y.z.aar')

初始化

在 Application.onCreate() 中调用一次。初始化只使用公开的应用标识,鉴权由服务端按来源白名单与配额控制。

MimaSDK.init( context = applicationContext, appKey = "<APP_KEY>", server = "https://fp.mima-code.com", namespace = "mima_default" )

获取 token

异步回调,超时建议 3000ms。成功时把 token 交给业务后端,不要保存在业务本地。

MimaSDK.getTokenAsync(timeout = 3000) { result -> when (result.code) { 200, 201 -> uploadToBackend(result.token) // 在线 / 离线均可送检 202 -> retryLater() // 本次不送检 } }

采集范围

SDK 只在端侧读取设备、系统与渲染栈的公开环境特征,用于生成稳定标识;具体参与计算的字段与权重由服务端维护,不对外公开。

核心哈希不包含 IMEI、MAC、Android ID、序列号等受限标识;测试环境的身份解析层会把部分标识作为辅助锚点,生产启用前需完成合规确认。
iOS SDK 开发中。以下是已确定的接入契约,发布前可能微调;当前版本请通过业务后端使用服务端接口。

添加依赖

// Swift Package Manager .package(url: "<SDK_REPO_URL>", from: "0.1.0")

初始化

在 AppDelegate 或 SceneDelegate 启动时调用一次。

MimaSDK.shared.init( appKey: "<APP_KEY>", server: "https://fp.mima-code.com" )

获取 token

MimaSDK.shared.getToken { result in switch result.code { case 200, 201: uploadToBackend(result.token) // 在线 / 离线均可送检 default: retryLater() // 本次不送检 } }

采集范围

SDK 只在端侧读取设备、系统与渲染栈的公开环境特征,用于生成稳定标识;具体参与计算的字段与权重由服务端维护,不对外公开。

不采集 IDFA、IDFV 等受限标识。iOS 沙箱可获取的硬件信息少于 Android,核心字段会单独定义。

token 形态

服务端对两种 token 的处理方式不同,接入方不需要区分。

形态触发长度服务端处理
短 token上报成功固定 40 字符从缓存读取计算结果
长 token上报失败4–8KB解密后现场计算

短 token 建议在 30 分钟内送检,超时后返回 5512。离线 token 内含采集数据,传输与存储都应按敏感数据处理。

检测接口

POST https://fp.mima-code.com/sdk/v1/check Content-Type: application/json

公共参数与业务参数放在同一个 JSON 请求体里。

参数必填说明
app_id是接入方标识
timestamp是13 位毫秒时间戳,超过 5 分钟拒绝
nonce是32 位随机串,服务端去重防重放
version是接口版本,当前为 1.0
sign是签名,见下节
token是客户端获取的凭证
account否业务方用户 ID
ip否用户 IP,缺省取请求来源

设备标识鉴别

校验一个设备 ID 是否为本服务为该应用签发的有效标识。两种调用方式返回同一结构。

POST https://fp.mima-code.com/sdk/v1/device-verify Content-Type: application/json

公开调用(app_key)

适合前端或第三方独立校验,只需要公开的应用标识;调用方身份不可信时请改用签名调用。

{ "app_key": "<APP_KEY>", "device_id": "<32 位 Base32>" }

服务端签名调用

公共参数与检测接口一致,device_id 参与签名。

{ "app_id": "<APP_ID>", "timestamp": 1730000000000, "nonce": "<32 位随机串>", "version": "1.0", "sign": "<md5 签名>", "device_id": "<32 位 Base32>" }

响应

{ "code": 200, "msg": "ok", "data": { "signed": true } }
字段说明
signed该标识是否为本服务为该应用签发的有效标识
signed=false 表示该标识不是本服务为该应用签发的(历史数据、其他应用或伪造)。要求“必须是我们签发的 ID”时应校验该字段。

签名规则

所有参数(不含 sign)按参数名 ASCII 升序排序,依次拼接键与值,末尾追加 app_secret,整体做 MD5,取 32 位小写十六进制。

function sign(params, secret) { const keys = Object.keys(params).filter(k => k !== 'sign').sort(); let raw = ''; for (const k of keys) raw += k + params[k]; raw += secret; return md5(raw).toLowerCase(); }
空值不要省略成 null,统一传空字符串,否则前后端签名会不一致。

返回字段

{ "code": 200, "msg": "ok", "data": { "device_id": "RZBW7ZSRJ7ID3SCVY2PIICNKEF654JUB", "version": "<标识版本>", "risk_level": 0, "hit_infos": [], "first_seen": false, "task_id": "trace-id", "cached": true, "device_info": { "client": "web", "url": "https://mimaapp.com/", "os_name": "Windows", "os_version": "10/11", "platform": "Win32", "vendor": "Google Inc.", "language": "zh-CN", "languages": ["zh-CN", "en"], "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...", "browser_name": "Google Chrome", "browser_version": "148", "engine": "Blink", "device_type": "desktop", "device_model": "", "cpu_arch": "x86", "cpu_bits": "64", "cpu_cores": 16, "memory_gb": 8, "max_touch_points": 0, "screen": { "width": 2560, "height": 1440, "avail_width": 2560, "avail_height": 1400, "color_depth": 24, "pixel_depth": 24 }, "dpr": 1.25, "timezone": "Asia/Shanghai", "gpu": { "vendor": "Google Inc. (NVIDIA)", "renderer": "ANGLE (NVIDIA ... D3D11)" }, "fonts_count": 61, "webgl_supported": true, "canvas_hash": "9405961b27ed", "webgl_hash": "359e91e8205c", "is_headless": false, "sdk_version": "1.0.11" } } }

基础字段

字段说明
device_id32 位 Base32 设备标识
version标识版本,当前固定为 v3,原样用于拼接 fp 头
risk_level0 正常 / 1 低 / 2 中 / 3 高 / 4 可信
cached同一 token 重复送检时为 true
device_info设备基础信息,见下节;旧 token 可能为空对象

device_info

由客户端上报的特征解析而来,无需额外采集成本。相比同类服务多给了 CPU、内存、触点数、DPR、时区、GPU 与指纹摘要。

字段说明
client端类型:web / android / ios
url页面地址,需客户端在 features 中上报 pageUrl,否则为空串
os_name / os_version操作系统与版本,如 Windows / 10/11、Android / 14、iOS / 17.2
platform / vendornavigator.platform 与浏览器厂商
language / languages首选语言与完整语言列表
user_agent完整 UA
browser_name / browser_version浏览器与版本,优先取 Client Hints,比 UA 解析更准
engine渲染引擎:Blink / Gecko / WebKit
device_typedesktop / tablet / mobile
device_model设备型号,来自 Client Hints,移动端才有值
cpu_arch / cpu_bits / cpu_coresCPU 架构、位数、逻辑核心数
memory_gb设备内存(GB,浏览器上限 8)
max_touch_points最大触点数,0 表示非触屏
screen分辨率、可用区域、色深、像素深度
dpr设备像素比
timezone时区标识
gpu.vendor / gpu.rendererWebGL 报告的显卡厂商与渲染器
fonts_count检测到的系统字体数量
webgl_supportedWebGL 是否可用
canvas_hash / webgl_hashCanvas / WebGL 渲染结果摘要,用于快速比对是否同一渲染环境
is_headlessUA 是否包含 HeadlessChrome
sdk_versionSDK 构建版本

返回码

code含义处理建议
200正常—
400请求参数不合法检查必填字段与类型
411请求频率过高降频后重试
5501时间戳过期校准服务器时间
5502参数缺失或格式错误对照参数表检查
5505nonce 格式错误或重复每次请求生成新的 32 位随机串
5506应用标识无效确认 app_id
5507token 为空检查客户端是否成功获取 token
5508签名错误核对排序与拼接规则
5509应用已停用联系管理员
5510配额或调用次数超限联系管理员调整配额
5511重复请求本服务默认返回 cached=true,不报错
5512token 非法或过期重新获取 token 后重试一次
5514处理超时可按退避策略重试
5515处理失败重试仍失败请携带 task_id 反馈
5521可重试失败稍后重试

业务侧约定

  • 业务后端用返回的 device_id 与 version 拼出 fp 头,再按现有方式加密存储、请求时解密封装;存储层无需改动。
  • 接口始终返回 device_id,采集不完整的设备同样可用;如需让识别更稳定,可在业务关键路径上重新获取一次 token。
  • token 获取失败(202)时本次不送检,不影响业务主流程。
  • 服务不可用时沿用本地已有标识,避免阻塞下单、登录等主链路。
存量标识与旧值不同时,切换初期会出现同一设备换 ID 的情况,建议先在单一端灰度。