# @hanzo/event 中文文档

规范地址：https://npmcn.com/package/%40hanzo/event/

版本：0\.3\.66
npm 元数据更新时间：2026-10-30T14:29:17.535Z
中文译文更新时间：2026-11-17T08:15:47.657Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hanzo/event
原文对照：https://npmcn.com/package/%40hanzo/event/?lang=original
源码仓库：https://github.com/hanzoai/ui

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

- 包体积（解压后）：1.4 MB，102 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19\.2\.8
- 首次发布：2026-07-20T23:50:19.252Z
- 最新版本发布：2026-10-30T14:29:17.328Z
- 近 30 天下载量：23692（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

半藏事件——一号遥测客户端. 将页面视图/活动/识别/组入汉藏云事件流(POST /v1/event),并将出错报告给哨兵作为真正的哨兵信封——错误平面需要DSN,没有任何一个到达哨兵. 先对

## 安装

```sh
npm install @hanzo/event
```

也可以使用：`pnpm add @hanzo/event`、`yarn add @hanzo/event`、`bun add @hanzo/event`

## README

# @hanzo/活动

汉藏表面的一元遥测客户端. 提供各种活动—— `pageview` 编号 : `event` 编号 : `identify` 编号 : `group` **错误** ——改为: **汉藏云**, (中文(简体) ), 从来没有给第三方.

一个终点, `POST {host}/v1/event`数字 `{ batch: [Event, …] }`页面视图, 事件,识别,组合和错误 都骑它; 没有第二个终点, DSN还是信封.

### 没有包? 使用主机标签

```html
<script defer src="https://api.hanzo.ai/v1/event/tag.js" data-key="pk-…"></script>
```

那条线是整个安装的, 并且它是同一个线 对于一个公布的网站, hanzo.team和客户自己的页面。 标记由吃东西的端点提供 事件,所以一个呼叫者允许使用 one 主机和标记永远不能从线上漂移 其员额为: `.js` 属于一段而非一段的孩子,所以标记 坐在下边 `/v1/event` 而不是旁边,还有老兄弟 `/v1/event.js` 404号.

它自动抓取页面视图——第一个和每一个SPA导航,因为 `history.pushState` 没有发生任何事件——加上未发现的错误和被拒绝 承诺。 任何一页的意思都是故意的 `window.hanzo` (单位:千美元)`track`, (中文(简体) ), `identify`, (中文(简体) ), `page`, (中文(简体) ), `error`, (中文(简体) ), `flush`) (中文(简体) ). 上面还贴着网站的标签 配置从 `/v1/projects/tags`,因此在工程上配置了一个像素 而不是贴入页面.

> 捆绑的应用程序不应添加此标签 。 两个客户都贴出相同的页面视图 结束点,所以要运行一个页面 `@hanzo/event` 和标签计算每个页面视图两次. 一个表面,一个客户端.

> **`data-key` 是一个可出版的 `pk-`没有标记就是INERT.** 写作 边缘不能属性被拒绝( q)`401 ingest_key_required`默默无声 所以 无密钥标记措施在浏览器和文件中都很好。 一块薄荷薄荷 与自己: `POST /v1/projects`。不会拒绝任何工程名称的密钥 `403 ingest_key_unknown` ——边缘未关闭而未提交出字 无法属性 .

此软件包是表面的客户端 **正在建设**没有秒 这里的脚本-tag分布:一线,一端点,一标记.

