# @didit-protocol/signals 中文文档

规范地址：https://npmcn.com/package/%40didit-protocol/signals/

版本：0\.1\.0
npm 元数据更新时间：2026-10-27T10:53:01.033Z
中文译文更新时间：2026-11-12T07:38:19.492Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40didit-protocol/signals
原文对照：https://npmcn.com/package/%40didit-protocol/signals/?lang=original
项目主页：https://docs.didit.me/
源码仓库：https://github.com/didit-protocol/sdk-web

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

- 包体积（解压后）：257 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：0 个
- 首次发布：2026-10-27T10:51:23.156Z
- 最新版本发布：2026-10-27T10:53:00.601Z
- 近 30 天下载量：3779（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Didit 设备信号和终端用户事件监视器

## 安装

```sh
npm install @didit-protocol/signals
```

也可以使用：`pnpm add @didit-protocol/signals`、`yarn add @didit-protocol/signals`、`bun add @didit-protocol/signals`

## README

# @ dodit- protocol/ 信号

用于浏览器的 Didit 设备信号和终端用户事件监测, 低于 5 KB 的 minfied and gziped.

-   **`submitEvent`** 向 Didit 发送签名、 登录、 失败的登录、 登录和任何其他终端用户事件 [事件监测](https://docs.didit.me/transaction-monitoring/events),与其核查和交易同一个人绑在一起.
-   **设备信号**:dit-fp-v2设备指纹被附在每批上. 页面退出如果其复合散列仍未完成,则使用可用的信号.
-   单独工作或与其他Didit SDK一起工作: [`@didit-protocol/sdk-web`](https://www.npmjs.com/package/@didit-protocol/sdk-web) 依赖于此软件包并再导出它,所以一个使用两个模块格式共享一个事件队列的应用程序. 独立的 CDN 和 脚本 tag 构建 每一个都带有自己的队列 .

## 安装

```bash
npm install @didit-protocol/signals
```

脚本标签( 曝光) `window.DiditSignals`:

```html
<script src="https://unpkg.com/@didit-protocol/signals/dist/didit-signals.umd.min.js"></script>
```

## 快开始

您的后端薄荷为您 API 密钥的签名人提供了短寿命监视符 :

```bash
curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor_data": "user_391", "allowed_event_categories": ["auth", "session"] }'
```

该页介绍事件:

```typescript
import { submitEvent, flush, configureEvents, DiditEventError } from "@didit-protocol/signals";

configureEvents({
  onError: (error: DiditEventError) => console.warn(error.type, error.eventIds, error.errors),
});

const eventId = submitEvent({
  monitoringToken, // from your backend - never ship an API key
  event: { category: "auth", actionType: "signup", payload: { method: "passkey" } },
});

// Optional: send right away (for example before a redirect you control) and read each outcome.
const result = await flush();
// { acceptedCount, replayedCount, rejectedCount, pendingCount, results: [{ eventId, outcome, eventUuid, status, score, error }] }
```

一个事件属于的人总是来自符号: Didit 覆盖请求中的任何主题 `vendor_data` 标记被刻出,并从请求中取出IP地址、用户代理和来源.

## 事件是如何发生的

| 何时 | 怎么样 |
| --- | --- |
| 25个活动在等待中 | 一个 `POST /v1/events/batch/` 马上 |
| 活动排队5秒后 | 所有等待的东西 |
| 页面被隐藏或关闭 | 符合页面退出预算的等待活动 `fetch` 财务报告和审定财务报表 `keepalive` 因此请求超过页面 |
| 你打电话 `flush()` | 等待的一切; 解决每个事件的结果 |

-   每个请求都带有 `X-Monitoring-Token` 页眉和设备指纹( e)`fingerprint_v2` 在体内加上它的匹配 `X-Didit-*` (原始内容存档于2018-10-21). headers.
-   每个事件都保留着它提交过的符号;不同符号的事件从不共享一个请求,所以在同一页上的签出和新签入从不混用人.
-   交付是最佳努力:页面关闭后会丢失内膜队列,浏览器可能会终止请求. 在页面退出时,浏览器允许64 KiB of `keepalive` 请求每页; 哪些不符合队列,如果页面返回,则发送. `sendBeacon` 不使用:它不能携带符号头.
-   退出请求从所收集的持久设备ID,浏览器信号和bot上下文开始. 如果WebCrypto hashing还悬而未决, `compositeHash` 已空并 `X-Didit-FP-Hash` 省略,而那些事件是在没有混合散列物的情况下储存的。 正常批次和 `flush()` 等待完整的指纹, 退出请求一旦准备好就使用 .
-   在网络出错,HTTP超时(408),限速(429),服务器出错(5xx)或无法读取的答案上,同样事件在10,20和40秒后再次发出,然后每分钟发一次. 他们重新发送字节的字节,所以一个已经存储的事件Didit回来作为 `replayed` 而不是被储存两次.
-   拒绝为最终决定,并通过 `onError` 和在 `flush()` 结果 :

| `error.type` | 含义 |
| --- | --- |
| `invalid_token` | 该令牌未知、被吊销、退出使用或绑入另一来源(HTTP 401) |
| `expired_token` | 信使的寿命已过(HTTP 401) |
| `monitoring_disabled` | 事件监测没有打开应用程序(HTTP 403) |
| `validation` | 事件验证失败 ; `error.errors` did it's per |
| `dropped` | 排队时间已满, 事件在发送前已放弃 |

`submitEvent` 本身投出一个 `DiditEventError` 仅用于丢失的符号(`invalid_token`),一个缺失 `category` 或者说 `actionType` (单位:千美元)`validation`),或环境没有 `fetch` (单位:千美元)`network`) (中文(简体) ).

