# @fingerprintjs/fingerprintjs-pro-spa 中文文档 规范地址：https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/ 版本：1\.3\.3 npm 元数据更新时间：2025-09-15T15:55:06.491Z 中文译文更新时间：2026-11-14T18:48:50.544Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fingerprintjs/fingerprintjs-pro-spa 原文对照：https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/?lang=original 项目主页：https://github.com/fingerprintjs/fingerprintjs-pro-spa#readme 源码仓库：https://github.com/fingerprintjs/fingerprintjs-pro-spa ## 关键信息（来自 npm 元数据） - 包体积（解压后）：57.3 kB，6 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：2 个 - 首次发布：2022-02-16T07:39:42.793Z - 最新版本发布：2025-09-15T15:55:06.285Z - 近 30 天下载量：765028（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：29（近 12 个月 0 个） ## 中文简介 指纹JS Pro JavaScript 单页应用程序代理 ## 安装 ```sh npm install @fingerprintjs/fingerprintjs-pro-spa ``` 也可以使用：`pnpm add @fingerprintjs/fingerprintjs-pro-spa`、`yarn add @fingerprintjs/fingerprintjs-pro-spa`、`bun add @fingerprintjs/fingerprintjs-pro-spa` ## README [![Fingerprint logo](https://fingerprintjs.github.io/home/resources/logo_dark.svg)](https://fingerprint.com/) [![Current NPM version](https://img.shields.io/npm/v/@fingerprintjs/fingerprintjs-pro-spa.svg)](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa) [![coverage](https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/badges.svg)](https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/) [![Monthly downloads from NPM](https://img.shields.io/npm/dm/@fingerprintjs/fingerprintjs-pro-spa.svg)](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa) [![MIT license](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/licenses/MIT) [![Discord server](https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white)](https://discord.gg/39EpE2neBg) [![Documentation](https://img.shields.io/badge/-Documentation-green)](https://fingerprintjs.github.io/fingerprintjs-pro-spa) # SPA 指纹 [指纹](https://fingerprint.com/) 是一个设备智能平台,提供行业领先的准确性 这个库是一个框架不可知的包装 围绕指纹 Pro [Java 脚本代理](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro),添加多个内置缓存机制,并设置了推荐的默认设置. - 如果你只需要指纹 [JS代理人](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro) 无需缓冲,你可以直接使用. - 如果你想要一个特定框架的集成, 我们有专门的SDK用于 [反应( 包括 Next, Preact)](https://github.com/fingerprintjs/fingerprintjs-pro-react), (中文(简体) ), [阴道](https://github.com/fingerprintjs/fingerprintjs-pro-vue), (中文(简体) ), [丝绒](https://github.com/fingerprintjs/fingerprintjs-pro-svelte) 财务报告和审定财务报表 [角质](https://github.com/fingerprintjs/fingerprintjs-pro-angular)。 。 。 . - 如果您拥有一个需要缓存的单页网页应用程序,但比特定框架的SDK提供更低级的代理控制,这个库是适合您的. > \[注\] 这个库假设你有一个指纹 Pro订阅或测试, 它不符合 [来源可用指纹JS](https://github.com/fingerprintjs/fingerprintjs)。见我们的文件,以便更多地了解 [指纹Pro和指纹JS之间的差异](https://dev.fingerprint.com/docs/identification-vs-fingerprintjs)。 。 。 . ## 目录 - [所需资源](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-requirements) - [安装](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-installation) - [开始](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-getting-started) - [缓存](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-caching) - [支助和反馈](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-support-and-feedback) - [文档](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-documentation) - [许可证](https://npmcn.com/package/%40fingerprintjs/fingerprintjs-pro-spa/#readme-license) ## 所需资源 - 对于 TypeScript 用户: Typescript 4.5 以上 ## 安装 使用 [无](https://npmjs.org/)数字 : ```sh npm install @fingerprintjs/fingerprintjs-pro-spa ``` 使用 [线条](https://yarnpkg.com/)数字 : ```sh yarn add @fingerprintjs/fingerprintjs-pro-spa ``` 使用 [小时](https://pnpm.js.org/)数字 : ```sh pnpm add @fingerprintjs/fingerprintjs-pro-spa ``` ## 开始 ### 1\. 获取指纹 Pro 公共 API 密钥 为了识别访客,你需要一个指纹 Pro账户(你可以) [免费报名](https://dashboard.fingerprint.com/signup/)) (中文(简体) ). - 转到 **指纹板** > 翻译: **应用程序设置** > 翻译: [**API 密钥**](https://dashboard.fingerprint.com/api-keys)。 。 。 . - 找到您的公共 API 密钥 . ### 2\. 创建客户端 创建一个 `FpjsClient` 在提交或初始化您的申请之前。 你只应该有一个客户的例子。 您需要根据您选择的区域和活动集成指定您的公共 API 密钥和其他配置选项 . ```js import { FpjsClient, FingerprintJSPro } from '@fingerprintjs/fingerprintjs-pro-spa' const fpjsClient = new FpjsClient({ // You can also pass these options later in `.init()` method loadOptions: { apiKey: '', endpoint: [ //'https://metrics.yourwebsite.com', FingerprintJSPro.defaultEndpoint, ], scriptUrlPattern: [ // 'https://metrics.yourwebsite.com/web/v//loader_v.js', FingerprintJSPro.defaultScriptUrlPattern, ], // region: "eu" }, }) ``` > \[注\] 您必须提供 `loadOptions` 包含您的公共 API 密钥, 无论是在构建器中还是在 `init` 方法。 否则SDK会出错的 您可以在这里更多地了解不同的负载选项 [JS代理文件](https://dev.fingerprint.com/reference/load-function)。 。 。 . ### 3\. 启动联合来文代理人 在你开始向指纹 Pro API提出身份请求之前,你需要初始化JS探员. 此从 Fingerprint CDN 下载最新的客户端侧逻辑 。 打电话 `init()` 之前 `getVisitorData()` 避免出错的方法. ```js // with async/await await fpjsClient.init() const visitorData = await fpjsClient.getVisitorData() // with promises const visitorData = fpjsClient.init().then(() => { return fpjsClient.getVisitorData() }) ``` 你也可以通过 `loadOptions` 输入 `init` 方法在这里。 它们将与转给建筑商的选项合并. ```js await fpjsClient.init({ apiKey: '', // endpoint: ["", FingerprintJSPro.defaultEndpoint], // scriptUrlPattern: ["", FingerprintJSPro.defaultScriptUrlPattern], // region: "eu" }) ``` ### 4\. 确定来访者 这个 `getVisitorData` 根据请求返回访客身份数据 [选项](https://dev.fingerprint.com/reference/get-function#get-options)。 。 。 . 设定 `ignoreCache` 改为 `true` 以调用 API ,即使数据存在于缓存中. ```js // with async/await const visitorData = await fpjsClient.getVisitorData({ extendedResult: true }, false) // with promises const visitorData = fpjsClient.getVisitorData({ extendedResult: true }).then((visitorData) => { // use visitor data in your fraud prevention logic checkIfFingerprintIsFraudulent(visitorData.visitorId) // this method is just an example, this SDK doesn't actually supply it }) ``` 见 [JS探员 API参考](https://dev.fingerprint.com/reference/javascript-agent) 更多细节. #### 链接和标记信息 这个 `visitorId` 由指纹识别提供,与您已经了解的用户信息相结合,例如账户ID,订单ID等,尤其有用. 更多地了解《公约》的各种应用 `linkedId` 财务报告和审定财务报表 `tag`,参见 [链接和标记信息](https://dev.fingerprint.com/docs/tagging-information)。 。 。 . ```js const visitorData = await fpjsClient.getVisitorData({ linkedId: 'user_1234', tag: { userAction: 'login', analyticsId: 'UA-5555-1111-1', }, }) ``` ## 缓存 指纹 Pro 使用量按API呼叫计费. 为了避免不必要的API呼叫,缓存识别结果是一种好的做法. SDK提供了三种将访客数据从盒子中缓存的方法: - 会话存储( 默认) - `sessionStorage` - 本地存储 - `localStorage` - 记忆 - `memory` - 没有缓存 - `nocache` 您可以指定 `cacheLocation` 选项 `FpjsClient`数字 : ```js const fpjsClient = new FpjsClient({ loadOptions: { apiKey: 'your-fpjs-public-api-key', }, cacheLocation: 'localstorage', // You can also use the provided TypeScript enum // cacheLocation: CacheLocation.LocalStorage }) ``` 缓存密钥基于组合 _获取选项_。例如,API对电话的响应 `extendedResult: true` 财务报告和审定财务报表 `extendedResult: false` 独立存储. > \[注\] 如果您使用来自 [`extendedResult`](https://dev.fingerprint.com/reference/get-function#extendedresult)注意你的隐蔽策略 一些领域,例如, `ip` 或者说 `lastSeenAt`,可能会随着时间而改变 同一访客. 您可以忽略特定 API 调用和使用的缓存结果 `{ ignoreCache: true }`数字 : ```js const visitorData = await fpjsClient.getVisitorData({ ignoreCache: true }) ``` 检查您是否使用返回的缓存获取了响应 `cacheHit` 旗帜 : ```js const { cacheHit, ...visitorData } = await fpjsClient.getVisitorData() ``` 使用 `getVisitorDataFromCache` 从缓存直接获取响应 : ```js // Checks if request matching given options is present in cache await fpjsClient.isInCache({ extendedResult: true }) // Returns cached visitor data based on the request options, or undefined if the data is not present in cache const cachedResult = await fpjsClient.getVisitorDataFromCache({ extendedResult: true }) ``` 您也可以使用下面描述的您的自定义缓存执行 . ### 创建自定义缓存 SDK可以使用您应用程序内执行的自定义缓存存储 。 当不同的数据存储在您的环境中更方便时,例如混合移动应用程序,此功能是有用的. 您可以为 `cache` 用于执行以下功能的 SDK 配置的属性。 所有函数都可以返回一个承诺或静态值. | 签署 | 返回类型 | 说明 | | --- | --- | --- | | `get(key)` | 答应 | 以指定的密钥返回缓存中的项目,或 `undefined` 如果找不到的话 | | `set(key: string, object: any)` | 承诺或无效 | 将项目设置在缓存中 | | `remove(key)` | 承诺或无效 | 从指定的密钥的缓存中删除单个项目, 如果未找到此项目, 则取消 | | `allKeys()` | 承诺 < string \[\] > 或字符串 \[\] | 返回所有密钥的列表。 默认情况下,我们使用的密钥前缀为 `@fpjs@client@` 但是,当你创建 FpjsClient 时,您可以通过自定义前缀作为选项 | > \[注\] 这个 `cache` 属性优先于 `cacheLocation` 如果两者都设定好了。 如果发生这种情况, 在控制台上显示警告 . 我们出口内部 `InMemoryCache`, (中文(简体) ), `LocalStorageCache`, (中文(简体) ), `SessionStorageCache`,以及 `CacheStub` 执行,因此如果您愿意,您可以将这些自定义缓存绕过这些执行. ### 缓存时间 使用 `cacheTimeInSeconds` 客户端构造器设置自定义缓存时间选项 。 为了确保识别的准确性,我们建议在24小时之内不缓存访客数据。 如果超过86400(60 x 60 x 24),则 `FpjsClient` 构造器会丢出一个错误 . ## 支助和反馈 报告问题、提问或反馈,请使用 [问题](https://github.com/fingerprintjs/fingerprintjs-pro-spa/issues)。如果你需要私人支持,你可以发电子邮件给我们 [oss- support@指印.com](mailto:oss-support@fingerprint.com)。 。 。 . ## 文档 此库使用 [指纹 Pro](https://fingerprint.com/github/) 在引擎盖下. - 为了了解更多的指纹 Pro读了我们 [产品文档](https://dev.fingerprint.com/docs)。 。 。 . - 为了多了解这个SDK,有一个 [Typedoc 生成的 SDK 引用](https://fingerprintjs.github.io/fingerprintjs-pro-spa) 可用. ## 许可证 这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/fingerprintjs/fingerprintjs-pro-spa/blob/master/LICENSE) 文档以获取更多信息. ## 常见问题 ### @fingerprintjs/fingerprintjs-pro-spa 是什么？ 指纹JS Pro JavaScript 单页应用程序代理 ### 如何安装 @fingerprintjs/fingerprintjs-pro-spa？ 在项目目录运行 npm install @fingerprintjs/fingerprintjs-pro-spa，或使用 pnpm add / yarn add / bun add。 ### @fingerprintjs/fingerprintjs-pro-spa 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fingerprintjs/fingerprintjs-pro-spa 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @fingerprintjs/fingerprintjs-pro-spa 可以商用吗？ @fingerprintjs/fingerprintjs-pro-spa 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fingerprintjs/fingerprintjs-pro-spa 的下载量有多少？ 根据 npm 官方下载统计，@fingerprintjs/fingerprintjs-pro-spa 在 2026/10/15 – 2026/11/13 这 30 天内被下载 765,028 次，日均约 25,501 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fingerprintjs/fingerprintjs-pro-spa 还在维护吗？ 最新版本 1\.3\.3 发布于 2025/09/15（1\.2 年前）；至今共发布 29 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/02/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。