# @baukit/analytics-core 中文文档

规范地址：https://npmcn.com/package/%40baukit/analytics-core/

版本：0\.18\.3
npm 元数据更新时间：2026-11-07T02:35:58.319Z
中文译文更新时间：2026-11-07T18:27:33.877Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：120 kB，35 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-08-25T18:45:47.706Z
- 最新版本发布：2026-11-07T02:35:57.889Z
- 近 30 天下载量：9069（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

提供者中立,隐私第一的产品分析港口和安全政策.

## 安装

```sh
npm install @baukit/analytics-core
```

也可以使用：`pnpm add @baukit/analytics-core`、`yarn add @baukit/analytics-core`、`bun add @baukit/analytics-core`

## README

# `@baukit/analytics-core`

为Baukit TypeScript应用提供中性,隐私第一产品分析. 包裹 定义端口和安全政策; PostHog 支持属于单独的网络和本地 适配软件包。 它没有运行时间依赖.

## 为什么是端口,不是提供者包装

产品代码应当拥有事件意义和编译时间形状而无需导入提供者SDK. 这个 核心接受产品事件联盟,应用同意和隐私控制,并发送中性命令 信封为 a `Transport`。一个提供者适配器只翻译那些已经解密的信封.

获取财产所需的命令是:

1.  在事件许可列表中只保留密钥 .
2.  Scrub屏蔽了密钥和敏感的字符串模式.
3.  标记必要的共同背景和身份.
4.  将消毒的信封排入运输.

## 类型设置

```ts
import {
  AnalyticsClient,
  type AnalyticsEvent,
  type EventAllowlist,
  type Transport,
} from '@baukit/analytics-core';

type ProductEvent =
  | {
      name: 'onboarding_started';
      properties: { source: 'organic' | 'invite' };
    }
  | {
      name: 'onboarding_completed';
      properties: { duration_seconds: number };
    };

const allowlist = {
  onboarding_started: ['source'],
  onboarding_completed: ['duration_seconds'],
} as const satisfies EventAllowlist<ProductEvent>;

declare const transport: Transport<ProductEvent>; // for example, a PostHog adapter

const analytics = new AnalyticsClient<ProductEvent>({
  context: {
    schema_version: 1,
    app: 'architecture-health',
    app_version: '1.0.0',
    platform: 'web',
    environment: 'production',
    locale: 'de-DE',
  },
  allowlist,
  transport,
});

analytics.capture({
  name: 'onboarding_started',
  properties: { source: 'organic' },
});
```

`AnalyticsClientOptions.context` 因此构建客户端时不需要 `schema_version`, (中文(简体) ), `app`, (中文(简体) ), `app_version`, (中文(简体) ), `platform`, (中文(简体) ), `environment`,或 `locale` 不键入检查. 添加名称到 `ProductEvent` 还使匹配的许可列表条目成为必要。 运行时间输入可以 仍然含有多余的密钥(例如,在不安全的铸出后或跨越了JavaScript边界后),所以 许可列表在运输前将其删除.

事件名称是产品自主的公约:稳定、过去 `snake_case`,例如 `onboarding_completed`。以模板字数类型编码英文过去时态将拒绝有效 不规则的形式和产生虚假的信心。 相反,客户使用保守的发展 警告(snake case 加上过去紧张的休眠症);它永远不会改变运行时间的交付。 追踪计划 目的和所有权仍然是产品责任.

## 同意

同意开始于 `unknown`. 在表示同意时捕获、识别电话和别名 `unknown` 或者说 `denied` 立即投放,绝不缓冲后期选入.

```ts
analytics.setConsent('granted'); // persist opt-in, then analytics may run
analytics.capture({
  name: 'onboarding_completed',
  properties: { duration_seconds: 42 },
});

analytics.setConsent('denied'); // persist withdrawal and discard every unsent command
```

`setConsent` 这不是一个分析事件。 同意在施工期间同步读取, 在第一次捕捉之前. `InMemoryAnalyticsStorage` 无依赖性默认; 产品应注入小同步 `AnalyticsStorage` 由设备存储支持。 如果 平台的本地存储 API 在构建前是同步的,水合的同步缓存 客户 原生反应, `HydratedAnalyticsStorage` 从 `@baukit/analytics-posthog-native/storage` 是缓存;此软件包不发送一个。 存储失败无法保护隐私:无法读取的同意变为 `unknown`,而且分析方法不会因为持久性诊断失败而抛出.

撤离清除了尚未交给运输队的命令。 已经飞了一批了 无法回顾,这是一个运输边界,而不是隐藏缓冲.

## 身份

客户端创建并坚持匿名UUID `globalThis.crypto.randomUUID()`。运行时间 没有它,包括一些反应原生配置,必须注入加密安全 `uuidFactory`;故意没有 `Math.random()` 倒计时.

```ts
analytics.setConsent('granted');
const anonymousId = analytics.anonymousId;

analytics.identify(internalUserUuid, { plan: 'free' });
analytics.alias(anonymousId, internalUserUuid); // accepted once for this anonymous identity

analytics.reset(); // logout: clear known identity and alias guard, rotate anonymous UUID
```

