# @fingerprint/react 中文文档

规范地址：https://npmcn.com/package/%40fingerprint/react/

版本：3\.3\.0
npm 元数据更新时间：2026-10-26T14:45:52.118Z
中文译文更新时间：2026-11-14T18:47:26.058Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fingerprint/react
原文对照：https://npmcn.com/package/%40fingerprint/react/?lang=original
项目主页：https://github.com/fingerprintjs/react#readme
源码仓库：https://github.com/fingerprintjs/react

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：80.9 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18 \<20
- 首次发布：2026-01-27T17:00:23.544Z
- 最新版本发布：2026-10-26T14:45:51.651Z
- 近 30 天下载量：422152（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

指纹反射 SDK

## 安装

```sh
npm install @fingerprint/react
```

也可以使用：`pnpm add @fingerprint/react`、`yarn add @fingerprint/react`、`bun add @fingerprint/react`

## README

[![Fingerprint logo](https://fingerprintjs.github.io/home/resources/logo_dark.svg)](https://fingerprint.com/)

[![CI badge](https://github.com/fingerprintjs/react/actions/workflows/release.yml/badge.svg)](https://github.com/fingerprintjs/react/actions/workflows/release.yml) [![coverage](https://fingerprintjs.github.io/react/coverage/badges.svg)](https://fingerprintjs.github.io/react/coverage/) [![Current NPM version](https://img.shields.io/npm/v/@fingerprint/react.svg)](https://www.npmjs.com/package/@fingerprint/react) [![Monthly downloads from NPM](https://img.shields.io/npm/dm/@fingerprint/react.svg)](https://www.npmjs.com/package/@fingerprint/react) [![MIT license](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/license/MIT) [![Discord server](https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white)](https://discord.com/invite/39EpE2neBg) [![Documentation](https://img.shields.io/badge/-Documentation-green)](https://fingerprintjs.github.io/react/)

# 指纹反射

指纹是一个设备智能平台,提供行业领先的准确性. 指纹反射 SDK 是方便的集成方式 **[指纹](https://fingerprint.com/)** 输入您的反应应用程序。 也与"Next.js"和"Preact"兼容. 参见应用程序演示 [实例](https://github.com/fingerprintjs/react/tree/main/examples) 文件夹.

## 目录

-   [指纹反射](https://npmcn.com/package/%40fingerprint/react/#readme-fingerprint-react)
    -   [目录](https://npmcn.com/package/%40fingerprint/react/#readme-table-of-contents)
    -   [所需资源](https://npmcn.com/package/%40fingerprint/react/#readme-requirements)
    -   [安装](https://npmcn.com/package/%40fingerprint/react/#readme-installation)
    -   [开始](https://npmcn.com/package/%40fingerprint/react/#readme-getting-started)
        -   [1\. 将应用程序(或组件)包入 `<FingerprintProvider>`。 。 。 .](https://npmcn.com/package/%40fingerprint/react/#readme-1-wrap-your-application-or-component-in-fingerprintprovider)
        -   [2\. 使用 `useVisitorData()` 在组件中勾勾以识别访客](https://npmcn.com/package/%40fingerprint/react/#readme-2-use-the-usevisitordata-hook-in-your-components-to-identify-visitors)
    -   [链接和标记信息](https://npmcn.com/package/%40fingerprint/react/#readme-linking-and-tagging-information)
    -   [处理错误](https://npmcn.com/package/%40fingerprint/react/#readme-error-handling)
    -   [API 参考](https://npmcn.com/package/%40fingerprint/react/#readme-api-reference)
    -   [版本支持](https://npmcn.com/package/%40fingerprint/react/#readme-version-support)
    -   [支助和反馈](https://npmcn.com/package/%40fingerprint/react/#readme-support-and-feedback)
    -   [许可证](https://npmcn.com/package/%40fingerprint/react/#readme-license)

## 所需资源

-   反应 18 或 19
-   预告用户:预告10.3或以上
-   Next.js用户:Next.js 13.1或更高
-   对于类型脚本用户:类型脚本 4.8 或更高

> \[注\] 此软件包假设您有指纹订阅或试用, 它不符合 [开源指纹JS](https://github.com/fingerprintjs/fingerprintjs)。见我们的文件,以便更多地了解 [指纹和开源指纹JS之间的差异](https://fingerprint.com/github/)。 。 。 .

## 安装

使用 [无](https://npmjs.org/)数字 :

```sh
npm install @fingerprint/react
```

使用 [线条](https://yarnpkg.com/)数字 :

```sh
yarn add @fingerprint/react
```

使用 [小时](https://pnpm.js.org/)数字 :

```sh
pnpm add @fingerprint/react
```

## 开始

为了识别访客,你需要一个指纹账户(你可以) [免费报名](https://dashboard.fingerprint.com/signup)) (中文(简体) ). 要得到你的 API 密钥并开始,看看 [指纹快速启动指南](https://docs.fingerprint.com/docs/quick-start-guide)。 。 。 .

### 1\. 将应用程序(或组件)包入 `<FingerprintProvider>`。 。 。 .

-   设定 `apiKey` 切入指纹 [公共 API 密钥](https://dashboard.fingerprint.com/api-keys)。 。 。 .
-   设定 `region` 如果您选择了非全局性 [区域](https://docs.fingerprint.com/docs/regions) 登记期间.
-   设定 `endpoints` 如果您正在使用 [我们的代理集成之一 提高准确性](https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers) 游客身份认证的有效性.
-   你可以使用所有的东西 [启动选项](https://docs.fingerprint.com/reference/js-agent-start-function#start-options) 在 JavaScript 代理服务器中可用 `start()` 函数.
-   缓存默认已禁用 。 要启用缓存, 请通过 JavaScript 代理 [`cache` 开始选项](https://docs.fingerprint.com/reference/js-agent-start-function#cache)。 。 。 .

```jsx
// src/index.js
import React from 'react'
import ReactDOM from 'react-dom/client'
import { FingerprintProvider } from '@fingerprint/react'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('root'))

// <FingerprintProvider /> supports the same options as `start()` function.
root.render(
  <FingerprintProvider
    apiKey='PUBLIC_API_KEY'
    cache={{ storage: 'sessionStorage', duration: 3600 }}
  >
    <App />
  </FingerprintProvider>
)
```

### 2\. 使用 `useVisitorData()` 在组件中勾勾以识别访客

```jsx
// src/App.js
import React from 'react'
import { useVisitorData } from '@fingerprint/react'

function App() {
  const { isLoading, error, isFetched, data } = useVisitorData()

  if (isLoading) {
    return <div>Loading...</div>
  }
  if (error) {
    return <div>An error occurred: {error.message}</div>
  }

  if (isFetched) {
    return <div>Welcome {data.visitor_id}!</div>
  }
  
  return null
}

export default App
```

这个 `useVisitorData` 钩子还返回 a `getData` 用于命令调用 API 的方法.

两者 `useVisitorData` 财务报告和审定财务报表 `getData` 接受所有 [获取选项](https://docs.fingerprint.com/reference/js-agent-get-function#get-options) 在 JavaScript 代理服务器中可用 `get` 函数.

返回的 v4 访问者数据在 snake case 中使用原始响应字段名称, 例如 `visitor_id` 财务报告和审定财务报表 `event_id`。 。 。 .

```jsx
// src/App.js
import React, { useState } from 'react'
import { useVisitorData } from '@fingerprint/react'

function App() {
  const { isLoading, error, getData } = useVisitorData(
    { immediate: false }
  )
  const [email, setEmail] = useState('')

  if (isLoading) {
    return <div>Loading...</div>
  }
  if (error) {
    return <div>An error occurred: {error.message}</div>
  }

  return (
    <div>
      <form
        onSubmit={(e) => {
          e.preventDefault()
          getData()
            .then((data) => {
              // Do something with the visitor data, for example,
              // append visitor data to the form data to send to your server
              console.log(data.visitor_id)
            })
            .catch((error) => {
              // Handle error
            })
        }}
      >
        <label htmlFor='email'>Email:</label>
        <input
          type='email'
          value={email}
          onChange={(e) => setEmail(e.currentTarget.value)}
        />
        <button type='submit'>Subscribe</button>
      </form>
    </div>
  )
}

export default App
```

-   你可以通过 `{ immediate: false }` 以禁用自动识别和呼叫 `getData` 手动取而代之.
-   默认( E)`{ immediate: true }`),钩子在挂起后自动识别访问者,只要其请求选项改变。 变化 `immediate` 从 `false` 改为 `true` 还开始一个带有最新选项的识别请求.
-   参见 [示例文件夹](https://npmcn.com/package/%40fingerprint/react/examples/)。 。 。 .
-   看我们的 [使用大小写](https://demo.fingerprint.com/) 页面 [开源](https://github.com/fingerprintjs/fingerprintjs-pro-use-cases) 利用指纹发现欺诈和简化用户经验的现实世界实例.

## 链接和标记信息

指纹识别提供的访问者身份证明与您已经了解的用户信息,例如账户身份证明,订单身份证明等,特别有用. 更多地了解《公约》的各种应用 `linkedId` 财务报告和审定财务报表 `tags`,参见 [链接和标记信息](https://docs.fingerprint.com/docs/tagging-information)。 。 。 .

将访客身份与您的数据联系起来 `linkedId` 或者说 `tags` 选项对象的参数 `useVisitorData()` 钩子或 `getData` 函数 :

```jsx
// ...
function App() {
  const { isLoading, error, getData } = useVisitorData({
    linkedId: 'user_1234',
    tags: {
      userAction: 'login',
      analyticsId: 'UA-5555-1111-1',
    },
  })
}
// ...
```

> \[注\] 这个 `tag` 选项为偏好 `tags`。 。 。 . `tag` 仍然有效,但如果两者都提供, `tags` 以优先为准.

## 处理错误

这个 `getData` 函数直接从 JS 代理中丢出错误而不修改它们。 见 [JS 代理处理错误](https://docs.fingerprint.com/reference/js-agent-error-handling) 更多细节.

## API 参考

见全 [生成 API 引用](https://fingerprintjs.github.io/react/)。 。 。 .

## 版本支持

| SDK 主要版本 | JS代理版本 | 状态 | 支持结束 |
| --- | --- | --- | --- |
| v3.x (当前) | [页:1](https://docs.fingerprint.com/reference/js-agent) | 支助 | \- 说吧 |
| v1.x-v2.x (英语) | [页:1](https://docs.fingerprint.com/reference/v3/javascript-agent) | 已折旧(仅限安全处理)。 见 [移徙指南](https://docs.fingerprint.com/docs/react#migration-guide-for-react-sdk-v3-0-0)。 。 。 . | 待定 |

## 支助和反馈

提问或提供反馈,使用 [问题](https://github.com/fingerprintjs/react/issues)如果您需要私人支援,请发电子邮件至 `oss-support@fingerprint.com`。 。 。 .

## 许可证

这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/fingerprintjs/react/blob/main/LICENSE) 需要更多信息的文件.

## 常见问题

### @fingerprint/react 是什么？

指纹反射 SDK

### 如何安装 @fingerprint/react？

在项目目录运行 npm install @fingerprint/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18 \<20）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fingerprint/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fingerprint/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fingerprint/react 可以商用吗？

@fingerprint/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fingerprint/react 的下载量有多少？

根据 npm 官方下载统计，@fingerprint/react 在 2026/10/15 – 2026/11/13 这 30 天内被下载 422,152 次，日均约 14,072 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fingerprint/react 还在维护吗？

最新版本 3\.3\.0 发布于 2026/10/26（19 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/01/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。