After a year of tracking without rules, a site's list of events looks like a drawer full of cables: button_click, Click Button, cta_home, signup, signup_ok, newsletter-2. Nobody remembers who created them or exactly what they measure. An event taxonomy is the set of rules that prevents this mess: what events are called, which properties go with them and where they are documented.
Events, properties and values
It helps to fix the vocabulary first:
- event: an action that happened at a specific moment, for example "form submitted";
- property (or parameter): a piece of information describing the event, for example "form name";
- value: the content of the property, for example "quote request".
The most common mistake is encoding values into the event name. submit_form_quote, submit_form_contact and submit_form_newsletter are three different events you have to add up by hand. form_submitted with a form_name property is a single event that can be filtered any way you like.
A naming convention
There is no absolutely right convention, but you need one, applied every time. A common and robust choice is:
- object + action, in the past tense:
form_submitted,video_started,file_downloaded; - lower case with underscores (snake_case), no spaces or accented characters;
- a single language for all technical names;
- verbs from a closed list: for example viewed, clicked, started, completed, submitted, failed.
The object-action order has a practical benefit: in an alphabetical list of events, everything relating to forms ends up together.
form_started
form_submitted
form_failed
video_started
video_completed
file_downloaded
Choosing properties
For each event ask yourself which questions you will want to ask. Properties answer "which", "where" and "how much":
| Event | Properties | Example value |
|---|---|---|
form_submitted |
form_name, position |
quote, footer |
file_downloaded |
file_name, file_type |
price-list-2025, pdf |
video_started |
video_title, duration_seconds |
installation, 245 |
search_performed |
terms, result_count |
nas backup, 0 |
A few rules keep properties clean:
- reuse the same property names across events when they mean the same thing:
positionmakes sense both for a click and for a form; - prefer values from a closed list over free text where possible;
- state the data type, text, number or boolean, and do not mix them;
- never include personal data: email addresses, names, phone numbers or customer identifiers in clear text.
Global properties
Some information is needed on almost every event: page type, site language, the user's login state (anonymous or signed in), application version. Rather than repeating it in the code of each event, set it once as global properties that the tool attaches automatically. You cut errors and duplication.
The event dictionary
The taxonomy lives in a document, the event dictionary or tracking plan. For each event it records:
- the exact name;
- a one-sentence description: when it fires and when it does not;
- properties with their type and allowed values;
- where it is implemented, meaning page, component or file;
- creation date and last modification date;
- owner.
The description must be precise. "Fires when the user submits the form" leaves a question open: even if validation fails? Better: "fires when the server confirms receipt of the form". That precision prevents future arguments over numbers that do not match.
Renaming without losing history
Sooner or later an event will need renaming. Changing the name abruptly breaks the time series: reports show one event stopping and another starting from zero. A more careful approach:
- send both names during a transition period;
- note the date of the change in the dictionary and in any tool that supports annotations;
- after the transition, remove the old name from the code but not from the documentation.
In my work I prefer to avoid renames that are not strictly necessary: an imperfect but stable name is often worth more than a perfect one that changes every year.
Periodic review
Once a quarter it is worth comparing the events actually received with the dictionary. There are always surprises: documented events that no longer arrive, received events nobody documented, properties with unexpected values such as stray capital letters or empty strings.
In short
- Separate the event name from the values: one generic event with properties beats many specific events.
- Adopt a single convention, for example object plus action in snake_case, with verbs from a closed list.
- Use consistent properties across events and never include personal data.
- Document everything in an event dictionary with precise descriptions.
- Rename with a transition period and review the dictionary every quarter.
