Well-known events: why standard event names matter

Every analytics setup eventually runs into the same problem: the data is messy because the events were named inconsistently. One developer sends signup, another sign_up, a third Signed Up. Now they’re three different events, and every funnel and retention report is wrong. Well-known events fix this by standardizing the names (and often the properties) of the events products commonly track.

What makes an event “well-known”

A well-known event is a predefined event name with an agreed meaning and, ideally, a typed set of properties. Instead of inventing a name, you pick the standard one: add_to_cart, purchase, login, and fill in its expected properties. Free-form custom events still have their place for things unique to your product; well-known events cover the common ground everyone needs.

Why they help

• Consistency. One canonical name per concept means no signup/sign_up drift fragmenting your reports.
• Typed properties + validation. A purchase that requires a product ID, amount, and currency catches malformed data at the source, before it pollutes a dashboard.
• Faster setup. A shared vocabulary means less to invent and fewer decisions; new teammates already know what the events mean.
• Portability. Standard names map cleanly between analytics tools, so migrating or running two tools in parallel doesn’t mean re-instrumenting everything.
• Analysis out of the box. When a tool recognizes checkout_started → purchase, funnels and revenue reports work without custom wiring.

A naming convention that scales

The single most valuable thing you can do is pick a naming convention and apply it to every event without exception. The widely used pattern is object_action, in snake_case, past tense: the thing, then what happened to it:

order_completed
subscription_started
video_played
invite_sent

The rules that matter: lowercase always (Signup and signup are two events in most tools), one consistent separator (underscores), past tense for actions, and a noun-first object so related events sort together (cart_viewed, cart_updated, cart_cleared). The specific convention matters less than never deviating from it. Property names deserve the same discipline, pick camelCase or snake_case for properties and keep it uniform, because productId and product_id won’t merge either.

Properties: the data that makes events useful

An event name tells you what happened; properties tell you the details you’ll actually slice by. A bare purchase event can answer “how many purchases?”, but with amount, currency, and productId it can answer “what’s revenue by product this month?”. The art is attaching enough to be useful without dumping everything:

• Required vs optional. Some properties are the point of the event, a search without a query is useless. Typed schemas mark these required so they’re never missing.
• Consistent units and types. Always send amounts as numbers in a known currency, timestamps in one format, IDs as strings. Mixed types are the quiet killer of clean analysis.
• Identifiers, not labels. Prefer a stable productId over a display name that changes; you can always join names back in later.

The events most products should track

A practical taxonomy, grouped by what they describe:

• Navigation: page_view
• Interaction: click, scroll, form_start, form_submit, rage_click, dead_click
• Commerce: add_to_cart, checkout_started, checkout_completed, purchase
• Authentication: signup, login, logout
• Engagement: search, video_play, video_pause, share, notification_received, notification_clicked
• Errors: error_occurred

A worked example: an e-commerce checkout

Standard names pay off most when several events describe one journey. A checkout flow maps cleanly onto four well-known events, each carrying the same shape of properties:

track('add_to_cart',      { productId: 'sku_42', amount: 29, currency: 'USD' })
track('checkout_started', { productId: 'sku_42', amount: 29, currency: 'USD' })
track('checkout_completed', { productId: 'sku_42', amount: 29, currency: 'USD' })
track('purchase',         { productId: 'sku_42', amount: 29, currency: 'USD' })

Because the names are standard and the properties are consistent, a funnel from add_to_cart to purchase works immediately. You can see the drop-off at each step, and break it down by product or source without renaming anything. Use the same names on web and server (a server-confirmed purchase is more trustworthy than a client one), and the events line up on one timeline per person.

Common event-tracking mistakes

• Naming drift. The same action under several names. A linter that enforces one convention prevents it.
• Inconsistent casing. Purchase, purchase, and PURCHASE counted separately. Lowercase everything.
• Over-tracking. An event for every micro-interaction creates noise you’ll never analyze. Autocapture handles the long tail; reserve named events for moments that matter.
• PII in properties. Putting emails, names, or full addresses into event properties is a privacy and compliance risk. Keep identifiers on the profile instead of scattering them through events.
• Free-form everything. No standard names, no typed properties. Every report becomes archaeology. Start from a known vocabulary instead.

Typed, validated events in Pug

In Pug, well-known events get typed properties and are validated at the moment you call track(): extra properties are still allowed and sent alongside, so you’re never boxed in. A purchase missing its currency is caught and logged rather than silently stored wrong. The schemas come from Pug’s shared event definitions, so the same well-known names mean the same thing across the web, server, and mobile SDKs. For autocaptured interactions like clicks and rage clicks, see autocapture; for the full developer story, the Web SDK deep-dive.

Plan and lint your events

Good event hygiene starts before you write tracking code. Three free tools help: the event tracking-plan generator gives you 127 well-known event kinds with typed properties and PII flags to start from, the event naming linter checks your names against a consistent object_action, snake_case convention, and the PII & GDPR event auditor flags properties that may carry personal data. Decide the vocabulary once, and every report downstream gets cleaner for it.