Quick Guide: dataLayer.push with examples

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 = [{}])?

dataLayer.push?

It’s a code which enables one to add/update data which is stored in the Data Layer, for example:

But what does it mean? Well, let’s have a quick refresher of what the Data Layer is.

What is Data Layer?

I’ll repeat myself once again: Data Layer is one of the main Google Tag Manager concepts which ensures maximum flexibility, portability, and ease of implementation. Without it, there would be (almost) no variables or triggers in GTM. 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 TL;DR version.

Technically speaking, a Data Layer is a JavaScript array that stores certain information. It’s a central place (virtual layer) of a website where you, your developers, or 3rd-party-tools tools can 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 GTM container’s JavaScript Snippet in your website’s source code, the Data Layer is automatically created. You don’t have to add anything more.

Google Tag Manager Data Layer can contain additional information, like userID, Product price, Order total, etc., and that’s where the dataLayer.push comes in.

Store/update data in the data layer

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

1. By adding Data Layer snippet above the GTM container snippet ( dataLayer = [] )
2. Or by pushing data with dataLayer.push method.

What’s the difference, you ask?

Data Layer declaration

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:

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.

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, thus overwriting anything that was in it before (such as Google Tag Manager’s own listener). Since you overwrite the dataLayer, it no longer works properly with GTM, and a typical symptom is that GTM’s triggers don’t work anymore, either.

dataLayer.push

The second method 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 GTM 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>

   1 2 3 4

   <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>

   1 2 3 4 5 6 7

   <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 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 GTM 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:

Read more: Phil Pearce‘s discussion and a paragraph in Simo Ahava‘s guide.

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:

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:

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.

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.

GTM experts, for example, Simo Ahava insists you on using the .push because it is a more elegant and robust solution.