Interaction analytics was app work. Every surface wired its own client and instrumented its own call sites, so a click on the same Button was named three ways or not at all. `<Hanzo analytics>` is now the whole wiring: one prop on the root an app already mounts, and every click, change, submit and route change inside the tree reaches the ONE front door named by the component it happened on — `card/button[Save]` — with input values withheld. A prop, not a default. Mounting a component library must never start a network conversation the app did not ask for; off, no provider renders and no listener is installed. On, it renders @hanzogui/telemetry's provider, which is where consent already lives (GPC, DNT, the stored choice a banner writes). No second client, no second stream, no second consent policy. Component names are real in production. Every primitive already carries a `data-slot` through one helper, so `componentName()` reads it — ranked ABOVE the React fiber owner deliberately, because the fiber name is development-only and a dashboard grouped on it empties silently at deploy. A named node keeps its qualifier now (`button[Save]`, not `button`): a component name says what KIND of thing it is, and a library renders hundreds of each. It cannot double-count. The engine installs DELEGATED listeners on a root, so two engines on one root report everything twice — which is exactly what an app got by following two true sets of instructions at once, since a library provider starts an engine and observe's own README told apps to mount another. The first engine to start now claims its root and any later one stays inert. The claim lives on the page under a `Symbol.for` registry rather than in module scope: two copies of the package in one bundle have two module scopes and would not see each other's claim, which is precisely when a duplicate is most likely. Driving it in Chromium found what jsdom could not: the input debounce was ONE slot shared across elements, so moving to the next field cleared the previous field's pending timer and a filled form reported only the last field touched. Keyed by field now. hz.js could not authenticate at all. Through 0.3.11 it sent no `Authorization` and no `?ingest_key=`, so every keyed static surface wrote unattributed, the door refused it (401 ingest_key_required), and nothing in the page said so — the tag measured fine in the browser and the surface was simply missing from the warehouse. `data-ingest-key="pk-…"` now rides the header on fetch and the query on a headerless unload beacon, the same pair the npm client uses. It also honors Global Privacy Control and the stored `hz_consent` choice, not DNT alone, and its stamped `libraryVersion` is pinned to the package version by a test — it had drifted three patches, dating every static-site row to the wrong release. The hz.js suite ran none of its tests: Node >= 21 ships a `navigator` whose descriptor has no setter, so the harness's assignment threw. The one shipped file with no bundler and no import-time typing had no executed coverage. It runs again, and now asserts what reaches the wire — transport, URL, headers — not only the batch. @hanzo/event 0.3.12, @hanzo/observe 0.1.7, @hanzo/ui 8.0.58. Co-authored-by: Hanzo Dev <[email protected]>
9.3 KiB
@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 API surface over TWO planes. They are separate pipes, and neither can starve the other:
1. event stream POST {host}/v1/event body: { batch: [Event, …] } -> { accepted, dropped }
2. error plane POST {dsn}/v1/sentry/{projectId}/envelope/?sentry_key=… (a real Sentry envelope)
Errors need a DSN. Without one, nothing reaches Sentry.
There is no server-side fan-out from
/v1/eventinto Sentry. Versions ≤ 0.3.1 of this README claimed there was — that "Cloud fans the one stream out into three lenses". It does not./v1/eventwrites atype:'error'row to the cloud event warehouse (readable viaGET /v1/errors) and stops there. Because every Hanzo property believed that claim, nobody set a DSN, and the entire fleet reported zero errors to Sentry until 0.3.2 added the envelope.Set
dsn(orNEXT_PUBLIC_HANZO_EVENT_DSN). Mint one per property withPOST /v1/sentry/projects. The key is publishable and write-only — safe in a browser bundle, same trust class as apk_ingest key. No DSN means the error plane is inert: nothing is sent, nothing throws, analytics is unaffected. Assertclient.errorPlaneEnabledif you want to know which you have.
No bundler? Use the hz.js tag — same client, same wire
<script async src="https://unpkg.com/@hanzo/event/hz.js"
data-product="hanzo.ai"
data-ingest-key="pk-…"
data-capture="1"></script>
data-ingest-keyis required off the door's own origin, and through 0.3.11 this file could not present one at all — no header, no query. A keyed static surface therefore sent UNATTRIBUTED writes, which the door refuses (401 ingest_key_required) silently, because nothing here reads the response. The tag measured fine in the browser and filed nothing. It now ridesAuthorization: Bearer pk-…on fetch and?ingest_key=pk-…on a headerless unload beacon — the same pair the npm client uses.
hz.js (in this package) is the script-tag distribution of this client, for
surfaces with no build step. It posts the SAME { batch: [WireEvent, …] } to the
SAME POST {host}/v1/event, and adds DOM autocapture — $click (with an
element locator), $outbound, $scroll, $form, $vitals — which a bundled app
does not need and a plain page cannot get. Manual API: window.hanzo.track() /
identify() / page().
It honours the same consent sources the bundled stack does: an explicit stored
choice (hz_consent, the key a Hanzo consent banner writes) outranks the browser
signal in both directions; otherwise Global Privacy Control and Do Not Track are
refusals. 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/analyticsand post a bare JSON array of{site, ts, type, path, …}toanalytics.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 whilePOST analytics.hanzo.ai/v1/event []answered 204, and a client pointed at the wrong host failed silently. Both the second door and the second collector are deleted. One wire, one door, one client home — this package.
- Batched with a size + interval flush, and beacon-on-unload
(
sendBeaconfor cookie/publishable-key apps,fetch(keepalive)for token apps). - Auto error capture (subsumes
@sentry):window.onerror,unhandledrejection, and a ReactErrorBoundaryare reported on both planes — a Sentry envelope to the DSN host, and a correlatedtype:'error'event on the stream. Opt out withcaptureErrors: 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 +
refCodeare parsed once and persisted, then attached to every event. - Cohorts:
signupWeek,channel,refCoderide 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.
Pass a dsn or none of this reaches Sentry.
import { ErrorBoundary } from '@hanzo/event/react'
<AnalyticsProvider config={{ product: 'console', dsn: process.env.NEXT_PUBLIC_HANZO_EVENT_DSN }}>
<ErrorBoundary fallback={(err, reset) => <Crash error={err} onReset={reset} />}>
<App />
</ErrorBoundary>
</AnalyticsProvider>
try { risky() } catch (err) { analytics.captureError(err, { properties: { where: 'checkout' } }) }
Each report goes to both planes:
- Sentry — a real Sentry envelope to the DSN's ingest route. This is the only thing that creates an issue in the error dashboard, with grouping and stack frames. Sent one envelope per error, immediately; batching a crash report is how you lose it.
- the event stream — a
type:'error'event; Cloud folds the exception intoproperties.$exceptionand stampsevent_type='error', so the error stays correlated with the session's pageviews (GET /v1/errors). This is product signal, not error tracking, and it never reaches Sentry on its own.
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,
and a failure on one plane cannot suppress the other.
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).
The ingestKey authenticates the event stream ONLY. The error plane
authenticates independently with the DSN key on ?sentry_key=, and the two
credentials are never sent to each other's host. A public page that wants errors
in Sentry needs the dsn as well:
createAnalytics({
product: 'site',
host: 'https://api.hanzo.ai',
ingestKey: 'pk_live_…', // event stream
dsn: process.env.NEXT_PUBLIC_HANZO_EVENT_DSN, // error plane
})
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.