Analytics Events That Answer a Question

1// The registry IS the contract. Adding a property is fine;
2// renaming one is a breaking change for every query downstream.
3type Events = {
4  CheckoutStarted:   { flowId: string; itemCount: number; currency: string }
5  CheckoutStepViewed:{ flowId: string; step: 'address' | 'payment' | 'review'; stepIndex: number }
6  CheckoutCompleted: { flowId: string; orderId: string; itemCount: number }
7  CheckoutFailed:    { flowId: string; step: string; reason: 'declined' | 'network' | 'validation' | 'unknown' }
8}
9 
10function track<K extends keyof Events>(name: K, props: Events[K]) {
11  queue.push({
12    id: crypto.randomUUID(),        // at-least-once delivery needs a dedupe key
13    name,
14    props,
15    at: Date.now(),
16    ctx: {
17      buildId: __BUILD_ID__,        // which client produced this
18      route: normalisedRoute(),     // '/orders/:id', never '/orders/8842?token=…'
19      variant: assignedVariants(),
20    },
21  })
22}
23 
24// Emitted where the domain fact happens — not in a click handler,
25// so it fires identically for pointer, keyboard and programmatic paths.
26function beginCheckout(cart: Cart) {
27  const flowId = crypto.randomUUID()
28  track('CheckoutStarted', { flowId, itemCount: cart.items.length, currency: cart.currency })
29  return flowId
30}

Two details do most of the work. flowId is what turns four independent counters into a funnel. Emitting from beginCheckout rather than from a handler is what makes the measurement independent of how the user triggered it (Keyboard Events).

1. 1
   Domain fact occurs

   The code that actually starts a checkout emits the event.

   fails by Being wired to a click handler, so keyboard, programmatic and restored-session paths are missing (How an Event Is Dispatched is not intent).

2. 2
   Enrich

   Adds event id, timestamp, build id, normalised route, variant assignment.

   fails by Adding location.href wholesale, carrying identifiers and query strings off-origin.

3. 3
   Consent gate

   Decides whether this may leave the browser at all.

   fails by Living inside the SDK rather than in front of it, so the SDK has already loaded and phoned home.

4. 4
   Queue

   Buffers in memory, with an overflow policy and optional persistence for offline.

   fails by Growing without bound in a long-lived tab (Memory Leaks).

5. 5
   Batch send

   Posts a group of events on an idle callback or a timer, off the interaction's critical path.

   fails by Sending synchronously inside the handler and adding latency to the interaction being measured.

6. 6
   Flush on hide

   On visibilitychange to hidden, sends the remainder with sendBeacon or keepalive.

   fails by Waiting for an unload event that a backgrounded mobile page will never fire.

7. 7
   Ingest and dedupe

   Validates against the schema and drops repeats by event id.

   fails by Accepting anything, so a renamed property becomes a silently null column.

Every step in this pipeline is a place data is lost, and the losses are correlated with bad experiences — slow networks, crashed tabs, abandoned flows. Read every funnel with that in mind.

• Normalise the route, never send the raw URL. /orders/:id is the analytical unit; /orders/8842 is an identifier.
• Allow-list query parameters. Deny by default; a token or a search term will otherwise arrive eventually.
• Bucket continuous values. A file size band answers the question a byte count does, and identifies nobody.
• Never send user-authored text — queries, message bodies, form values, or the rendered text of the element that was clicked.
• Gate before the SDK loads, not inside it. Consent that runs after the script is a preference, not a control.
• Set a referrer policy so third-party requests do not carry your URLs even when your payload does not (Content Security Policy).
• Mask by default in session replay, and treat every unmasked region as a deliberate, reviewed decision (Session Replay and the Privacy It Costs).

track('search', {
  url: location.href,
  // 'https://app.example.com/orgs/acme-health/search
  //   ?q=patient%20readmission%20jane%20doe&invite=8f2a…'
  title: document.title,        // 'Acme Health — Search'
  text: el.innerText,           // 'Open Jane Doe — 1984-03-02'
  userEmail: user.email,
})

// Sent to a vendor, retained under their policy, and now
// subject to an erasure request you cannot service.

track('SearchPerformed', {
  route: '/orgs/:slug/search',  // pattern, not instance
  queryLength: q.length,        // shape, not content
  hasFilters: filters.length > 0,
  resultCount: bucket(results.length),  // 0 | 1-9 | 10-99 | 100+
})

track('SearchResultOpened', {
  route: '/orgs/:slug/search',
  rank: index,                  // answers 'are the top results good?'
  resultType: 'patient',        // a type, never an identity
})

The right-hand version answers the same questions — is search returning results, are the top ranks the ones people open — while carrying nothing that identifies a person or a customer. The minimisation is not a compliance tax added afterwards; it is the same design step that made the events queryable, because a bucketed count aggregates and a raw query string does not (Sensitive Data Classification).