它尊重与捆绑的堆栈相同的同意来源:访问者所在区域与 云决定( 二`eu`:在选择之前没有可选择的; `us_privacy` 财务报告和审定财务报表 `global`数字 : 默认情况下的一切,Ads 关闭是出售或分享选择退出,一个存储的选择 (单位:千美元)`__Host-hz_consent` 在安全页面上 访问者的单词,以及 Global Privacy Control 或 Do Not track 作为拒绝在 每个区域:根本没有平台载荷。 一个 React app 不需要此文件 – 挂载 `<Hanzo analytics>` 从 `@hanzo/ui`将客户端和捕捉引擎连接在一起.

> 曾经居住的标签 `hanzoai/analytics` 员额a **空 JSON 阵列** 联 合 国 `{site, ts, type, path, …}` 改为 `analytics.hanzo.ai/v1/event` - 第二项议定书 在同一个路径拼写后面, 由第二个收藏家服务 数据库. `POST api.hanzo.ai/v1/event {"batch":[]}` 回答 200 时 `POST analytics.hanzo.ai/v1/event []` 回答204,一个客户指着 错误的主机静默失败 。 第二个终点和第二个收藏家 删除。 一个线,一个终点,一个客户端回家——这个包裹.

-   **划伤** 带有大小+间距冲出,以及 **卸载信标** (单位:千美元)`sendBeacon` 为饼干/可应用的钥匙应用程序, `fetch(keepalive)` (原始内容存档于2017-03-28). for sorch apps.
-   **自动抓取错误** (分录 `@sentry`: `window.onerror`, (中文(简体) ), `unhandledrejection`反应 `ErrorBoundary` 报告为一体 `type:'error'` 每个事件。 选择退出 `captureErrors: false`。 。 。 .
-   **在源头被打扫**: 秘密总是被修改, PII 被掩盖 错误离开设备前的客户端.
-   **一触即发**: UTM+裁判员+ `refCode` 解析一次 坚持,然后依附每件事.
-   **组合**数字 : `signupWeek`, (中文(简体) ), `channel`, (中文(简体) ), `refCode` 骑每一件事.
-   **租赁安全**: 客户端从未发送过 Org/tenant —— 从云来邮票 已验证会话或已签名的可公布密钥.
-   **失败软件**:遥测损失被吞入;客户端从不向应用投放.
-   **安保部门安全**:在服务器上导入是无操作;它只在浏览器中操作.

## 核心(框架-不可知性)

```ts
import { createAnalytics, EVENTS } from '@hanzo/event'

// Cookie/session apps (console, admin): same-origin, no token.
const analytics = createAnalytics({ product: 'console' })

// Token apps (app, site): give the cloud host + a bearer getter.
const analytics = createAnalytics({
  product: 'app',
  host: 'https://api.hanzo.ai',
  getToken: () => localStorage.getItem('hanzo_access_token') ?? undefined,
})

analytics.pageview()
analytics.identify('user-42')
analytics.capture(EVENTS.SIGNUP_COMPLETED, { plan: 'pro' })
analytics.capture(EVENTS.ORDER_COMPLETED, { kind: 'plan' }, { productId: 'plan_pro', revenue: 49, quantity: 1, currency: 'usd' })
```

## 反应

```tsx
'use client'
import { AnalyticsProvider, useAnalytics, usePageview } from '@hanzo/event/react'
import { usePathname } from 'next/navigation'

export function Providers({ children }) {
  return <AnalyticsProvider config={{ product: 'console' }}>{children}</AnalyticsProvider>
}

function RouteTracker() {
  usePageview(usePathname()) // one pageview per navigation
  return null
}

function UpgradeButton() {
  const a = useAnalytics()
  return <button onClick={() => a.capture(EVENTS.PLAN_CLICKED, { plan: 'pro' })}>Upgrade</button>
}
```

## 错误( @ sentry 替换)

未处理的错误和承诺拒绝自动被捕获. 反应渲染 错误从未到达 `window.onerror`将你的树包入 `ErrorBoundary` 改为 抓住这些了。 报告自己发现的错误 `captureError`。 。 。 .

```tsx
import { ErrorBoundary } from '@hanzo/event/react'

<AnalyticsProvider config={{ product: 'console' }}>
  <ErrorBoundary fallback={(err, reset) => <Crash error={err} onReset={reset} />}>
    <App />
  </ErrorBoundary>
</AnalyticsProvider>
```

```ts
try { risky() } catch (err) { analytics.captureError(err, { properties: { where: 'checkout' } }) }
```

每一份报告 `type:'error'` 包含的事件 `error` (单位:千美元)`type`, (中文(简体) ), `message`, (中文(简体) ), `frames`, (中文(简体) ), `stack`, (中文(简体) ), `handled`+) 加上 (中文(简体) ) `release`, (中文(简体) ), `environment`, (中文(简体) ), `site`, (中文(简体) ), `product` 财务报告和审定财务报表 `level`。服务器在错误平面上存档,并将其分组为一个问题.

讯息和任何 `properties` 在传送之前, 消息封顶在8KB. `captureError` 从来没有扔回你的应用程序,

## 可公布的密钥( 公开页面, 无记名)

营销/公共网页没有会议。 Mint 只写可公布的密钥 (单位:千美元)`POST /v1/ingest/keys`并传为 `ingestKey`骑着它 `Authorization` 打开 获取和 `?ingest_key` 在卸货信标,所以 **事件流** 接受 匿名流量。 装入捆绑(只写,不能读)是安全的.

```ts
createAnalytics({ product: 'site', host: 'https://api.hanzo.ai', ingestKey: 'pk_live_…' })
```

## 分类学、漏斗和目标

**[塔克索诺米·姆德](https://npmcn.com/package/%40hanzo/event/TAXONOMY.md) 是犬科的谱系** - 命名会议, 财产规则, `identify`编号 :`group` 语义学,为hanzo.ai所取的漏斗/ hanzo.app / hanzo.chat, 以及每个事件的确切发射站点( file:line) 每一个表面。 在增加活动前读取.

`FUNNELS` (见 `funnels.ts`)是漏斗登记单:每次行程是 命令步骤列表命名 `EVENTS` 值,以 `product`一个漏斗 登录时横跨来源 `join: 'aggregate'` - 两个来源的意思 两个 `anonymousId`s,所以在他们身上的每人费率会是一个谎言.

```ts
import { FUNNELS, GOALS } from '@hanzo/event'

FUNNELS.appShip.steps.map((s) => s.event)
// ['$pageview','build_started','generation_completed','deploy_started','deploy_succeeded']
GOALS.signup.funnel // derived from FUNNELS.signup — never restated
```

## 目标组

`GOALS` 财务报告和审定财务报表 `COHORTS` (见 `goals.ts`是共享的、机器可读的见解 光谱 : **注册** (funnel view 提交 核实 第一行动), **销售** 联合国 `order_completed` 与 `kind=plan`),以及 **升级意向** (单位:千美元)`plan_clicked`, (中文(简体) ), 漏斗从 `pricing_viewed`) (中文(简体) ). 共享字段映射到 `signup_week`, (中文(简体) ), `channel`,以及 `ref_code` 栏 `hanzo.events`。 。 。 .

## 常见问题

### @hanzo/event 是什么？

半藏事件——一号遥测客户端\. 将页面视图/活动/识别/组入汉藏云事件流\(POST /v1/event\),并将出错报告给哨兵作为真正的哨兵信封——错误平面需要DSN,没有任何一个到达哨兵\. 先对

### 如何安装 @hanzo/event？

在项目目录运行 npm install @hanzo/event，或使用 pnpm add / yarn add / bun add。

### @hanzo/event 支持 TypeScript 吗？

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

### @hanzo/event 支持 ESM 还是 CommonJS？

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

### @hanzo/event 可以商用吗？

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

### @hanzo/event 的下载量有多少？

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

### @hanzo/event 还在维护吗？

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

