Most tracking problems start before any tag is written. Different teams name the same action differently, parameters are sent inconsistently, and nobody knows which events matter. An event specification fixes this: a single document that defines what's tracked, when, with which details, and who owns it.
What each row needs
- Event name: snake_case, object then action where possible (
form_submit,video_start). Use your analytics tool's recommended names where they fit, such asgenerate_lead,sign_upandpurchasein GA4. - Trigger: exactly when it fires ("on successful submission", not "on button click").
- Parameters: the details sent with it, their format and allowed values.
- Key event: whether it counts as a business outcome.
- Owner: the team responsible for it.
- Status: proposed, implemented, tested, live.
Write triggers developers can test
"When the user submits the form" is ambiguous: before or after validation? Write "when the form is submitted and the server confirms success". Clear triggers prevent double-counting and phantom conversions.
Keep parameters consistent
- Same names for the same thing across events (
valueandcurrencyeverywhere, notpricein one andamountin another). - Defined formats: currency as a three-letter code, value as a number, IDs as strings.
- Allowed values listed for categories (
lead_type: demo, quote, callback).
Make it the source of truth
- Version it in a shared repository or document with a change log.
- Build from it: the data layer and tags implement the specification, not the other way round.
- Test against it: each release checks that events fire as specified.
- Review changes with analytics before they ship.
Start small
You don't need every interaction tracked. Start with the events that matter for decisions: key conversions and the main steps towards them. Add more when there's a question they would answer.
A good specification makes audits quick, onboarding easy and reports trustworthy. It's the single most useful document in analytics implementation.
