Skip to content
Growth Notes

The data layer as a contract

Most teams treat the dataLayer as a convenience surface - a place the site dumps events for the tag manager to grab. That framing is where the rot starts. The healthier framing: the dataLayer is the contract between the engineering team that owns the site and the marketing team that owns the tags. Versioned, tested, owned, broken if mishandled.

What it is

Section titled “What it is”

A global object on the page (window.dataLayer, by convention, an array) that the site pushes structured events onto. Tag managers, analytics SDKs, and experiment platforms read from it. When done well, every downstream tool - GA4, Meta Pixel, Klaviyo, your A/B testing platform - reads from the same source of truth and reports consistent numbers.

window.dataLayer = window.dataLayer || []


window.dataLayer.push({
  event: 'product_viewed',
  schema_version: 3,
  product: {
    id: 'SKU-123',
    price_cents: 4999,
    currency: 'GBP',
    category: 'knitwear',
  },
})

What goes in is what tags get. If product.id is missing, the Meta tag has no product ID. If price_cents becomes a string, the Google Ads conversion value is now NaN. Most of the “tracking is broken in Looker again” tickets trace back to this single layer.

Why “contract” is the right word

Section titled “Why “contract” is the right word”

The producer (engineering) and the consumer (marketing, analytics) don’t see each other’s work. Engineering renames a field from price to total. Marketing finds out three weeks later when the warehouse revenue report goes flat. Nobody got an alert. The change wasn’t tested. Nothing failed.

A contract makes the exchange explicit:

  • The producer commits to emitting a defined shape.
  • The consumer commits to reading only that shape.
  • Changes happen by spec, with a version bump, with a deprecation window.

Same logic as any API. The dataLayer is an API. It just doesn’t look like one because it’s a global mutable array.

A typed wrapper, not direct pushes

Section titled “A typed wrapper, not direct pushes”

The simplest improvement most stacks can make: stop letting arbitrary code call dataLayer.push({...}). Wrap it.

type ProductViewedV3 = {
  event: 'product_viewed'
  schema_version: 3
  product: {
    id: string
    price_cents: number
    currency: 'GBP' | 'USD' | 'EUR'
    category: string
  }
}


function trackProductViewed(payload: ProductViewedV3) {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push(payload)
}

Now the only way to push a product_viewed is through the typed function. Half the failure modes vanish at compile time - misspelt event names, missing fields, wrong types. See the event schema design note for what goes into the types themselves.

Operational practices that keep the contract alive

Section titled “Operational practices that keep the contract alive”
  • A spec in the repo. A markdown file documenting events, properties, types, and version history - or, better, the TypeScript types themselves with comments. Both engineering and marketing need read access. If the spec lives in someone’s head or in a Notion page nobody’s updated since 2024, it’s not a spec.
  • Validation in non-prod. A GTM tag (or equivalent) that runs on every push, validates against the schema, and surfaces failures to the console. Catches drift on staging before it ships.
  • Clear ecommerce between pushes. dataLayer.push({ ecommerce: null }) before each ecommerce event. GTM’s data layer variable type reads the most recent value for a key, so stale items from view_item_list will leak into the next event without this. It’s the single most common ecommerce tracking bug.
  • Treat tag changes like code. Tag manager changes don’t go through code review by default. They should. A misconfigured tag deletes the analytics value of a quarter as effectively as a bad commit does.

Where it falls down

Section titled “Where it falls down”
  • Tag managers overwriting the dataLayer. Some installations re-initialise the array on load, wiping pushes that happened before the manager loaded. The defensive pattern is window.dataLayer = window.dataLayer || [] everywhere it’s touched, never window.dataLayer = [].
  • Race conditions with SPA route changes. The dataLayer push happens after the route change but the tag manager’s trigger fired off the route change itself. Tag reads stale data. Order events explicitly, don’t trust coincident firing.
  • PII in the dataLayer. It’s a global on the page, anyone with devtools can read it. Email addresses, phone numbers, anything regulated belongs hashed or, better, sent only via server-side tagging where the browser never sees the raw value.
  • Marketing teams adding to it directly. A nice GTM custom HTML tag pushes a “helpful” event nobody knew about. Now the contract has third authors. Lock down write access or accept that the contract is decorative.
  • Trusting a vendor data layer. Shopify doesn’t provide a native dataLayer; third-party apps (Elevar, DataLayer Pro, Analyzify) generate one with their own schemas and quirks. If you’re using one, audit what it pushes and when - don’t assume it matches the GA4 ecommerce schema without verifying.

The endgame

Section titled “The endgame”

On a healthy stack, the dataLayer is boring. The schema is in version control. Pushes go through a typed wrapper. Tags consume documented fields. Changes ship with version bumps and migration notes. New tracking requests start with a spec PR, not a “can you just add a thing for me” Slack message.

Most teams won’t get there. Most will get to “the dataLayer mostly works and we know which fields not to touch”, which is still better than “nobody knows what’s in window.dataLayer right now”. Pick a direction and improve.