Blog / Tools & automation /

A process for documenting GA4 event definitions

Open a GA4 report and you may find form_submit, submit_form, lead_sent and a generic click event, all looking like the same thing. If nobody can say what each one means, the report stops being a way to make decisions and turns into a wall of numbers.

Documenting GA4 event definitions is a small governance task with a big practical payoff. The goal is to make clear what an event represents, how it’s collected, who owns it and which events count as key events for the business.

Start with the user action

Describe the action in plain language before choosing an event name. “A visitor sends the consultation form successfully” is clearer than “lead event”. State what counts as success and what doesn’t: opening a form is different from sending it, and a validation error isn’t a completed submission.

Identify the page, interface and conditions involved. If an event fires from several forms, note whether a parameter identifies the form or each form needs a distinct event. Keep the structure useful without creating an event for every button label.

Separate user actions from system observations. A page view, an error, a video start and a completed transaction are different behaviours. Don’t use one event for several actions just because the reporting interface makes it convenient.

Create a definition record

For each event, document its name, purpose, trigger, parameters, examples, exclusions, data owner and implementation location. Note whether it’s automatically collected, recommended, custom or imported from another system. Include the date and environment where you verified the definition.

Use a naming convention people can read and maintain. GA4 names and parameter rules have platform constraints, so check current requirements before implementing. Readable names help analysts, but they don’t guarantee valid event collection.

List parameters with allowed values and a privacy review. Don’t send personally identifiable information or sensitive data in event names or parameters. If a parameter can contain user-entered text, define controls to stop accidental collection. The documentation should say what’s deliberately excluded.

Decide which events are key events

In GA4, “key events” is the current term for events designated as important to the business. Choose them on meaningful outcomes, not because they sit prominently in a report. A page scroll may help diagnose engagement but is rarely equivalent to an enquiry or purchase.

Document why each event is key and who approved the choice. If several teams share a property, align on the business meaning. Marketing and operations may both care about a form but define completion differently.

I don’t mark every event as key. When too many actions get equal emphasis, conversion reporting loses its meaning. Review the list when business goals or measurement needs change.

Validate implementation

Test the event in a suitable environment and inspect the actual payload. Confirm it fires once, at the intended moment, with the expected parameters, and not on an error or accidental repeat. Test common variations such as mobile, different form types and confirmation flows.

Compare debug evidence with reporting behaviour, remembering that processing and privacy settings can affect what appears. A successful test event doesn’t prove the production implementation or consent setup is right. Assign a separate live verification after release.

Record dependencies: tag manager containers, application code, plugins, consent tools and third-party integrations. A change in any of them can alter collection. Name an owner for each production implementation or shared measurement layer.

Manage changes and retirements

When an event changes meaning, don’t silently reuse the old name. Reports may combine incompatible behaviour over time. Document the change date and whether a new event is needed. If an event is retired, say why and identify the downstream reports or automations that depend on it.

Keep a changelog with release or ticket references. It explains why a chart shifts and stops future analysts mistaking a measurement change for a change in customer behaviour.

Schedule a review when the site changes forms, checkout, consent management or analytics architecture. Remove duplicate events and obsolete definitions carefully. A stale event can still feed a legacy report, so confirm dependencies before deleting anything.

Keep documentation usable

Store the definitions where analysts and implementers can find them. A shared table is enough if it’s maintained and linked from implementation tickets. Add examples and test evidence; long prose with no owner goes stale.

Use the document during planning, not only after an event breaks. Ask what decision the event supports and how its value will be read. I’d drop an event nobody can answer that for.

Keep reporting definitions aligned

An event definition should connect implementation language with the report a decision-maker sees. If a dashboard says “qualified lead” but the event records every form opening, the mismatch can survive for months. Link the dashboard field to the event definition and to the source system that confirms the outcome where one exists.

Be careful with attribution and deduplication. A browser event and a server event may both represent the same purchase or enquiry. Document how duplicates are handled and where the authoritative outcome comes from. Don’t assume GA4 is the source of truth for every business record.

Include a glossary for terms shared across marketing and operations. “Lead”, “submission” and “qualified enquiry” can mean different things to different teams. Agree on definitions before comparing reports.

Pick one event your team relies on. Could someone unfamiliar with the setup explain exactly when it fires, what its parameters mean and why it’s marked as a key event?