GTM dataLayer.push Examples (Standard, Ecommerce, Advanced)

This post shows four examples of using the dataLayer.push method to pass in extra metadata to Google Tag Manager (GTM) via Variables.

#1 Standard GTM Data Layer Push Syntax
#2 GTM Data Layer Push with Array
#3 GTM Data Layer Push with Nested Key-Value Pairs
#4 GTM Data Layer Push with Nested Arrays

#1 STANDARD GTM DATA LAYER PUSH SYNTAX

The standard syntax for a GTM data layer push includes an event key and sets of key-value pairs, like this:

window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'event' : 'trackEvent',
  'pageType' : 'Blog',
  'userID' : '12345',
  'loginStatus' : 'logged in' 
});
Note: while event keys aren't strictly necessary for a data layer push, every tag in GTM needs an event key to trigger it. If you push dimensions without an event key, you can't access the dimension values at that current state -- they will be inaccessible to GTM until the next event key gets set. So as a best practice, always include an event key on every data layer push.

#2 GTM DATA LAYER PUSH WITH ARRAY

In some cases, the value of your data layer key will be an array, rather than a single value. Here's an example where you're marking a page with multiple categories:

window.dataLayer = window.dataLayer || []
window.dataLayer.push({
  'event':'trackEvent',
  'pageType' : 'Blog',
  'userID' : '12345', 
  'loginStatus' : 'logged in', 
  'pageCategories':['Marketing','Measurement','Implementation'];
  });

#3 GTM DATA LAYER PUSH WITH NESTED KEY-VALUE PAIRS

Getting a little more advanced, you will sometimes also want to pass in nested key-value pairs into your data layer. Probably the most common example of this is when you implement the various Google Analytics Enhanced Ecommerce data layer pushes for GTM, as described here. In this example snippet for tracking cart adds, there's an e-commerce object that contains a products key. Within this product key, you can see key-value pairs for product name, product ID, product price, product brand, product category, product variant, and product quantity:

window.dataLayer = window.dataLayer || []; 
dataLayer.push({
  'event': 'addToCart',
  'ecommerce': {
    'currencyCode': 'EUR',
    'add': {                                
      'products': [{                        
        'name': 'Triblend Android T-Shirt',
        'id': '12345',
        'price': '15.25',
        'brand': 'Google',
        'category': 'Apparel',
        'variant': 'Gray',
        'quantity': 1
       }]
    }
  }
});
To put it simply, objects are lists of key -> value pairs, and can be identified by their curly bracket. Arrays are lists of values and are marked with a square bracket. The above syntax leverages both data types.

4 GTM DATA LAYER PUSH WITH NESTED ARRAYS

I'll also include one more case, for when you want to go even deeper.  In this example, imagine you are tracking content on your site, and your content has multiple top-level categories as well as sub-categories. This would be the syntax for pushing a 'pageCategories' key that contains multiple category values, which are then further broken down by sub-category.

window.dataLayer = window.dataLayer || []
window.dataLayer.push({
  'event':'trackEvent',
  'pageType' : 'Blog',
  'userID' : '12345', 
  'loginStatus' : 'logged in', 
  'pageCategories':[{
    "Marketing":["Facebook Ads","Google Ads","Mailchimp"],
    "Measurement":["Google Analytics"],
    "Implementation":["FB Pixel","GTM"]
}]
});

You could theoretically continue nesting sub-arrays/objects, but it's hard to think of a use case where that would make sense. It also requires a more complex GTM implementation to extract the information from sub-arrays, so if you have some need to track additional levels of hierarchy, I'd suggest moving them up a level into their own keys, e.g. key 1 = pageCategories, key 2 = marketingSubCategories, key 3 = marketingTags, and so on.

QUICK NOTE

All of the above examples show the final, resolved output of the code you're using to populate the data layer push. The actual code will usually contain variables, like this:

window.dataLayer = window.dataLayer || []; 
dataLayer.push({
  'event': 'addToCart',
  'ecommerce': {
    'currencyCode': 'EUR',
    'add': {                                
      'products': [{                        
        'name': productObj.name,
        'id': productObj.id,
        'price': productObj.price,
        'brand': productObj.brand,
        'category': productObj.cat,
        'variant': productObj.variant,
        'quantity': productObj.quantity
       }]
    }
  }
});

4 thoughts on “GTM dataLayer.push Examples (Standard, Ecommerce, Advanced)”

  1. I’m having a little trouble getting this to work and I’m not sure how I can go about debugging it. I think I’ve followed the directions in the article properly. It’s a little fuzzy to me how exactly GTM hears the event being fired. I put mine within a click event handler that simply pushed the values into the dataLayer object as you’ve outlined in the first step. Does GTM watch for changes to that object, or is there something else I need to do to make GTM pass the values?

    • Hey Mike, that should work fine. GTM will pick up any data layer pushes automatically, so you don't need to do anything else. However, you can't do anything with these values until you push them into triggers and variables. So if you're pushing an event called trackEvent into the data layer, in GTM you now need to go to Triggers > New > Custom Event and enter Event name = trackEvent. Similarly, if you've pushed a key named pageType into the data layer, in GTM you should go to Variables > New > Data Layer Variable and enter Data Layer Variable Name = pageType. Then you can use trackEvent as a trigger, and push pageType into any of your tags.

    • Not sure I totally understand what you're asking, but yes you could put these data layer pushes into a custom HTML tag if you wanted. Let me know if that answers your question.

Comments are closed.