Amir Mousavi

Notes

GA4 and GTM Notes

Updated · By Amir Mousavi

GA4 and Google Tag Manager stay maintainable when event names, parameters, triggers, consent behavior, and release notes follow a shared convention. These notes are the tool-side mechanics: the exact limits, the naming formats, the data layer push worth standardizing, and the debugging checks that catch quiet failures. The process around them — what to define first, what to verify, and who signs off — is the territory of the analytics implementation checklist linked below.

Event and parameter design

  • Model events around user actions, not page mechanics. form_submit survives a redesign; click_blue_button does not. Events named after the interface break the moment the interface changes, and the historical data becomes uninterpretable.
  • Reuse a small, consistent set of parameter names. One item_id used everywhere is worth more than five near-synonyms. Every redundant name spends one of a small number of custom-dimension slots — and the caps below are lower than most taxonomies assume.
  • Register custom dimensions deliberately, not reactively. Registration is not retroactive in practice: reports show a custom dimension only for data processed after it exists, so earlier collection is not recoverable through the interface — only a BigQuery export, if one was already running, keeps the raw parameter. Decide what needs to be reportable before collection starts.

The limits that shape the design

The finite resource is not figurative. These are the registration caps a taxonomy has to fit inside:

Custom definitionStandard propertyGA4 360
Event-scoped custom dimensions50125
User-scoped custom dimensions25100
Item-scoped custom dimensions1025
Custom metrics50125

Collection has bounds of its own: event and parameter names cap at 40 characters, a parameter value at 100 characters, and an event carries at most 25 parameters (GA4 360 raises the value length to 500 and the count to 100). Archiving a custom dimension frees its slot, but archiving cannot be undone, at the limit Google asks you to wait 48 hours before adding a new one, and nothing collected under a wasted slot is repaired retroactively — which is why the slots are worth budgeting before the first tag ships.

Naming conventions

  • Use lowercase, underscored, predictable event names. GA4 names are case-sensitive: sign_up, Sign_Up, and SIGN_UP collect as three parallel events, and nobody notices until a report splits. Lowercase with underscores also matches the recommended-event format, which keeps custom and built-in events visually consistent in reports.
  • Document the convention so new tags stay consistent. The convention is only useful if the next person implementing a tag can find it. Keep it where the work happens — a note in the container beats a document nobody opens.
  • Avoid synonyms for the same action across templates. signup, sign_up, and registration for one action produce three partial pictures and no complete one. Agree the verb list up front.

The convention itself fits in one table:

ElementConventionExample
Event nameslowercase snake_case, under 40 charactersform_submit
Parameter nameslowercase snake_case, one canonical name per conceptform_id
GTM tagsplatform prefix, then the event the tag sendsGA4 event — form_submit
GTM triggerstype prefix, then the conditionCE — form_submit
GTM variablestype prefix, then the data layer keyDLV — form_id

The data layer contract

Tags should read values the site pushes deliberately, never values scraped out of the rendered DOM. Scraped values depend on markup nobody promised to keep, so tracking breaks silently the day a developer renames a CSS class — and silent failure is worse than loud failure. The push below is the contract worth standardizing:

window.dataLayer = window.dataLayer || []

// Pushed by the site template, before the trigger listens for it.
window.dataLayer.push({
  event: 'form_submit', // matches the Custom Event trigger, case included
  form_id: 'newsletter', // registered as an event-scoped custom dimension
  form_destination: '/api/subscribe',
  form_length: 2, // a real number — GA4 will not coerce the string "2"
})

The event key is what a GTM Custom Event trigger matches, casing included — which is where parallel events usually start. Types travel as pushed: GTM passes values through untouched, so a numeric field sent as a string stays a string all the way into reports.

Container hygiene

  • Prefer fewer, well-named triggers over many ad hoc ones. Duplicate triggers with slightly different conditions are the usual cause of double-counted events. One trigger reused across tags is easier to reason about than five that nearly match.
  • Use folders, naming, and notes to keep the container readable. Containers are inherited more often than they are built. A prefix convention that groups tags by purpose is what makes the next person able to change something safely.
  • Version and document significant changes. Write what changed and why in the version notes at publish time. GTM keeps version history, so a documented version is the difference between a thirty-second rollback and an afternoon of guessing.

Debugging

  • Validate in Preview and the GA4 DebugView before publishing. Preview shows whether the tag fired; DebugView shows what GA4 actually received. Both are needed, because a tag can fire correctly and still send the wrong payload.
  • Check parameter values, not just that an event fired. Confirm the value is present, the right type, and not the string "undefined" — that one usually traces to a misspelled Data Layer Variable, which resolves to undefined and is cast to text on the way out. A numeric parameter sent as a string looks identical in DebugView and quietly refuses to aggregate in reports.
  • Watch for duplicate or double-counted events. Common causes are a tag firing on both a history change and a page view, or the same tag deployed in the container and hardcoded on the page. Check event counts against a known-good session rather than assuming.

These notes pair with the analytics implementation checklist linked below, which covers the process side — what to define, what to verify, and who signs off — before any of this is built. One definition worth writing down now: GA4’s AI Assistant channel, added on May 13, 2026, counts referrals from named assistant products and leaves Google’s AI Overviews and AI Mode in Organic Search, which is why AI search traffic needs four separate reports rather than one GA4 number.

Sources

Factual claims on this page were checked against these primary sources on October 10, 2026:

Related reading