Quick Guide: dataLayer.push with examples

Updated: April 13th, 2020.

This quick guide was born after getting multiple questions from Google Tag Manager beginners/intermediate users: when should I use dataLayer.push() and when Data Layer declaration (dataLayer = [{}])? 

The reason why this question is raised at all is that Google Tag Manager’s official documentation is a bit misleading in some parts. Continue reading and I’ll show you where.

dataLayer.push?

So what is dataLayer.push in the first place? It’s a code which enables one to add/update data which is stored in the Data Layer, for example:

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
 'event': 'new_subscriber',
 'formLocation': 'footer'
 });
</script>

But what does it mean? Well, let’s have a quick refresher of what the Data Layer is. P.S. If (after reading this blog post) the topic still looks confusing, consider enrolling in my Google Tag Manager course for Beginners where I explain what dataLayer.push in much greater detail.

What is Data Layer?

Data Layer is one of the main Google Tag Manager concepts which ensures maximum flexibility, portability, and ease of implementation. Without it, GTM would just not work. It is what keeps your tag management running properly. It is the key to unlocking Google Tag Manager’s potential.

I’ve already covered Data Layer in my other guide, Complete Data Layer Guide, but to save you some time, here’s the TL;DR version.

Simply put, a Data Layer is like a bucket that stores certain information. It’s a central place (virtual layer) of a website where you, your developers, or 3rd-party-tools tools can temporarily store data (about user, page content, etc.). From there, Google Tag Manager reads that information, uses it in tags/triggers/variables, or sends further to other tools, Google Analytics, Google Adwords, Facebook, you name it.

Once you place the Google Tag Manager container’s JavaScript Snippet in your website’s source code, the Data Layer is automatically created. You don’t have to add anything more. However, if you want some more custom data, like userID, Product price, Order total, etc. (and use that in Google Tag Manager), additional configurations will be needed. And that’s where dataLayer.push plays the role.

Store/update data in the data layer

There are two ways of how the data can be pushed to the Data Layer. Actually, there is only one that you should be using, but for sake of knowledge I’ll mention both:

1. By adding Data Layer snippet above the Google Tag Manager container snippet ( dataLayer = [] ). This method is also mentioned in the official GTM documentation.
2. Or by pushing data with dataLayer.push method.

What’s the difference, you ask?

Data Layer declaration (not recommended)

This method of inserting data into the Data Layer could be used if you want to add any data right when the page loads, for example, user ID. As a result, you could utilize the user ID variable in the All Pages trigger.

In this case, your developers should add a Data Layer snippet above (this is important!) GTM tracking container with the actual user ID. Once this information is added to Data Layer, you can start working with it in Google Tag Manager. Here’s a code example:

<script>
 dataLayer = [{
 'userID': '123456'  
 }];
</script>
<!-- Google Tag Manager --> 
// this is where your Google Tag Manager container snippet should be placed
<!-- End Google Tag Manager -->

Although this method is mentioned in the official Google Tag Manager documentation, you should not use it. Why?

If a developer places this snippet below the Google Tag Manager container, it will break things. One of the consequences will be broken All Pages trigger. Also, Google Tag Manager will not be able to track various website interactions, such as clicks, form submissions, etc.

Even Google’s documentation is inconsistent here. For example, in the Standard Ecommerce (for GTM) documentation they are offering another way how to place the data, and it’s dataLayer.push (which is explained in the next paragraph).

Simo Ahava also recommends using only dataLayer.push, and never dataLayer = []. 

Why? Because by using the syntax dataLayer = [], you are resetting the dataLayer variable to a new Array (read: you clear the bucket), thus overwriting anything that was in it before (such as Google Tag Manager’s customizations needed for tracking to work). Since you overwrite the dataLayer, it no longer works properly with Google Tag Manager, and a typical symptom is that GTM’s triggers don’t work anymore, either.

dataLayer.push (recommended)

