开发文档
设备标识服务对外开放。客户端采集后换取 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 为空串 | 本次不送检,稍后重试 |
getTokenAsync)时同步接口返回 202。需要稳定结果请使用异步接口。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 只在端侧读取设备、系统与渲染栈的公开环境特征,用于生成稳定标识;具体参与计算的字段与权重由服务端维护,不对外公开。
添加依赖
// 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 只在端侧读取设备、系统与渲染栈的公开环境特征,用于生成稳定标识;具体参与计算的字段与权重由服务端维护,不对外公开。
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_id | 32 位 Base32 设备标识 |
version | 标识版本,当前固定为 v3,原样用于拼接 fp 头 |
risk_level | 0 正常 / 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 / vendor | navigator.platform 与浏览器厂商 |
language / languages | 首选语言与完整语言列表 |
user_agent | 完整 UA |
browser_name / browser_version | 浏览器与版本,优先取 Client Hints,比 UA 解析更准 |
engine | 渲染引擎:Blink / Gecko / WebKit |
device_type | desktop / tablet / mobile |
device_model | 设备型号,来自 Client Hints,移动端才有值 |
cpu_arch / cpu_bits / cpu_cores | CPU 架构、位数、逻辑核心数 |
memory_gb | 设备内存(GB,浏览器上限 8) |
max_touch_points | 最大触点数,0 表示非触屏 |
screen | 分辨率、可用区域、色深、像素深度 |
dpr | 设备像素比 |
timezone | 时区标识 |
gpu.vendor / gpu.renderer | WebGL 报告的显卡厂商与渲染器 |
fonts_count | 检测到的系统字体数量 |
webgl_supported | WebGL 是否可用 |
canvas_hash / webgl_hash | Canvas / WebGL 渲染结果摘要,用于快速比对是否同一渲染环境 |
is_headless | UA 是否包含 HeadlessChrome |
sdk_version | SDK 构建版本 |
返回码
| code | 含义 | 处理建议 |
|---|---|---|
200 | 正常 | — |
400 | 请求参数不合法 | 检查必填字段与类型 |
411 | 请求频率过高 | 降频后重试 |
5501 | 时间戳过期 | 校准服务器时间 |
5502 | 参数缺失或格式错误 | 对照参数表检查 |
5505 | nonce 格式错误或重复 | 每次请求生成新的 32 位随机串 |
5506 | 应用标识无效 | 确认 app_id |
5507 | token 为空 | 检查客户端是否成功获取 token |
5508 | 签名错误 | 核对排序与拼接规则 |
5509 | 应用已停用 | 联系管理员 |
5510 | 配额或调用次数超限 | 联系管理员调整配额 |
5511 | 重复请求 | 本服务默认返回 cached=true,不报错 |
5512 | token 非法或过期 | 重新获取 token 后重试一次 |
5514 | 处理超时 | 可按退避策略重试 |
5515 | 处理失败 | 重试仍失败请携带 task_id 反馈 |
5521 | 可重试失败 | 稍后重试 |
业务侧约定
- 业务后端用返回的
device_id与version拼出fp头,再按现有方式加密存储、请求时解密封装;存储层无需改动。 - 接口始终返回
device_id,采集不完整的设备同样可用;如需让识别更稳定,可在业务关键路径上重新获取一次 token。 - token 获取失败(
202)时本次不送检,不影响业务主流程。 - 服务不可用时沿用本地已有标识,避免阻塞下单、登录等主链路。