# @hanzogui/telemetry 中文文档

规范地址：https://npmcn.com/package/%40hanzogui/telemetry/

版本：8\.4\.4
npm 元数据更新时间：2026-10-30T17:31:07.587Z
中文译文更新时间：2026-11-17T08:39:57.460Z
软件包许可：BSD-3-Clause

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

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

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

- 包体积（解压后）：257 kB，90 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=19\.2\.8
- 首次发布：2026-07-25T22:19:19.917Z
- 最新版本发布：2026-10-30T17:31:07.404Z
- 近 30 天下载量：13607（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

Zero-config Hanzo遥测——一线错误+会话抓取,页面视图,产品事件到一端(POST api.hanzo.ai/v1/event),将它们透入哨站.hanzo.ai,分析.hanzo.ai和洞察.hanzo.ai. 荣誉

## 安装

```sh
npm install @hanzogui/telemetry
```

也可以使用：`pnpm add @hanzogui/telemetry`、`yarn add @hanzogui/telemetry`、`bun add @hanzogui/telemetry`

## README

# @hanzogui/遥测

任何汉佐地表的零配置遥测——网络,桌面和原生.

**如果你挂载 `<GuiProvider>` 从 `@hanzo/gui`你已经有了它.** 有一个 不安装、导入或接线:页面视图、未处理错误、反应渲染 错误和交互捕捉到达一个半藏端点,与产品 从运行时间和从环境读取的摄入密钥中解析出名称.

```tsx
import { GuiProvider } from '@hanzo/gui'

<GuiProvider config={config}>{children}</GuiProvider>   // telemetry included
<GuiProvider config={config} telemetry={false}>…        // opt out
<GuiProvider config={config} telemetry={{ product: 'studio' }}>…
```

只有当你不是Gui应用程序时,或者当你需要开车时,才能自己挂上 路由器的页面视图 :

```tsx
import { TelemetryProvider } from '@hanzogui/telemetry'

export default function Root({ children }) {
  return <TelemetryProvider path={usePathname()}>{children}</TelemetryProvider>
}
```

也可以从组件层获得,因为 `@hanzo/ui/telemetry`,哪个 重新导出此软件包时, 无需修改 。 所以一个已经依赖于 `@hanzo/ui` 没有增加什么.

## 一道溪流,两道溪流

`GuiProvider` 挂载 `<TelemetryProvider owner="gui">`,这种姿态是 每一个应用都安全启动: **贵州自有供应商 只有在没有其他收藏时才收集.**

| 应用程序挂载 | 何处 | 阿贵做什么 |
| --- | --- | --- |
| 无 | —— 说 | 收集——这是免费案例 |
| `<AnalyticsProvider>` 编号 : `<TelemetryProvider>` | 上文 `GuiProvider` | 然后把应用程序的客户端直接通过 |
| `<TelemetryProvider>` | 下级 `GuiProvider` | 读取惰性; 应用程序拥有流 |
| 秒数 `<GuiProvider>` | 任何地方 | 一个客户端, 一个流 |

所有权是模块镜槽上的权利要求,不是渲染时间猜想,所以 幸存后山(一条懒行道取出溪口)和出山(取出溪口) 回来. `owner="app"` 是供货商的默认情况,您会自动挂载自己,并且总是 赢了.

**一个形状的Gui看不见** 是一个生的 `@hanzo/event` `<AnalyticsProvider>` _下级_ `GuiProvider`:反应上下文不向下看,与 `<TelemetryProvider>` 生的一无所有。 这些应用程序通过 `telemetry={false}` 直到他们放弃了自己的线路.

## 一个端口 三道镜头

一切——网页视图,产品事件,例外,互动捕捉——是 作为分批流到 **一个** 汉佐端点 :

```
POST https://api.hanzo.ai/v1/event   { batch: [Event, …] }
```

云镜将单流分入三个视图:

| 镜头 | 东道主 | 显示什么 |
| --- | --- | --- |
| 错误 | `sentry.hanzo.ai` | 例外、 堆栈、 会话抓取 |
| 网络分析 | `analytics.hanzo.ai` | 页面视图、裁判、活动 |
| 产品见解 | `insights.hanzo.ai` | 漏斗,笔记本, **`analytics_errors`** |

洞察力也出错 所以漏斗滴会加入这个例外 这个 这三位主持人是 **仪表板**。它们从来不是摄入的终点: 正是一个 API 主机, 这就是为什么没有任何配置.

## 你免费得到的