The second method of how to put data in the Data Layer is dataLayer.push, which is absolutely recommended and should be the only choice of yours. Regardless of where you place it (below or above the Google Tag Manager container), dataLayer.push will work properly. Here are a few examples:

1. You have a newsletter signup form (which cannot be easily tracked with a default GTM’s form listener) so you decided to ask a website developer to fire a Data Layer event once a new subscriber has successfully entered his/her email on your website:

   <script>
   window.dataLayer = window.dataLayer || [];
     window.dataLayer.push({'event': 'new_subscriber'});
   </script>

   If you wish you can ask your developer for additional information (e.g. form location (because you might have more than one form on the same page)).

   <script>
   window.dataLayer = window.dataLayer || [];
   window.dataLayer.push({
    'formLocation': 'footer',
    'event': 'new_subscriber'
   });
   </script>

2. When a visitor adds a product to his/her cart, a Data Layer event (containing the product’s information) could be fired.

One more thing. If you compare code snippet in this blog post to the ones that are explained in the official Google Tag Manager documentation for developers, you’ll notice that my code examples also have the “window” prefix (instead of dataLayer.push,  I use window.dataLayer.push). After using Google Tag Manager for a while and seeing other professionals talking, I’ve noticed that they recommend one more thing (as a rule of thumb): adding a prefix window to the dataLayer.push. As a result, the final dataLayer.push code snippet could look like this:

<script>
window.dataLayer.push({
 'formLocation': 'footer',
 'event': 'new_subscriber'
 });
</script>

By the way, the dataLayer name is case-sensitive. This means that only letter L must be uppercase:

• DataLayer.push will not work (because D is uppercase)
• datalayer.push will also not work (all letters are lowercase although L should have been uppercase).

More dataLayer.push examples

Previously mentioned dataLayer.push examples are pretty basic but if you need, you can also push data as objects or arrays. A good example would be a Standard E-commerce transaction code:

<script>
window.dataLayer = window.dataLayer || [];
dataLayer.push({
 'transactionProducts': [{
 'sku': 'DD44',
 'name': 'T-Shirt',
 'category': 'Apparel',
 'price': 11.99,
 'quantity': 1
 },{
 'sku': 'AA1243544',
 'name': 'Socks',
 'category': 'Apparel',
 'price': 9.99,
 'quantity': 2
 }]
});
</script>

What happened here is that with one dataLayer.push we also pushed an array (transactionsProducts) containing two objects. Each object contains the same set of keys (sku, name, category, price, quantity) but their values are different. And that’s logical because two different products will usually have different characteristics.

Enhanced E-commerce Data Layer pushes also use a bit more difficult data structures:

<script>
window.dataLayer.push({
 'ecommerce': {
  'promoView': {
   'promotions': [
    {
     'id': 'JUNE_PROMO13', // ID or Name is required.
     'name': 'June Sale',
     'creative': 'banner1',
     'position': 'slot1'
    },
    {
     'id': 'FREE_SHIP13',
     'name': 'Free Shipping Promo',
     'creative': 'skyscraper1',
     'position': 'slot2'
   }]
  }
 }
});
</script>

With this dataLayer.push, we added an ecommerce object which contains promoView object which contains promotions array which contains two objects of two promotions displayed on a page. Each promotion has 4 keys, id, name, creative, position.

OK, now what?

After the data/events are pushed into the Data Layer, it’s time to start working with them:

• Do you want to use a Data Layer event as a trigger? Do it with the Custom Event Trigger.
• Do you wish to access some data (e.g userID) and insert it in the Universal Analytics tag? Create a Data Layer Variable for each data point you want to access from the Data Layer.

dataLayer.push: Final Words

DataLayer.push is a way for you/developers/3rd-party-plugins to pass some useful data to the Data Layer. And from there you can “play with it” in Google Tag Manager and use it in your tag management.

DataLayer.push should be the only way how you should be adding data. Even though Google Tag Manager official documentation still mentions/recommends using a regular Data Layer declaration (dataLayer = [{}]), you should not fall for that. Remember, always push to the dataLayer.