只接受UUID形用户ID. 这无法证明哪个系统发布了UUID, 所以产品 必须通过内部用户 UUID , 而不是电子邮件、 名称或提供者主题 。 直接切换 拒绝已知用户之间; 调用 `reset()` 先说 异名的后卫一直坚持 并承认在 大部分别名是匿名身份的命令 包括客户重建 特质 使用与事件属性相同的被屏蔽的键和敏感值规则来擦除.

`AnalyticsClient` 存储同意状态、 匿名 UUID、 已知用户 UUID 以及其它名 `storageKeyPrefix`。 。 。 . `analyticsStorageKeys(prefix)` 返回这四个密钥, 因此是一个持续存储 适配器可以列出它所保存的.

## 捣乱

默认密钥块列表为 `email`, (中文(简体) ), `name`, (中文(简体) ), `token`, (中文(简体) ), `password`, (中文(简体) ), `authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `phone`,以及 `address`匹配是案件/分离者不敏感和故意保守,所以 键类 `displayName` 财务报告和审定财务报表 `auth_token` 已编辑。 产品可以通过 `blockedKeys`。电子邮件形状的字符串,JWT形状的字符串,以及长六进制/ Base64 类似字符串成为 `"[redacted]"`。嵌入式阵列和平面物体在不改变输入的情况下进行穿行.

短键需要精确匹配, 因为 `ip` 作为子字符串也会修改 `zip_code` 财务报告和审定财务报表 `description`。 。 。 . `DEFAULT_EXACT_BLOCKED_KEYS` 编辑 `ip`, (中文(简体) ), `ip_address`, (中文(简体) ), `remote_addr`, (中文(简体) ), `x_forwarded_for`,以及 `x_real_ip` 只有当普通键等于其中之一时。 添加产品 键,例如 `q`,通过 `exactBlockedKeys` 打开 `scrubProperties` 或者说 `AnalyticsClient`。 。 。 .

```ts
scrubProperties(properties, { blockedKeys: ['notes'], exactBlockedKeys: ['q'] });
```

`scrubErrorEvent` 对崩溃报告适用同样的规则,例如在哨兵报告中 `beforeSend`。 。 。 . 还可以编辑其中的密钥 `ERROR_EVENT_BLOCKED_KEYS` (单位:千美元)`headers`, (中文(简体) ), `data`, (中文(简体) ), `query_string`, (中文(简体) ), `body`, (中文(简体) ), `vars`, (中文(简体) ), `geo`,以及 `env`任何深度,包括请求的有效载荷、面包屑数据和堆栈 框变量。 字符串值在 `ERROR_EVENT_PRESERVED_KEYS` 保持原状, 所以事件,追踪 跨度 ID 幸存于长重击规则和堆栈框保存 `filename`, (中文(简体) ), `abs_path`, (中文(简体) ), `function`,以及 `module`。顶级 `sdk` 对象保留其密钥,所以SDK名称仍可读取. 其它 `name` 密钥,包括 OS 和设备名称,仍然被编辑.

```ts
Sentry.init({
  dsn,
  sendDefaultPii: false,
  beforeSend: (event) => scrubErrorEvent(event, { blockedKeys: ['notes'] }),
});
```

洗涤器只是最后的防线. 事件属性必须保持有界限的元数据:永远 健康或食物价值,谈话或即时内容,免费文本,准确位置,证明, 或原始标识 URL.

## 缓冲和失败

接受命令输入带有这些默认的内存队列 :

-   最大100个等待命令;
-   20个命令或5秒后冲出;
-   最古老的等待命令掉到溢出处;
-   在最初的运输尝试之后进行两次复试,并有短暂的指数延迟;
-   重试后投放失败的批次 .

`capture`, (中文(简体) ), `identify`, (中文(简体) ), `alias`, (中文(简体) ), `reset`,以及 `setConsent` 是同步的,从不等待 供养. 大小触发的送出被安排在一个微任务中; 间隔送出使用 unref'd 运行时间支持的计时器 。 拒绝运输和同步运输的例外情况 内部被抓住,从不逃入用户之行. `onTransportFailure` 可用于 限制的诊断,甚至这种召回的例外都有限制.

`flush()` 是一个明确的最佳边界 总是解决的, 有用的测试和应用 寿命轮钩. `dispose()` 进行最佳冲洗并清除计时器。 队列不是 持续: 应用程序重新启动不会重现分析命令, 未知/ 否认的事件可以 后经同意后永远不会出现.

`NoopTransport` 安全丢弃命令. `InMemoryTransport` 保留可检查的信封 测试。 通过执行 PostHog 网络和 React 本地包插件 `Transport<E>` 翻译 中键 `capture`, (中文(简体) ), `identify`, (中文(简体) ), `alias`,以及 `reset` 信封变体;产品代码和隐私 政策保持不变.

## 常见问题

### @baukit/analytics-core 是什么？

提供者中立,隐私第一的产品分析港口和安全政策\.

### 如何安装 @baukit/analytics-core？

在项目目录运行 npm install @baukit/analytics-core，或使用 pnpm add / yarn add / bun add。

### @baukit/analytics-core 支持 TypeScript 吗？

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

### @baukit/analytics-core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @baukit/analytics-core 需要什么版本的 Node\.js？

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

### @baukit/analytics-core 可以商用吗？

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

### @baukit/analytics-core 的下载量有多少？

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

### @baukit/analytics-core 还在维护吗？

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