Google Tag Manager doesn't read your DOM. It doesn't scrape text from your page or guess what a button click means. It reads the dataLayer — a JavaScript array that your site populates with structured event data, and that GTM listens to in real time.
When the dataLayer is well-structured, GTM tags fire reliably with the right parameters and GA4 receives clean, consistent data. When it's poorly structured — events pushed before the page loads, missing fields, inconsistent naming — no amount of GTM configuration will fix what's broken at the source.
What the dataLayer actually is
The dataLayer is a plain JavaScript array declared on the page before GTM loads. Every time your site calls dataLayer.push(), it appends an object to that array. GTM watches for these pushes and can trigger tags, read values, and pass parameters into GA4 events.
The bare-minimum initialization belongs in the <head>, above the GTM snippet:
<!-- Initialize dataLayer before GTM loads -->
<script>
window.dataLayer = window.dataLayer || [];
</script>
<!-- Then your GTM snippet -->
<script>(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXXXXX');</script>The window.dataLayer = window.dataLayer || [] guard is important. If something else has already declared the array (a CMS plugin, a third-party script), you don't want to overwrite it and lose events that were already queued.
GTM and GA4 are separate concerns. GTM reads the dataLayer and fires tags. GA4 is one of those tags. Your dataLayer pushes define what data is available — your GTM configuration decides what gets sent to GA4 and how.
Page view enrichment
GA4 automatically collects page views, but the default event carries almost no useful context beyond the URL. Push additional data on every page load to give your reports something to work with:
// Push before GTM fires — typically server-rendered into the page
window.dataLayer = window.dataLayer || [];
dataLayer.push({
page_type: 'product', // 'home' | 'category' | 'product' | 'checkout' | 'confirmation'
content_group: 'Footwear', // maps to GA4's content_group parameter
user_id: '8821', // if authenticated; omit entirely if not
user_type: 'returning', // 'new' | 'returning'
ab_variant: 'checkout_v2' // any active experiment variant
});These values become available as GTM Data Layer Variables. Map them to GA4 event parameters in your GTM GA4 Configuration tag and they'll be attached to every event on the page — including the page_view.
E-commerce events
purchase
The purchase event is the most important push on any e-commerce site. It populates GA4's revenue metrics, feeds Smart Bidding in Google Ads, and is the one event you cannot afford to get wrong.
dataLayer.push({ ecommerce: null }); // Clear previous ecommerce data first
dataLayer.push({
event: 'purchase',
ecommerce: {
transaction_id: 'T-98231', // Required — must be unique per order
value: 149.95, // Required — revenue, not including tax/shipping unless intended
tax: 11.25,
shipping: 8.50,
currency: 'NZD', // Required — ISO 4217 code
coupon: 'SAVE10',
items: [
{
item_id: 'SKU-441', // Required — matches your product catalogue
item_name: 'Trail Runner X', // Required
item_brand: 'Apex',
item_category: 'Footwear',
item_category2: 'Running',
item_variant: 'Blue / 10',
price: 139.95, // Unit price
discount: 15.00,
quantity: 1,
coupon: 'SAVE10'
}
]
}
});Always push { ecommerce: null } before any ecommerce event. GTM merges dataLayer state, so a previous add_to_cart push can contaminate your purchase items array if you don't clear it first. This is the most common cause of inflated or duplicated item data in GA4.
add_to_cart
The structure mirrors purchase, just without the transaction fields:
dataLayer.push({ ecommerce: null });
dataLayer.push({
event: 'add_to_cart',
ecommerce: {
currency: 'NZD',
value: 139.95, // Total value of items being added
items: [
{
item_id: 'SKU-441',
item_name: 'Trail Runner X',
item_brand: 'Apex',
item_category: 'Footwear',
item_variant: 'Blue / 10',
price: 139.95,
quantity: 1
}
]
}
});Lead form submission
Lead gen sites don't have an items array, but they still benefit from structured pushes. Push after a successful form submission — not on button click, which fires even when validation fails:
dataLayer.push({
event: 'generate_lead',
form_id: 'contact-main', // Which form on the page
form_name: 'Contact Us',
lead_type: 'enquiry', // 'enquiry' | 'quote' | 'demo' | 'callback'
service_interest: 'Web Design' // What the user selected, if captured
});These parameters won't appear in GA4 automatically — you need to register them as custom dimensions first. See GA4 Event Parameters for how that works.
Event reference: required vs. optional parameters
The table below covers the most common events. "Breaks" means GA4 will either reject the event, zero out a metric, or show it in a degraded state if the parameter is missing.
| Event | Required parameters | Recommended optional | What breaks if skipped |
|---|---|---|---|
purchase |
transaction_id, currency, value, items[] |
tax, shipping, coupon, item item_category |
Revenue shows as $0; deduplication fails without transaction_id; item reports empty without items[] |
add_to_cart |
currency, value, items[] |
item_brand, item_category, item_variant |
Cart funnel metrics break; item-level analysis unavailable |
view_item |
currency, value, items[] |
item_list_name, item_list_id |
Product detail views unattributable to lists or categories |
begin_checkout |
currency, value, items[] |
coupon |
Checkout funnel step missing; cart abandonment rate unreliable |
generate_lead |
event name only |
value, currency, form_id, lead_type |
All leads appear identical; no lead quality segmentation possible |
sign_up |
method (e.g. 'email') |
user_type, plan |
Sign-up method breakdown unavailable in reports |
Naming conventions
GA4 uses snake_case for all event names and parameters. Stick to that convention throughout your dataLayer pushes — it makes GTM variable mapping predictable and keeps your GA4 reports consistent.
- Event names: use GA4's recommended event names where they fit (
purchase,add_to_cart,generate_lead). Only create custom event names when no standard equivalent exists. - Custom parameters: prefix them with your namespace if you have multiple teams pushing events — e.g.
shop_product_typerather than justproduct_type, which might collide with a third-party script. - Boolean values: use
true/false(not'yes'/'no'or1/0) so GA4 can apply the correct parameter type. - IDs: always send as strings, not numbers.
transaction_id: 'T-98231'nottransaction_id: 98231. GA4 treats them as dimensions, not metrics.
Five mistakes that corrupt your data
1. Pushing before the dataLayer is declared
If a script calls dataLayer.push() before window.dataLayer = window.dataLayer || [] runs, it throws a TypeError and the push is lost. Always declare the array at the very top of <head>, before any other scripts.
2. Not clearing ecommerce between events
GTM preserves dataLayer state across pushes. If you push add_to_cart on product page A, then push purchase without first pushing { ecommerce: null }, GTM may merge the two objects. The result: your purchase event contains the wrong items.
3. Missing or malformed items array
The items array must be an array of objects, even for single-item purchases. items: {} (an object) will be silently ignored. Every item object needs at minimum item_id or item_name — GA4 will not populate item reports without one of them.
4. Undefined variables in the push
If your server-side template renders value: {{ order.total }} and order.total is undefined, GA4 receives value: undefined — which it drops. Always guard against undefined before pushing: value: parseFloat(orderTotal) || 0. Check the GA4 DebugView to catch these silently dropped parameters.
5. Firing the event on button click instead of success callback
Triggering generate_lead on form submit button click means it fires even when validation rejects the form. Trigger only after a confirmed submission — in the success callback of your form handler or after a successful API response. For purchases, push on the order confirmation page, not the "place order" click.
Use GA4 DebugView to verify your pushes. Enable debug mode by adding ?gtm_debug=x to your URL (with GTM preview active) or by setting debug_mode: true in your GA4 config tag. DebugView shows every event and parameter in real time, including ones that arrive with no value.
Putting it together
A clean dataLayer implementation follows a predictable pattern: declare the array before GTM, push page-level context on load, and push event-specific data in response to user actions — always clearing the ecommerce object first for commerce events.
The payoff is GA4 data you can trust. When your purchase event consistently carries transaction_id, currency, and a valid items array, your revenue metrics are accurate, your funnel reports are complete, and Smart Bidding has the signal it needs. Everything downstream — attribution, audiences, key events — depends on getting the push right at the source.
For what happens to these parameters once they arrive in GA4, see GA4 Event Parameters and Event, Session & User Scopes. For how to mark your purchase and lead events as conversions, see GA4 Conversions vs Key Events.