## API 密码

### `submitEvent({ monitoringToken, event, baseUrl? }): string`

队列一个事件并返回其id.

| 活动领域 | 说明 |
| --- | --- |
| `category` | `auth`, (中文(简体) ), `session`, (中文(简体) ), `security`, (中文(简体) ), `payment`, (中文(简体) ), `dispute`, (中文(简体) ), `gameplay`, (中文(简体) ), `bonus`, (中文(简体) ), `affiliate`, (中文(简体) ), `responsible_gambling` 或者说 `custom` |
| `actionType` | 发生了什么事,例如. `signup`, (中文(简体) ), `login`, (中文(简体) ), `login_failed`, (中文(简体) ), `logout`, (中文(简体) ), `password_reset`, (中文(简体) ), `mfa_challenge` |
| `eventId` | 您的同位素密钥( 最多128个字符); 省略时生成 UUID |
| `occurredAt` | `Date` 或 ISO 8601 字符串; 默认为现在( 过去最多7天) |
| `timeZone` | IANA 时区; 默认浏览器的 |
| `payload` | 特定类别的密钥; 付款需要 `payment_reference_id`, (中文(简体) ), `amount`, (中文(简体) ), `currency`, (中文(简体) ), `payment_method` 财务报告和审定财务报表 `status` |
| `customValues` | Scalar 值您的规则可以处理 |
| `session` | `{ sessionId, sequence, pageUrl, referrer }` |
| `transactionContext` | `{ amount, currency, direction, paymentReferenceId }` |
| `subject` | 配置提示 `{ fullName, email, phone, country }`人总是从符来 |
| `business` | 活动属于 |

### `flush(): Promise<DiditEventFlushResult>`

发送所有等待。 永不拒绝:无法发送的事件被计算在内 `pendingCount` 并自动复试.

### `configureEvents(options)`

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `baseUrl` | `https://verification.didit.me` | Didit 验证 API 基础 URL |
| `batchSize` | `25` | 等这么多事件( 1 到 500) 立即发送 |
| `flushIntervalMs` | `5000` | 在这多毫秒后发送等待事件 |
| `maxQueueSize` | `1000` | 为纪念而举行的活动。 全部价值低的事件(`session.page_view` 先被弃绝; `security`, (中文(简体) ), `payment`, (中文(简体) ), `dispute`, (中文(简体) ), `responsible_gambling` 赌注是不会被放弃的,所以这是一个软的限制 |
| `onError` | 无 | 被叫来 `DiditEventError` 每一次拒绝或放弃的事件 |

### 设备信号

-   `getDeviceFingerprintPayload(): Promise<DeviceFingerprintPayload | null>` 收集dit-fp-v2指纹(`null` 在浏览器之外).
-   `buildFingerprintHeaders(payload)` 返回匹配 `X-Didit-*` 头.

全向导 : [SDK 事件提交](https://docs.didit.me/transaction-monitoring/sdk-event-submission)。 。 。 .

## 发展

这个包裹住在 [sdk 网络](https://github.com/didit-protocol/sdk-web) 工作空间。 从寄存器根 :

```bash
npm ci
npm test -- --runInBand        # unit tests of both packages
npm run typecheck
npm run build                  # builds @didit-protocol/signals, then @didit-protocol/sdk-web
npm run test:size              # fails above 5 KB minified and gzipped
npm run test:e2e               # Chromium, Firefox and WebKit
```

单元和浏览器测试 Didit 校验 API 的真实答案 `POST /v1/events/batch/` (单位:千美元)`src/__tests__/fixtures/device-lane-recordings.json`) (中文(简体) ). 运行浏览器对照一个活的 API 进行检查(直接的跨源请求,包括 CORS 和 Origin 绑定符号检查):

```bash
EVENTS_UPSTREAM=<API base URL> EVENTS_MONITORING_TOKEN=<token from POST /v3/events/sdk-token/> \
  npx playwright test e2e/events-live.spec.mjs --project=chromium
```

API 必须允许 `X-Monitoring-Token`, (中文(简体) ), `Content-Type` 和在浏览器交付前其CORS政策中的指纹头。 源头标记必须允许固定源 `http://127.0.0.1:4173`. 这些试验没有建立起装或生产准备状态.

## 许可证

麻省理工学院

## 常见问题

### @didit-protocol/signals 是什么？

Didit 设备信号和终端用户事件监视器

### 如何安装 @didit-protocol/signals？

在项目目录运行 npm install @didit-protocol/signals，或使用 pnpm add / yarn add / bun add。

### @didit-protocol/signals 支持 TypeScript 吗？

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

### @didit-protocol/signals 支持 ESM 还是 CommonJS？

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

### @didit-protocol/signals 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @didit-protocol/signals 可以商用吗？

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

### @didit-protocol/signals 的下载量有多少？

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

### @didit-protocol/signals 还在维护吗？

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