Skip to content
home

Analytics implementation · 2 min read

Writing an event specification developers will follow

One document that defines every event, parameter, trigger and owner, and keeps tracking consistent.

By WebIQ Analytics · 16 April 2026

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 as generate_lead, sign_up and purchase in 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.
An event specification: event, trigger, parameters, key event status and owner.EventWhen it firesParametersKey event?Ownergenerate_leadLead form submittedsuccessfullyform_id, form_name, lead_typeYesWeb teamsign_upAccount createdmethodYesProductadd_to_cartItem added to basketcurrency, value, itemsNoEcommercepurchaseOrder confirmedtransaction_id, value, currency,itemsYesEcommerceview_pricingPricing page viewedplan_viewedNoMarketingUse recommended event names where they fit; snake_case; one owner per event.
An event specification: event, trigger, parameters, key event status and owner.

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 (value and currency everywhere, not price in one and amount in 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.

Tracking you can trust, with consent handled properly

We implement GA4, server-side tagging and Consent Mode v2, with an event specification your team can maintain.