@hanzogui/telemetry

中文文档
8.4.4发布于 2026/10/31BSD-3-ClauseTypeScriptESM + CJS近 30 天下载 1.4万

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

中文使用文档
文档目录9 节
  1. 一道溪流,两道溪流
  2. 一个端口 三道镜头
  3. 你免费得到的
  4. 隐私
  5. 别的地方
  6. 组件
  7. 配置( 全部可选)
  8. 保证
  9. 组成

@hanzogui/遥测

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

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

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应用程序时,或者当你需要开车时,才能自己挂上 路由器的页面视图 :

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中做出明确的选择,比 浏览器双向默认 :

    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 在任意 元素不包括整个子树.

别的地方

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

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' } })
}

组件

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_URLhttps://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 是一个建置时杀开关.

道具,当你想要它们时:

<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 共发布 22 个版本,首次发布于 2026/07/26;过去 12 个月发布了 22 个版本。

版本发布日期距今
8.4.4latest2026/10/3117 天前
8.4.32026/10/3018 天前
8.4.22026/10/2325 天前
8.4.12026/10/2325 天前
8.4.02026/10/2325 天前
8.3.52026/09/072 个月前

关于 @hanzogui/telemetry 的常见问题

@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 和提交记录判断。