Event Naming Conventions That Prevent Telemetry Rot

As digital products evolve, analytics tracking code frequently degrades into what we term telemetry rot. One squad fires user_clicked_signup_btn, another emits registration_started, and a third records account_create_v2. The result is fragmented event funnels, broken historical reporting, and engineering friction.

At WebFlow Base, we enforce a strict Object-Action Taxonomy across every client audit and tracking plan we design.

1. The Core Object-Action Pattern

Every event should describe a concrete entity (noun) undergoing a specific state transition or action (past-tense verb):

[domain] . [noun_entity] . [action_verb]

Examples:

• auth.session.created (User logs in or creates a session)
• onboarding.step.viewed (User navigates to a setup step)
• checkout.payment_method.selected (User picks a payment channel)
• workspace.member.invited (User triggers a team invite)

Avoid embedding UI presentation details into the event name itself (e.g., blue_button_clicked or modal_popup_opened). Instead, pass UI location and component variants as structured event properties.

2. Standardized Context Properties

Every event dispatched within your conversion funnels should carry a standardized baseline payload:

interface StandardTelemetryPayload {
  // Global Identifiers
  user_id: string | null;
  anonymous_id: string;
  session_id: string;

  // Flow Context
  flow_name: string;           // e.g. "team_onboarding"
  flow_version: string;        // e.g. "2026.1"
  step_index: number;          // e.g. 2
  step_total: number;          // e.g. 5
  step_name: string;           // e.g. "organization_details"

  // Environment
  platform: 'web' | 'ios' | 'android';
  app_version: string;
  client_timestamp: number;
}

By ensuring this context payload is injected globally via a centralized telemetry wrapper, individual engineers only need to specify domain-specific parameters when calling track().

3. Automated Schema Validation in CI/CD

Documentation alone cannot prevent tracking drift. We recommend validating event payloads at compile time using TypeScript union types or JSON Schema validators in your automated test suite.

Catching tracking discrepancies during pull request review guarantees that your conversion path analysis remains continuous, dependable, and audit-ready.