-   **页面视图**,包括SPA路由更改. 过 `path` (下一个: `usePathname()`(中文(简体) ) 要从你的路由器中驱动它们, 或通过什么 和历史API驱动它们.
-   **错误** —— 说 `window.onerror`,无处理的拒绝, 和反应产生错误. 这是 `@sentry` 替换; 没有浏览器 SDK 和 CDN 脚本,所以 `default-src 'none'` CSP无法突破.
-   **会话抓取** ——每次点击/输入/投递都附加了语义说明 等级 (`navigation/Dashboard/UserCard/button[save]`),所以重播为 可读取而不是像素电影. 装入了动态 `import()` 在一个 空闲的回调,在自己的块, 所以它永远不会花费LCP.
-   **一触即发** 和组别`channel`, (中文(简体) ), `refCode`, (中文(简体) ), `signupWeek`(中文(简体) ) 每一事件.
-   **产品推论** 从主机名 - `console.hanzo.ai` 报告为: `console`, (中文(简体) ), `hanzo.chat` 作为 `chat`, (中文(简体) ), `hanzo.ai` 作为 `site`。 。 。 .

## 隐私

-   **Do-not-Track和Global 隐私控制被默认遵守.** 与 要么是信号集,要么是没有明确的应用选择,任何信息都无法收集 什么也没有写到存储.
    
-   **发觉同意.** 一个人在你的UI中做出明确的选择,比 浏览器双向默认 :
    
    ```tsx
    import { setConsent, useConsent } from '@hanzogui/telemetry'
    
    const choice = useConsent() // 'granted' | 'denied' | undefined
    setConsent('denied') // takes effect immediately, everywhere
    setConsent('unset') // forget it; DNT/GPC applies again
    ```
    
    退取为前想:一时收取停止. 已经缓冲的事件 在得到现场同意的情况下,可以完成飞行冲洗.
    
-   **输入值被扣** 从默认抓取. `data-hz-private` 在任意 元素不包括整个子树.
    

## 别的地方

非反应代码不需要提供者——环境客户端自建 从环境开始使用,供应商登记自己的客户 进入同一个槽,所以有 一种实例和一流的方式.

```ts
import { track, identify, captureError, EVENTS } from '@hanzogui/telemetry'

identify(user.id)
track(EVENTS.PLAN_CLICKED, { plan: 'pro' })
try {
  risky()
} catch (err) {
  captureError(err, { properties: { where: 'checkout' } })
}
```

## 组件

```tsx
import { useTelemetry, useTrack } from '@hanzogui/telemetry'

const t = useTelemetry() // total: never null, never throws, SSR-safe
const track = useTrack() // just the recorder
```

## 配置( 全部可选)

环境,从 `process.env` (下个), `import.meta.env` (vit/Expo),或 a (中文(简体) ) `window.__HANZO_TELEMETRY__` 没有构建步骤的页面对象 :

| 变量 | 默认 | 含义 |
| --- | --- | --- |
| `NEXT_PUBLIC_PUBLISHABLE_KEY` 编号 : `VITE_PUBLISHABLE_KEY` 编号 : `EXPO_PUBLIC_PUBLISHABLE_KEY` | —— 说 | 可出版 `pk-…` 键 - **一个名字**KMS搭载的那个 `deploy/PUBLISHABLE_KEY` 和一个 `@hanzo/event` 读取。 只有写,而且安全 没有它,信标是无属性的,边缘拒绝它。 (老年人) `…_HANZO_INGEST_KEY` 拼写仍然读取,第二并正在被退役. ) |
| `NEXT_PUBLIC_HANZO_API_URL` 编号 : `VITE_HANZO_API_URL` | `https://api.hanzo.ai` | 摄入最上主. |
| `NEXT_PUBLIC_HANZO_PRODUCT` 编号 : `VITE_HANZO_PRODUCT` | 从运行时间解析, 然后是主机名 | 隐形地表。 Tauri 窗口报告为 `desktop` 它服务于来自三个来源的一捆货物(`tauri://localhost`, (中文(简体) ), `http://tauri.localhost`,dev服务器),所以URL是唯一不能命名它的东西. |
| `NEXT_PUBLIC_HANZO_TELEMETRY` 编号 : `VITE_HANZO_TELEMETRY` | 打开 | `0`编号 :`false`编号 :`off` 是一个建置时杀开关. |

道具,当你想要它们时:

```tsx
<TelemetryProvider
  path={usePathname()} // drive pageviews from your router
  product="console" // override the inferred surface
  host="" // same-origin, cookie-auth apps
  getToken={() => token} // bearer-auth apps
  replay={false} // no interaction capture
  errors={false} // no error capture
  pageviews={false} // no pageviews
  consent="granted" // your own consent gate decided
  enabled={false} // hard kill switch, wins over everything
  fallback={(err, reset) => <Crash error={err} onReset={reset} />}
/>
```

没有 `fallback`,然后报告一个渲染错误 **重新投掷** 所以你们自己 仍然运行错误 。 观察不能改变行为.

## 保证

-   **安全无虞.** 导入无所事事; 服务器上的渲染无所作为 .
-   **原始山地,暂时保持沉默.** `GuiProvider` 电线遥测 完全相同,但DOM仍然是 收集: `@hanzo/event`是因为 `init()` 读取 `window.location.search` 财务报告和审定财务报表 `document.referrer` 后面一个 `typeof window` 校验,并且 React 本地定义 `window` 也没有。 满足本地需求 检查需要 `document` - 一个 `@hanzo/event` 固定,不是一个gui。 在那之前,土生土长 和惰性而不是崩溃.
-   **失败的软.** 每一个公共方法 吞下自己的错误,网络损失是 被忽略,一个失败的抓取引擎块 仅仅意味着没有抓取.
-   **树可摇.** `sideEffects: false`无害环境管理,每起出口一次.
-   **没有CDN.** 没有从第三方来源装货的.

## 组成

```
@hanzo/event      the ONE client — batching, attribution, the wire, the endpoint
@hanzo/observe    the capture engine — semantics, redaction, playback stream
@hanzogui/telemetry  ← this: the zero-config policy that wires them together
@hanzo/ui/telemetry   re-export, so the component layer needs no new dependency
```

机制生活在下面,政策生活在这里,每个机制都有一个.

## 常见问题

### @hanzogui/telemetry 是什么？

Zero-config Hanzo遥测——一线错误\+会话抓取,页面视图,产品事件到一端\(POST api\.hanzo\.ai/v1/event\),将它们透入哨站\.hanzo\.ai,分析\.hanzo\.ai和洞察\.hanzo\.ai\. 荣誉

### 如何安装 @hanzogui/telemetry？

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

### @hanzogui/telemetry 支持 TypeScript 吗？

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

### @hanzogui/telemetry 支持 ESM 还是 CommonJS？

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

### @hanzogui/telemetry 可以商用吗？

@hanzogui/telemetry 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @hanzogui/telemetry 的下载量有多少？

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

### @hanzogui/telemetry 还在维护吗？

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

