API REFERENCE · V1

浏览器指纹 API 文档

以下描述当前本站同源接口。服务器不会替你采集 Canvas、WebGL 或其他只能在浏览器中读取的信号。

端点与参数

方法	路径	约定
`GET`	`/api/fingerprint/schema`	版本、基础与深度采集字段、保留时间。
`POST`	`/api/fingerprint/session`	请求 { tier: "basic" \| "advanced" }；返回 sessionId、nonce、expiresAt 和版本。
`POST`	`/api/fingerprint/collect`	提交 sessionId、nonce、相同 tier 和 components 数组；返回 FingerprintReport。
`GET`	`/api/fingerprint/report/{id}`	获取未过期的报告。报告 ID 是访问凭据。
`DELETE`	`/api/fingerprint/report/{id}`	删除报告；返回 { deleted: true }。
`POST`	`/api/fingerprint/compare`	请求 { leftId, rightId }；返回各组件 stable、changed、added 或 missing 的比较。

采集流程示例

仅在用户了解并同意提交内容后执行上传。此示例只提交一个 UA 字段，用于演示协议，不等同于完整检测。

// Run from a page on the same origin as BrowserCheak.
const schema = await fetch('/api/fingerprint/schema').then(r => r.json());

// This minimal example uploads only a User Agent observation.
const sessionResponse = await fetch('/api/fingerprint/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tier: 'basic' })
});
if (!sessionResponse.ok) throw new Error('Session request failed');
const session = await sessionResponse.json();

const response = await fetch('/api/fingerprint/collect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionId: session.sessionId,
    nonce: session.nonce,
    tier: 'basic',
    components: [{
      key: 'navigator', label: 'Browser', version: 1,
      tier: 'basic', status: 'ok', confidence: 'medium',
      durationMs: 0, value: { userAgent: navigator.userAgent }
    }]
  })
});
if (!response.ok) throw new Error('Report request failed');
const report = await response.json();
// report.id, createdAt, expiresAt, components, scores, findings, transport
// Missing signals in this minimal example limit report interpretation.

组件与返回值

组件包含 key、label、version、tier、status、value、durationMs 和 confidence。status 可以是 ok、protected、unsupported、blocked、timeout 或 error。confidence 为 high、medium、low 或 unknown。使用 schema 端点获取允许的组件键。

报告包含 id、createdAt、expiresAt、tier、schemaVersion、ruleVersion、scores、automationLevel、confidence、summary、findings、components 与 transport。scores 是当前规则的启发式指标，不是代表性人群唯一性或真实追踪概率。

保留、限额与访问

默认每个来源的全部 API 合计每分钟 60 次、每 24 小时 1,000 次，最多同时执行 4 个请求。创建会话与提交报告各限每分钟 6 次、每 24 小时 60 次；每个来源最多保留 3 个未提交会话。会话 10 分钟后过期，成功提交后 nonce 失效。IPv6 按 /64 网段共用配额。

提交报告的整个请求体默认最多 512 KiB，其他写入请求最多 4 KiB；只接受未压缩的 JSON，上传限时 10 秒。最多提交 20 个组件，不接受重复或未知组件键；Canvas PNG data URL 仍限 250,000 个字符。报告全站最多 500 份，序列化内容合计最多 32 MiB；容量不足时拒绝新增报告，删除或过期后释放空间。

网络概览默认每来源每分钟 12 次、每 24 小时 300 次；DNS 会话为 10 次和 120 次，结果轮询为 40 次和 480 次；报告读写为 30 次和 500 次，对比为 10 次和 100 次。配额按固定时间窗口计数，以上为默认值，可由部署方调整；以响应头与当前服务配置为准。收到 429 后请遵循 Retry-After，不要自动连续重试。

当前实现会保留提交的组件值，包括可选的 Canvas 图像与音频样本。报告 ID 可用于读取、比较和删除报告，请仅向需要的人分享。数据保存在单个服务进程内存中，最长 24 小时，多进程之间不共享，重启可能提前清空；限流计数也保存在单进程内存并会在重启时重置。

错误响应

400：JSON、等级或组件无效；401：会话、nonce 无效、已使用或过期；404：报告不存在或过期；408：上传超时；413：请求体或画布超过限制；415：不支持的媒体类型或压缩编码；429：频率、配额或并发超限；503：存储容量或网络查询服务暂时不可用。429 和容量限制响应附带 Retry-After；X-RateLimit-Limit、Remaining、Reset 表示配额与重置时间。请求方应检查 HTTP 状态，不应将失败结果视为安全检测通过。