Funnel Instrumentation

• Define funnel steps as events that fire on real user intent
• Handle retries, auto-refires and double-counting in step events
• Version funnel definitions safely

• Server-side retries silently inflate step counts — 3 payment attempts become 3 conversions.
• Client-side 'page view' steps misfire for bots, prerenderers and cached reloads.
• Confusing 'user reached' (UI) with 'user succeeded' (server confirm) corrupts both.
• Versioning steps lets you change definitions without breaking trend lines.

A museum whose turnstile double-counts people stepping out for air reports phantom attendance. Funnel steps that fire on retries are the same double-count.

• Select the genuine-intent event for each step (order_confirmed from the server, not order_clicked from the UI).
• Add a stable unique key (session_id + step_id or event_id) so dedupe is deterministic.
• Decide the capture layer by step meaning: intent markers client-side, confirmed outcomes server-side.
• Set the timing convention (event time vs processed time) and keep it consistent across steps.
• Version funnel definitions (v1/v2) and run both during migrations for a comparison window.

• A checkout funnel uses order_confirmed (server) as the terminal step because order_clicked double-counted on retries by 40%.
• A mobile app dedupes 'payment_started' by a client-generated attempt UUID, so a failed network retry doesn't inflate the step.
• An adoption funnel versioned its activation step from v1 to v2 after a UI change and kept both active for a month to compare apples.

• Instrument committed outcomes server-side wherever truth matters (payment, order, signup).
• Attach a unique attempt/event id to every step event so dedupe is never approximate.
• Keep a definition comment on each step: trigger, layer, dedupe rule, version.
• QA the funnel on a staging build with a known script of user actions before launch.

• Firing a step on every element render (React effects, page visibility) instead of on user intent.
• Counting server-side the same step the client also emits — the funnel never 'closes' and steps balloon.
• Retry loops that spam the endpoint: 5 attempts, 5 events, 1 conversion.
• Deleting the old step event on migration, silently rewriting the funnel's history.

• If a step conversion >100%, compare event sources — one step is client-fired, the other server-fired for the same logical action.
• Step volume way above UI events? Filter for events without the session/attempt id or with bot user agents.
• After a deploy, diff step counts day-over-day before analyzing the funnel itself.
• To validate a step, replay a known user's journey and confirm exactly one event per intended action.