The workspace declared pkg/* and pkgs/* both, so one repo had two names for one concept and a package's home was a coin toss. The shared build tooling already lived in pkg/ui/scripts and pkgs reached back into it two levels up; now it is a sibling. hanzo.yml gates on pkg/ui, so the published library stays where CI already looks and the rest joins it. The publish glob follows: one root, one pattern, nothing invisible to it. Co-authored-by: Hanzo Dev <[email protected]>
14 KiB
Hanzo product analytics — the taxonomy
The canonical event vocabulary, property rules, identity semantics, and funnels for hanzo.ai, hanzo.app, and hanzo.chat. One definition, three surfaces.
Why this document lives here
The taxonomy is code, not prose: src/events.ts (EVENTS), src/funnels.ts
(FUNNELS, PRODUCTS), src/goals.ts (GOALS, COHORTS). All three apps
already import { EVENTS } from '@hanzo/event', so this package is the only
place a definition can live and be used rather than merely described.
It is deliberately not in hanzo/insights. Insights is the read lens — it
renders whatever arrives. A funnel defined there could name an event no surface
emits and nobody would find out; a funnel defined next to EVENTS cannot, because
funnels.test.ts fails the build. Docs that sit apart from the constants they
describe drift within a release. These do not.
@hanzo/event ── EVENTS ──┬── hanzo.ai (product: 'site')
FUNNELS ├── hanzo.app (product: 'app')
GOALS ├── hanzo.chat (product: 'chat')
└── insights.hanzo.ai (reads; never defines)
1. The rules
Naming
| Rule | Yes | No |
|---|---|---|
snake_case, <object>_<verb-past> |
deploy_succeeded |
DeploySuccess, deploy-ok |
| Names are constants, never interpolated | deploy_succeeded + {framework:'static'} |
deploy_static_succeeded |
| Dimensions are properties | plan_clicked + {plan:'pro'} |
pro_plan_clicked |
No product prefix — product is already on the wire |
chat_started |
chat_app_chat_started |
$ is reserved for the client |
$pageview (emitted by pageview()) |
any app-authored $name |
| One name per user-visible moment, shared by all surfaces | signup_completed everywhere |
signup_done / registered |
Enforced by funnels.test.ts (event vocabulary block). Adding a name means
adding it to EVENTS — a raw string in capture() is a bug, and the string will
be invisible to every funnel.
Properties
Every event already carries, with no app code: messageId, type, timestamp,
distinctId, anonymousId, personId, sessionId, product, referrer,
utm.*, channel, refCode, signupWeek, library, libraryVersion. Never
re-send these as properties.
App-supplied properties:
- Low cardinality, enumerated.
mode,framework,plan,source,endpoint,model,provider,status,reason. A property whose value space is unbounded is a log line, not a dimension. - Never user content. No prompt, message, project name, file path, URL, email, or org display name. The client is PII-free by construction; keep it so.
- Booleans read as predicates:
hasPrompt,hasImages,isUpdate. - Durations are
durationMs(number, milliseconds). Outcome events own their duration, which is why there is no paired*_startedfor generations. - Money never goes in properties — use the commerce fields on
capture():capture(EVENTS.ORDER_COMPLETED, { kind: 'plan' }, { productId, revenue, currency, quantity }). - Errors are events.
captureError(err, { properties: { where: 'publish' } })puts the exception in the sentry lens on the same stream, so a funnel drop joins to the exception that caused it. Always passwhere.
Identity — identify and group
Exactly one place per app, mounted where the session resolves. Never at a call site.
analytics.identify(user.id) // the stable IAM subject (OIDC `sub`). NEVER email.
analytics.group(orgId) // the org
identifyjoins a person's pre- and post-login events, and joins them across surfaces (the same subject arrives from Cloud server-side). Traits, if any, must be non-PII (plan,role).groupis what makes org-level questions answerable — "which orgs stalled before their first deploy?" Cloud already resolves the tenant server-side for billing and stamps it;group()is the analytics dimension, and without it no B2B funnel exists. It was missing everywhere before this revision.setCohort({ signupWeek })is stamped once, at account birth, so every later event carries the acquisition week and retention curves are free.- Never send email, name, or phone. Not as a trait, not as a property.
Cross-origin identity — the honest limit
hanzo.ai, hanzo.app, and hanzo.chat are different origins. A logged-out
visitor therefore has a different anonymousId on each; nothing joins them.
Only personId (post-login) spans surfaces.
So a funnel that crosses origins while logged out is declared
join: 'aggregate' in FUNNELS and read as step-over-step counts, never as
a per-person conversion rate. The join key is an explicit property: the hanzo.ai
composer appends ?hz_ref=site, and hanzo.chat stamps referrerProduct:'site'
on its own chat_started. Measurable, without cross-domain tracking.
2. The funnels
Machine-readable in src/funnels.ts; GOALS reference them by id.
hanzo.ai — land → signup → activation
$pageview ──▶ signup_viewed ──▶ signup_submitted ──▶ signup_completed ──▶ first_action
(land) (/signup) (redirect to IAM) (/auth/callback) {action:'api_call'}
FUNNELS.signup + FUNNELS.apiActivation. IAM hosts the form, so submitted is
the redirect into IAM and completed is the return. first_action{action: 'api_call'} is emitted server-side by Cloud on an org's first successful
/v1 request — a browser cannot observe it, and this is the only step that
proves the account was worth acquiring.
Secondary: FUNNELS.upgrade (pricing_viewed → plan_clicked → checkout_started → order_completed) and FUNNELS.siteToChat (the composer handoff, aggregate).
hanzo.app — describe → build → ship
$pageview ──▶ build_started ──▶ generation_completed ──▶ deploy_started ──▶ deploy_succeeded
(land) (composer) (working build) (publish) (live URL)
FUNNELS.appShip. The product thesis in five steps. deploy_succeeded fires
only when a live URL is in hand — never inferred from "started and no error".
The first one also emits first_action{action:'app_live'}.
hanzo.chat — visit → first message → answer
$pageview ──▶ chat_started ──▶ chat_message_sent ──▶ generation_completed
(land) (new convo) (per message) (answer, durationMs)
FUNNELS.chatEngage. chat_started carries referrerProduct when the visitor
came from the hanzo.ai composer. model_switched is the quality signal that
sits beside the funnel: a switch mid-conversation usually follows a bad answer,
and fromModel/model is what makes "which model gets abandoned" answerable.
Return/retention is a cohort question (signupWeek × $pageview), not an event.
3. Emit sites — what exists, what is missing
Verified against the trees at the time of writing. ✅ = emitting, ❌ = not emitted.
hanzo.ai (~/work/hanzo/hanzo.ai, product: 'site')
| Event | Where | State |
|---|---|---|
$pageview |
app/providers.tsx (AnalyticsProvider + usePageview) |
✅ |
identify / group |
app/providers.tsx:72,75 (Identity) |
✅ added |
signup_viewed |
app/(marketing)/signup/page.tsx:19 |
✅ |
referral_used |
app/(marketing)/signup/page.tsx:21 |
✅ |
signup_submitted |
app/(marketing)/signup/page.tsx:24 |
✅ |
signup_completed |
app/(marketing)/auth/callback/page.tsx:39 |
✅ added |
login_completed |
app/(marketing)/auth/callback/page.tsx:41 |
✅ added |
setCohort({signupWeek}) |
app/(marketing)/auth/callback/page.tsx:38 |
✅ added |
| auth-exchange failure | app/(marketing)/auth/callback/page.tsx:49 |
✅ added |
chat_started |
components/home/ChatHero.tsx:58,66, components/home/LandingNav.tsx:90 |
✅ |
feature_used |
components/home/ChatHero.tsx:63 |
✅ |
pricing_viewed |
app/(marketing)/pricing/page.tsx:34 |
✅ |
plan_clicked |
components/pricing/PricingPlan.tsx:43 |
✅ |
waitlist_joined / _shared |
app/(marketing)/research-access/page.tsx:95, components/referrals/ReferralLink.tsx:27,47 |
✅ |
referral_claimed |
components/referrals/TryFreeCoupon.tsx:32 |
✅ |
checkout_started |
app/(marketing)/account/billing-plans/page.tsx:90 (checkout(planId)) |
❌ missing |
order_completed |
— (server-side; commerce owns the truth) | ❌ missing |
api_key_created |
— (no key UI on this site; console.hanzo.ai owns it) | ❌ n/a here |
first_action{action:'api_call'} |
— (Cloud, on first successful /v1 request) |
❌ missing — server-side |
hanzo.app (~/work/hanzo/app, product: 'app')
| Event | Where | State |
|---|---|---|
$pageview, errors |
components/providers/analytics.tsx (AnalyticsRoot) |
✅ |
identify |
components/providers/analytics.tsx:47 |
✅ |
group |
components/providers/analytics.tsx:55 |
✅ added |
build_started |
components/build-composer/index.tsx:173 |
✅ fixed (was app_created — intent mislabelled as creation) |
chat_message_sent |
components/chat-panel/index.tsx:242 |
✅ |
generation_completed |
components/workspace/index.tsx:1051 |
✅ added |
generation_failed |
components/workspace/index.tsx:1065,1092 |
✅ added |
project_created |
components/project-manager/index.tsx:299 |
✅ |
deploy_started |
components/editor/deploy-button/content.tsx:61 |
✅ |
deploy_succeeded |
components/editor/deploy-button/content.tsx:156 |
✅ added |
first_action{action:'app_live'} |
components/editor/deploy-button/content.tsx:164 |
✅ added |
deploy_failed |
components/editor/deploy-button/content.tsx:95,183 |
✅ added |
pricing_viewed / plan_clicked |
app/pricing/page.tsx:87,99 |
✅ |
signup_viewed / _submitted |
app/signup/page.tsx:26,30 |
✅ |
signup_completed |
— (this app has no IAM callback route of its own) | ❌ missing |
hanzo.chat (~/work/hanzo/chat, product: 'chat')
| Event | Where | State |
|---|---|---|
$pageview |
client/src/Providers/AnalyticsProvider.tsx |
✅ |
identify |
client/src/Providers/AnalyticsProvider.tsx (AnalyticsBridge) |
✅ |
chat_started (+ referrerProduct) |
client/src/hooks/Chat/useChatFunctions.ts:138 |
✅ enriched |
chat_message_sent |
client/src/hooks/Chat/useChatFunctions.ts:144 |
✅ |
generation_completed |
client/src/hooks/SSE/useSSE.ts:138 |
✅ added |
generation_failed |
client/src/hooks/SSE/useSSE.ts:251 |
✅ added |
model_switched |
client/src/components/Chat/Menus/Endpoints/ModelSelectorContext.tsx:233 |
✅ added |
group |
— (no org concept in the chat session today) | ❌ missing |
signup_completed |
— (IAM session-bridge, no callback route here) | ❌ missing |
4. Known gaps — ranked
- hanzo.app runs a second, parallel telemetry pipe.
lib/telemetry/(config.ts,tracker.ts,events.ts) POSTs its own vocabulary (task_started,task_complete,task_fail,model_selected,pageview,heartbeat) with its own visitor id and its own batching tohttps://console.hanzo.ai/api/public/otel/v1/traces. That is a frontend host, with an/api/prefix, and a vocabulary disjoint from this one — so nothing in that stream can be joined to a funnel in this one. Both fire today atcomponents/workspace/index.tsx(track('task_complete')besidecapture(GENERATION_COMPLETED)). Fix: reducelib/telemetry'strack()to a thin adapter over the shared@hanzo/eventclient (name-maptask_complete → generation_completed,model_selected → model_switched), deletetracker.ts+config.ts, and the duplicate queue/retry/heartbeat/visitor-id machinery goes with it. first_actionis emitted by nobody on the API path. Activation — the one metric that matters — needs Cloud to emitfirst_action{action:'api_call'}on an org's first successful/v1request.FUNNELS.apiActivationis specified and unmeasurable until it does.hanzo.appnow covers its own variant (action:'app_live').checkout_started/order_completedare unwired.hanzo.ai'saccount/billing-plans/page.tsx:90callscheckout(planId)and captures nothing, soGOALS.salehas no data andFUNNELS.upgradetruncates atplan_clicked.- No org on hanzo.chat.
group()is absent because the chat session carries no org today; chat funnels are person-scoped only. - Logged-out reach depends on a publishable key. Anonymous events need
ingestKey(pk_…, write-only) or they fail closed at the edge.NEXT_PUBLIC_HANZO_INGEST_KEY(hanzo.ai),NEXT_PUBLIC_PUBLISHABLE_KEY(hanzo.app),VITE_HANZO_INGEST_KEY(hanzo.chat) are read but must be provisioned per org viaPOST /v1/ingest/keys. Config, not code.
5. Adding an event
- Add the constant to
EVENTSinsrc/events.ts— with a comment saying which decision it informs. If you cannot name one, do not add it. - If it is a funnel step, add it to the funnel in
src/funnels.ts. If it is a conversion, point aGOALSentry at that funnel id. pnpm test— the drift guard will reject a step whose event does not exist.- Emit it from one place per app, with enumerated properties only.
- Bump the patch version; the
hanzoai/uipublish workflow ships it on merge tomain, and apps pick it up on their next install.