Data layer: how your website passes data to tags

What is a data layer?

According to Google, the data layer is used to pass information to tags. On the website, it is a list named dataLayer. The website writes data into it, and Tag Manager reads it.

This separates the website from measurement. If the design changes, the data stays the same. Without a data layer, a tag would have to fetch such values from the DOM, the page structure. That breaks more easily when a template changes.

Example: dataLayer.push

You add new entries with dataLayer.push. This example reports a submitted form:

dataLayer.push({
  'event': 'generate_lead',
  'form_name': 'contact'
});

The event key has a fixed meaning, because triggers respond to it. generate_lead is an event name from the GA4 reference. form_name is a name of your own choosing.

Details that need to be available when the page loads go above the Tag Manager snippet:

<script>
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'pageType': 'product_page',
  'visitorType': 'customer'
});
</script>

The line with window.dataLayer creates the list if it does not exist yet and does not overwrite existing entries.

Example: a purchase in an online shop

For e-commerce, Google specifies a fixed schema. On the order confirmation page, this example reports a purchase of two items to GA4:

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'B-10042',
    value: 50.00,
    tax: 9.50,
    shipping: 4.90,
    currency: 'EUR',
    items: [{
      item_id: 'SKU-123',
      item_name: 'Sample product',
      price: 25.00,
      quantity: 2
    }]
  }
});

The first line clears the previous e-commerce object, so that no old values get into the new event. transaction_id and items are required. GA4 needs value for revenue reports, and currency whenever value is set. value is the sum of price times quantity, excluding shipping and tax, which have their own fields. The transaction ID prevents purchases from being counted twice.

Data layer in Google Tag Manager

Tag Manager works with the entries in three steps:

1. Trigger: a Custom Event trigger with the name generate_lead responds to the entry.
2. Variable: a Data Layer Variable with the name form_name reads the value.
3. Tag: a tag for GA4 or conversion tracking fires and passes the value on.

Tags, triggers and variables are explained in our article on Google Tag Manager. The server container works differently. It does not read the list from the browser. It receives requests that clients turn into event data. You therefore need to send values from the data layer as parameters in the web container.

Data layer or reading values from the page?

For values that bids or revenue reports rely on, there is a strong case for the data layer.

Data layer specification for developers

Before anyone writes code, decide which event fires when and which values it contains. A small table is enough:

Record the names and sample values. Developers can then check each event against this table. Use the recommended GA4 names where they exist for the action.

Testing the data layer

1. Open preview mode: start Tag Manager’s preview and trigger the action, for example a test purchase.
2. Check the entries: according to Google, Tag Assistant shows the status of the data layer at any point in a chain of events. Check the event name, spelling and values.
3. Use the browser console: typing dataLayer in the developer tools lists all entries on the page.
4. Check delivery: confirm in the destination service that the value arrives correctly, for example in GA4’s real-time reports.

Rules for a working data layer

• Spelling: dataLayer must be written exactly like this. According to Google, datalayer does not work.
• Never overwrite it: according to Google, a new assignment deletes existing entries.

  // Deletes existing entries. Do not use:
  window.dataLayer = [];
  
  // Correct:
  window.dataLayer = window.dataLayer || [];

• Current page only: according to Google, values apply as long as the person stays on the page. Anything you need on several pages must be written in again on each page. Single-page applications have no new page load, so old values remain until you replace them.
• Quotation marks: Google recommends putting variable names in quotation marks. In JavaScript, they are only required if the name contains special characters such as a hyphen. 'event' and event create the same entry, as the examples above show.
• Consistent names: the same item keeps the same name on every page. visitorType and visitor_type would be two different variables.
• Order: details for the page view come before the Tag Manager snippet.
• Keep data to a minimum: the data layer can be read in the browser. Only write what measurement needs, and check any personal data with your data protection officer in advance.