fingerprintjs/node-sdk
GitHub: fingerprintjs/node-sdk
Fingerprint Node.js SDK 是用于与 Fingerprint 设备智能平台 Server API 交互的官方 TypeScript 库，帮助开发者在服务端实现访客识别、事件查询、Webhook 验证和数据管理。
Stars: 27 | Forks: 11
# Fingerprint 服务端 Node.js SDK
[Fingerprint](https://fingerprint.com) 是一个提供业界领先准确性的设备智能平台。
Fingerprint 服务端 Node SDK 是一种从你的 Node 应用程序与 Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) 进行交互的简便方法。你可以搜索、更新或删除识别事件。
## 要求
TypeScript 支持：
- TypeScript 4.5.5 或更高版本
支持的运行时：
- Node.js 18 LTS 或更高版本（我们支持所有[生命周期结束前的 Node LTS 版本](https://nodejs.dev/en/about/releases/)）。
- Deno 和 Bun 可能可以运行，但未经过主动测试。
- “Edge”运行时可能在经过某些修改后可以运行，但未经过主动测试。
查看“edge”运行时的兼容性
通过替换依赖 Node API 的 SDK 内置 `fetch` 函数，可以使用运行时的原生 `fetch` 函数，使此 SDK 能够与不完全支持所有 Node API 的 JavaScript “edge”运行时兼容，例如 [Vercel Edge Runtime](https://edge-runtime.vercel.app/) 或 [Cloudflare Workers](https://developers.cloudflare.com/workers/)。
要使其工作，请在正确绑定的情况下将该函数传入构造函数中：
const client = new FingerprintServerApiClient({
region: Region.EU,
apiKey: apiKey,
fetch: fetch.bind(globalThis),
})
## 如何安装
使用你最喜欢的包管理器安装该包：
- NPM:
npm i @fingerprint/node-sdk
- Yarn:
yarn add @fingerprint/node-sdk
- pnpm:
pnpm i @fingerprint/node-sdk
## 入门指南
初始化客户端实例并使用它来发起 API 请求。你需要指定你的 Fingerprint [Secret API key](https://dev.fingerprint.com/docs/quick-start-guide#4-get-smart-signals-to-your-server) 以及你的 Fingerprint 工作区的区域。
```
import {
FingerprintServerApiClient,
Region,
} from '@fingerprint/node-sdk'
const client = new FingerprintServerApiClient({
apiKey: '
',
region: Region.Global,
})
// Get visit history of a specific visitor
client.searchEvents({ visitor_id: '' }).then((visitorHistory) => {
console.log(visitorHistory)
})
// Get a specific identification event
client.getEvent('').then((event) => {
console.log(event)
})
// Get an event with a ruleset evaluation
client.getEvent('', { ruleset_id: '' }).then((event) => {
console.log(event.rule_action?.type) // 'allow' or 'block'
})
// Search for identification events
client
.searchEvents({
limit: 10,
// pagination_key: previousSearchResult.pagination_key,
suspect: true,
})
.then((events) => {
console.log(events)
})
```
有关更详细的示例，请参阅 [示例](https://github.com/fingerprintjs/node-sdk/tree/main/example) 文件夹。
### 错误处理
Server API 方法可能会抛出 `RequestError`。
在处理错误时，你可以这样进行检查：
```
import {
RequestError,
FingerprintServerApiClient,
TooManyRequestsError,
} from '@fingerprint/node-sdk'
const client = new FingerprintServerApiClient({
apiKey: '',
region: Region.Global,
})
// Handling getEvent errors
try {
const event = await client.getEvent(eventId)
console.log(JSON.stringify(event, null, 2))
} catch (error) {
if (error instanceof RequestError) {
console.log(error.responseBody) // Access parsed response body
console.log(error.response) // You can also access the raw response
console.log(`error ${error.statusCode}: `, error.message)
} else {
console.log('unknown error: ', error)
}
}
```
### Webhook
#### Webhook 类型
在处理来自 Fingerprint 的 [Webhook](https://dev.fingerprint.com/reference/posteventwebhook#/) 时，你可以将 payload 转换为内置的 `Event` 类型：
```
import { Event } from '@fingerprint/node-sdk'
const event = eventWebhookBody as unknown as Event
```
#### Webhook 签名验证
Enterprise 计划的客户可以启用 [Webhook 签名](https://dev.fingerprint.com/docs/webhooks-security)，以加密方式验证传入 Webhook 的真实性。
此 SDK 提供了一个实用方法，用于验证传入 Webhook 请求的 HMAC 签名。
要了解更多信息，请参阅 [example/validateWebhookSignature.mjs](example/validateWebhookSignature.mjs) 或阅读 [API 参考](https://fingerprintjs.github.io/node-sdk/functions/isValidWebhookSignature.html)。
### 密封结果
此 SDK 提供了解密[密封结果](https://docs.fingerprint.com/docs/sealed-client-results)的实用方法。
使用以下代码解封结果：
```
import { unsealEventsResponse, DecryptionAlgorithm } from '@fingerprint/node-sdk'
const sealedData = process.env.BASE64_SEALED_RESULT
const decryptionKey = process.env.BASE64_KEY
const unsealedData = await unsealEventsResponse(Buffer.from(sealedData, 'base64'), [
{
key: Buffer.from(decryptionKey, 'base64'),
algorithm: DecryptionAlgorithm.Aes256Gcm,
},
])
console.log(JSON.stringify(unsealedData, null, 2))
```
要了解更多信息，请参阅位于 [example/unsealResult.mjs](./example/unsealResult.mjs) 中的示例。
### 删除访客数据
Enterprise 计划的客户可以[删除与特定访客关联的所有数据](https://dev.fingerprint.com/reference/deletevisitordata)，以符合隐私法规。请参阅 [example/deleteVisitor.mjs](https://github.com/fingerprintjs/node-sdk/tree/main/example/deleteVisitor.mjs) 或 [API 参考](https://fingerprintjs.github.io/node-sdk/classes/FingerprintServerApiClient.html#deleteVisitorData)。
## API 参考
请参阅完整的 [API 参考](https://fingerprintjs.github.io/node-sdk/)。
## 语义化版本控制
* 此仓库中对**类型**的更改被视为非破坏性更改，通常作为 PATCH 或 MINOR semver 版本发布（否则每个 schema 的添加都会成为主版本升级）。
* 强烈建议你将包版本锁定到特定的 PATCH 版本，并在升级时期望类型可能在任何版本之间发生升级。
* Node SDK 的运行时（非类型相关的）公共 API 仍然严格遵循 semver 规范。
## 支持与反馈
要报告问题、提出问题或提供反馈，请使用 [Issues](https://github.com/fingerprintjs/node-sdk/issues)。如果你需要私人支持，可以通过 [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com) 给我们发送电子邮件。
## 许可证
本项目基于 [MIT 许可证](https://github.com/fingerprintjs/node-sdk/tree/main/LICENSE) 授权。标签：C2日志可视化, Fingerprint, GNU通用公共许可证, MITM代理, Node.js, NPM包, OSV-Scalibr, Server API, TypeScript, 反欺诈, 后端开发, 安全插件, 指纹识别, 授权管理, 接口封装, 暗色界面, 机器人检测, 浏览器指纹, 用户追踪, 网络安全, 设备指纹, 设备智能, 访客识别, 隐私保护, 风控系统
