FingerprintJS API 完全指南：从安装到高级使用

霍曙柏

于 2025-06-01 09:06:03 发布

阅读量430

点赞数 4

本文链接：https://blog.csdn.net/gitblog_00972/article/details/148361411

版权

FingerprintJS API 完全指南：从安装到高级使用

fingerprintjs Browser fingerprinting library. Accuracy of this version is 40-60%, accuracy of the commercial Fingerprint Identification is 99.5%. V4 of this library is BSL licensed. 项目地址: https://gitcode.com/gh_mirrors/fi/fingerprintjs

前言

在现代Web开发中，设备指纹识别技术扮演着越来越重要的角色。FingerprintJS作为一款优秀的开源浏览器指纹识别库，能够帮助开发者准确识别访问者身份。本文将全面解析FingerprintJS的API使用方式，从基础安装到高级配置，带你深入了解这一强大工具。

安装方式详解

FingerprintJS提供了多种灵活的安装方案，适应不同开发环境和需求。

浏览器原生ES模块方案

这是最推荐的现代浏览器使用方式，采用异步加载不影响页面性能：

<script>
  // 应用启动时初始化代理
  const fpPromise = import('指纹库CDN地址')
    .then(FingerprintJS => FingerprintJS.load())

  // 在需要时获取访问者标识
  fpPromise
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId))
</script>

传统script标签方案

虽然简单但不推荐，因为会阻塞页面渲染：

<script src="指纹库IIFE版本地址"></script>
<script>
  var fpPromise = FingerprintJS.load()
  fpPromise
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId))
</script>

模块化方案

对于使用Webpack/Rollup等构建工具的项目：

npm install @fingerprintjs/fingerprintjs
# 或
yarn add @fingerprintjs/fingerprintjs

import FingerprintJS from '@fingerprintjs/fingerprintjs'

const fpPromise = FingerprintJS.load()

;(async () => {
  const fp = await fpPromise
  const result = await fp.get()
  console.log(result.visitorId)
})()

注意：NPM安装方式会以极低概率(0.1%)发送使用统计到服务器，包含库版本、HTTP头和客户端IP等信息。

核心API深度解析

FingerprintJS.load方法

FingerprintJS.load({ 
  delayFallback?: number, 
  debug?: boolean 
}): Promise<Agent>

这是初始化入口方法，建议在应用启动时尽早调用。

参数说明：

delayFallback：设置不支持requestIdleCallback浏览器的回退延迟(毫秒)，通常使用默认值即可
debug：设为true可在控制台输出调试信息

agent.get方法

agent.get(): Promise<GetResult>

获取访问者标识的核心方法，建议在真正需要时才调用，以提高识别准确率。

返回结果结构：

interface GetResult {
  visitorId: string  // 访问者唯一标识
  confidence: {      // 置信度评估
    score: number    // 0-1的置信分数
    comment?: string // 附加说明
  }
  components: {      // 组成指纹的各个组件
    [key: string]:
      { value: any, duration: number } |  // 成功时
      { error: any, duration: number }     // 出错时
  }
  version: string    // 算法版本号
}