The data layer: how a website hands information to its tags

Tracking tags need facts about the page: what the product is, how much it costs, who is logged in, what the visitor just did. There are two ways to get them. One is to scrape the page, reading text out of elements with selectors. The other is to have the page say what is happening. The second is a data layer.

What it is

A data layer is a JavaScript array, usually called dataLayer, that the page fills with plain objects. A tag manager watches the array and reads from it.

window.dataLayer = window.dataLayer || [];

// information about the page, pushed as it loads
window.dataLayer.push({
  page_type: 'product',
  user_status: 'logged_in',
});

// something the visitor did
window.dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'EUR',
    value: 29.9,
    items: [{ item_id: 'SKU-123', item_name: 'Desk lamp', price: 29.9, quantity: 1 }],
  },
});

The first line creates the array if the tag manager has not yet loaded, so the page can start pushing straight away. A push with an event key is special: it tells the tag manager that something happened, and any trigger set to listen for add_to_cart fires.

Why not scrape the page?

Scraping reads .price-box > span.amount and hopes. The day a designer renames a class, the tag silently reports nothing. A data layer moves the responsibility to where the knowledge is: the developer who builds the page knows the price and the product id, and publishes them under agreed names. The tags no longer depend on markup.

It also separates jobs. Developers maintain the data layer. Marketers and analysts change tags in the tag manager without a release.

Good habits

• Write a specification. A document (or a shared sheet) listing each event, its name and its parameters, with an example. It is the contract between developers, analysts and anyone who tests.
• Name things consistently. Pick a convention (snake_case, as in add_to_cart) and keep it. If you send events to Google Analytics 4, use its recommended event and parameter names where one exists, so the standard reports work.
• Push values, not decisions. Publish "price 29.9" and let the tag manager decide what to do with it. Putting tag logic in site code means a release for every change.
• Push at the right moment. Values must exist before the tag that needs them fires. Page-level information belongs before the tag manager's container loads, or must be followed by an event that triggers the tags.
• Clear the previous value. Data layer values persist and are merged, so an old ecommerce object can leak into the next event. Google's guidance for e-commerce events is to push { ecommerce: null } first, then the new object.

window.dataLayer.push({ ecommerce: null });   // clear the previous ecommerce object
window.dataLayer.push({ event: 'purchase', ecommerce: { transaction_id: 'T-1001', value: 59.8, currency: 'EUR', items: [] } });

• Keep personal data out. Do not push e-mail addresses, names or anything that identifies a person unless you have a clear legal basis and the tags that receive it are meant to. A hashed identifier or an internal id is usually enough.

The mistakes behind most broken tracking

Testing

Use your tag manager's preview mode: it lists every push in order, shows the data layer's state at that moment and which tags fired. Test each event from the specification, on a staging copy first, and keep the results with the specification. When something breaks in a year, you will know what "working" looked like.