@hanzo/event

中文文档
0.3.66发布于 2026/10/30MITTypeScriptESM + CJS近 30 天下载 2.4万

Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-to

原始使用文档
文档目录7 节
  1. No bundler? Use the hosted tag
  2. Core (framework-agnostic)
  3. React
  4. Errors (the @sentry replacement)
  5. Publishable key (public pages, no bearer)
  6. Taxonomy, funnels & goals
  7. Goals & cohorts

@hanzo/event

The ONE telemetry client for Hanzo surfaces. Emits every kind of event — pageview / event / identify / group and errors — to Hanzo Cloud, never to a third-party.

ONE endpoint, POST {host}/v1/event, body { batch: [Event, …] }. Pageviews, events, identifies, groups and errors all ride it; there is no second endpoint, DSN or envelope.

No bundler? Use the hosted tag

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

That one line is the whole install, and it is the same line for a published site, hanzo.team and a customer's own page. The tag is served by the endpoint that eats the events, so a caller allowlists ONE host and the tag can never drift from the wire it posts to — .js is part of a segment rather than a child of one, so the tag sits UNDER /v1/event rather than beside it, and the old sibling /v1/event.js 404s.

It autocaptures pageviews — the first one and every SPA navigation, since history.pushState fires no event of its own — plus uncaught errors and rejected promises. Anything a page means on purpose goes through window.hanzo (track, identify, page, error, flush). It also carries the site's tag config from /v1/projects/tags, so a pixel is configured on the project rather than pasted into the page.

A bundled app should NOT add this tag. Both clients post pageviews to the same endpoint, so a page running @hanzo/event and the tag counts every pageview twice. One surface, one client.

data-key is a publishable pk-, and without one the tag is INERT. A write the edge cannot attribute is refused (401 ingest_key_required) silently, so a keyless tag measures fine in the browser and files nothing. A project mints one with itself: POST /v1/projects. A key that names no project is refused 403 ingest_key_unknown — the edge fails closed rather than filing a write it cannot attribute.

This package is the client for a surface that builds. There is no second script-tag distribution here: one wire, one endpoint, one tag.

It honours the same consent sources the bundled stack does: the visitor's region as cloud decides it (eu: nothing optional before a choice; us_privacy and global: everything on by default, Ads off being the sale-or-sharing opt-out), a stored choice (__Host-hz_consent on a secure page, the key the Hanzo consent banner writes) as the visitor's word, and Global Privacy Control or Do Not Track as a refusal in every region: no platform loads at all. A React app does not need this file — mount <Hanzo analytics> from @hanzo/ui, which wires this client and the capture engine together.

The tag used to live in hanzoai/analytics and post a bare JSON array of {site, ts, type, path, …} to analytics.hanzo.ai/v1/event — a second protocol behind an identical path spelling, served by a second collector with its own database. POST api.hanzo.ai/v1/event {"batch":[]} answered 200 while POST analytics.hanzo.ai/v1/event [] answered 204, and a client pointed at the wrong host failed silently. Both the second endpoint and the second collector are deleted. One wire, one endpoint, one client home — this package.

  • Batched with a size + interval flush, and beacon-on-unload (sendBeacon for cookie/publishable-key apps, fetch(keepalive) for token apps).
  • Auto error capture (subsumes @sentry): window.onerror, unhandledrejection, and a React ErrorBoundary are reported as one type:'error' event each. Opt out with captureErrors: false.
  • Scrubbed at the source: secrets are always redacted and PII is masked client-side before an error leaves the device.
  • First-touch attribution: UTM + referrer + refCode are parsed once and persisted, then attached to every event.
  • Cohorts: signupWeek, channel, refCode ride each event.
  • Tenant-safe: the client NEVER sends an org/tenant — Cloud stamps it from the validated session or the signed publishable key.
  • Fail-soft: telemetry loss is swallowed; the client never throws into the app.
  • SSR-safe: importing on the server is a no-op; it only acts in the browser.

Core (framework-agnostic)

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

React

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

Errors (the @sentry replacement)

Unhandled errors and promise rejections are captured automatically. React render errors never reach window.onerror, so wrap your tree in the ErrorBoundary to catch those too. Report caught errors yourself with captureError.

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

<AnalyticsProvider config={{ product: 'console' }}>
  <ErrorBoundary fallback={(err, reset) => <Crash error={err} onReset={reset} />}>
    <App />
  </ErrorBoundary>
</AnalyticsProvider>
try { risky() } catch (err) { analytics.captureError(err, { properties: { where: 'checkout' } }) }

Each report is one type:'error' event carrying error (type, message, frames, stack, handled) plus release, environment, site, product and level. The server files it on the error plane and groups it into an issue.

The message and any properties are scrubbed of secrets and PII before sending, and the message is capped at 8KB. captureError never throws back into your app,

Publishable key (public pages, no bearer)

Marketing/public pages have no session. Mint a write-only publishable key (POST /v1/ingest/keys) and pass it as ingestKey; it rides Authorization on fetch and ?ingest_key on an unload beacon, so the event stream accepts anonymous traffic. It is safe to ship in a bundle (write-only, cannot read).

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

Taxonomy, funnels & goals

TAXONOMY.md is the canonical spec — naming convention, property rules, identify/group semantics, the funnels for hanzo.ai / hanzo.app / hanzo.chat, and the exact emit site (file:line) of every event on each surface. Read it before adding an event.

FUNNELS (see funnels.ts) is the one funnel registry: each journey is an ordered list of steps naming EVENTS values, scoped by product. A funnel that spans origins while logged out is marked join: 'aggregate' — two origins mean two anonymousIds, so a per-person rate across them would be a lie.

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 and COHORTS (see goals.ts) are the shared, machine-readable insights spec: Signup (funnel view→submit→verify→first-action), Sale (a order_completed with kind=plan), and Upgrade Intent (plan_clicked, funnel from pricing_viewed). Cohort fields map to the signup_week, channel, and ref_code columns of hanzo.events.

版本与发布记录

@hanzo/event 共发布 62 个版本,首次发布于 2026/07/21;过去 12 个月发布了 62 个版本。

版本发布日期距今
0.3.66latest2026/10/3017 天前
0.3.652026/10/3017 天前
0.3.642026/10/3017 天前
0.3.632026/10/2621 天前
0.3.622026/10/2622 天前
0.3.612026/10/2622 天前

关于 @hanzo/event 的常见问题

@hanzo/event 是什么?

Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-to

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