About this Codelab
How to name events and properties so analytics stays usable as the product grows, instead of becoming hundreds of one-off strings.
Topics: amplitude, product-analytics, event-taxonomy. Language: JSON.
The most common mistake is naming events after the screen they fire from (HomeScreenButtonClicked) instead of the action a user took (Call Started, Report Exported). Screen names change with every redesign — your design team will absolutely rename “Home” to something else next quarter — but the underlying action usually doesn’t. A taxonomy organized around actions survives UI churn; one organized around screens has an expiration date baked in.
A convention that scales: Object Action, both in title case — Call Started, Export Requested, Plan Upgraded. This keeps the event list groupable in Amplitude’s UI by object (all Call * events together) without needing a separate naming registry to remember which events exist.
Don’t create Call Started — Cloud and Call Started — SIM as two events. Use one Call Started event with a medium: "cloud" | "sim" property. This keeps funnels and retention charts comparable across variants instead of fragmenting the same user action into events that can’t be summed.
Mixing these up shows up later as identical event properties repeated on every single event call, when they should have been set once via identify.
If the same logical action can fire from two code paths (a retry button and an automatic retry), give both a shared trigger property (manual / automatic) under the same event name, rather than letting the two call sites drift into separate, inconsistently named events over time.
A spreadsheet with event name | trigger condition | properties | owner that’s actually kept up to date is worth more than a fully normalized schema nobody maintains — a beautiful doc nobody opens does less for you than an ugly one everyone checks before shipping. Treat the taxonomy doc as the thing PRs are reviewed against, not a one-time design exercise.
The taxonomy doc only stays useful if it’s actually part of the review process for new events — otherwise it drifts out of sync with the codebase within a few sprints, and nobody trusts it enough to consult it, which makes it worthless even though it’s technically still there. Treating “does this new event fit an existing object, or does it need a genuinely new one” as a real review question, the same way a schema migration gets reviewed, keeps the taxonomy doc accurate enough to actually rely on months later.