January 11, 2019

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.

Google Tag Manager Course for Beginners - Learn More

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

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

dataLayer.push in standard ecommerce
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 (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 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:

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

Julius Fedorovicius
In Google Tag Manager Tips
43 COMMENTS
Marine

Hi Julius,

There's something that confuses me. I understand that a DL push will work wherever it's placed on the page, but for it to work, do you need to declare

window.dataLayer = window.dataLayer || []

above the GTM container? Or do you need this part at the start of every data layer push?

Thanks,
Marine

    Julius Fed

    If you're placing the window.dataLayer.push code above the GTM container, then you should add window.dataLayer = window.dataLayer || [].

    In other cases it's optional. Actually, feel free to remove window.dataLayer = window.dataLayer || [] from other places if you wish. It's important to define the dataLayer before GTM container snippet does it, if you have some additional data that needs to be pushed before the Page view event.

Michael

Julius, one question please. Is this enough?

dataLayer.push ( { "event": "newsletter_unsubscribe"} )

Because I don't see this event in Google Analytics > Behaviour > Events after implementation. The call is made, I can confirm it but the event is not visible.

    Bruno

    Hi,

    If I may come in and try to help, I think when you push this event "newsletter_unsubscribe" on GTM you are creating a event on GTM, not GA. That means that you can recognize it on GTM now and use it, for example, as a trigger. In your case you could create a trigger based on the Custom Event "newsletter_unsubscribe" (without quotes). Then you can create a Google Analytics Event Tag on your GTM and use the trigger above in it.

    I hope that makes sense =)

      Michael

      That's what I assumed as well. I just created a Trigger and Tag in GTM, associated them together and hopefully I will now start seeing the event in GA.

      Thanks Bruno!

      Michael

      Hi Bruno.

      No luck, I'm afraid.

      I created a trigger in GTM named "newsletter_unsubscribe", a custom event.

      I created a tag in GTM which is referencing the trigger. The tag type is "Universal Analytics" and fires trigger "newsletter_unsubscribe".

      I thought this was enough?

      Thanks.

        Bruno

        Hi Michael,

        If I understand correctly you should fire a Universal Analytics Tag of Track Type Event using the trigger you created.

        Make sure you are chosing a distinct combination of Category, Action and Label to identify it later on GA.

        Pro tip: for this to work you should had fired GA Standard Tag first. To make sure the Event tag doesnt fire earlier than Standard Tag you can use the Tag Sequecing option in Advanced Settings.

Michael

Hi Bruno.

I believe the configuration in GTM is correct because I debugged the website and I see the below when datalayer.push is called:

Tags Fired On This Event
- GA_event_EE_newsletter_unsubscribe
- Universal Analytics

When I click:

Type: Universal Analytics
Category: 'newsletter_unsubscribe'
Non-Interaction Hit: false
Enable overriding settings in this tag: true
Track Type: 'TRACK_EVENT'

Am I right or I forgot some configuration?

Thanks!

    Julius Fed

    Do you see that event in real-time reports?

      Michael

      Hi Julius.

      That's the issue, I see the others, not this one.

      I also removed the tag and trigger and created two new ones based on the data attribute of the button rather than a direct call to datalayer.push.

      Trigger Type: Click - All Elements
      This trigger fires on matches CSS selector [data-test*="btn-unsubscribe"]

      The tag is linked with the trigger.

      When I debug GTM(preview mode) and click the button I see gtm.click under Summary with these details:

      Tags Fired on this event: html_event_unsubscribe (Universal Analytics)

      I click:

      Type: Universal Analytics
      Action: 'UNSUBSCRIBE' (it's the {{Click Text}} variable)
      Category: 'gtm.click'
      Label: 'Click'
      Non-Interaction Hit: false
      Enable overriding settings in this tag: true
      Track Type: Track Type

      Thanks!

Bruno

Michael,

It seems that handled alright the GTM part. The only possibility I can think of this not working after you fired the tag is that for some reason you global GA tag didnt fire before, thats why I suggested you using tag sequencing just to make sure this isnt the case.

Also, if you are firing the tag right, maybe the issue is viewing it on GA. Make sure you are not using any traffic filter on your view or property. Double check the tracking code, see if you are looking on the right report... that type of thing.

Good luck!

    Michael

    It was that type of thing, so embarrassing, I forgot to Publish the changes!

    It's ok now!

      Bruno

      Hahaha been there, done that! Great you managed it!

Chamin

Hey Julius,
Is there way to reset data layer after transaction complete ?

Bruno

Hi,

Sorry for intruding, but maybe you can do this: every time you declare the dataLayer, such as:
dataLayer = [{
'property' : 'value'
}];

You are overwriting the previous value of the dataLayer, including all objects and values that you had there. This, in some ways, is a reset on the dataLayer (I don't know if you meant that by reset).

Obs: I don't know why you would want to do this, but it is not recommended. I'd recommend you using just the dataLayer.push method so you will always append values or overwrite just the properties you want.

    Julius Fed

    Do not declare Data Layer (dataLayer = [{}] ) after GTM is loaded as it might (and usually will) break things. For example, this blog post is a consequence of declaring the dataLayer after it's already initiated.

    Actually, it's pretty easy to delete a certain value from the Data Layer. Just push an "undefined" value, e.g.
    dataLayer.push({
    'someParameter': undefined
    })

    Cheers

Payal Varshney

Can you provide GTM implementation in share point 2013 website using visual studio.

    Julius Fed

    Hey, I doubt that. The current schedule is a bit overcrowded and I never needed to track Sharepoint before.

Steve

If I push an event to the dataLayer before GTM is loaded in what order do things happen once GTM loads? Say I have GA set for 'all pages' and another GA set for this specific event... would all pages always 'run' before the event trigger or because the event was pushed before GTM loads it would happen immediately?

Tag Sequencing makes it seem like that tag would be fired 'again' or in addition to the tag you add it. If I have GA set to fire once per event on all pages then on another tag choose GA as the setup tag (fire before)... it seems like GA would be fired twice or just once if it already had - right? Isn't ordering of the tags what Tag Firing Priority is for?

    Julius Fed (Fedorovicius)

    Hey, if you push event + data before the GTM snippet, then that event will occur before the Pageview event.

    As for your second question, a tag might fire once, it might fire twice. It depends.

    Imagine there are 2 tags:
    - Event tag
    - Some other tag.

    If:
    - "Some other tag" fires on All pages
    - AND you also set Event tag as its setup tag
    - AND also Event tag is set to fire on All pages, then Event tag will fire only once because everything is happening within the boundaries of "Pageview" event.

    If you set event tag to fire on DOM Ready, then Event tag will fire twice per page:
    - On All pages
    - And on DOM Ready

Will

Thanks for the great article.

I have two questions:

Lets say i'm trying to track an AJAX form submission. So after the form is submitted the user stays on the same page.
Am i right then that id tell my developer to dynamically plant the datalayer push script ( dataLayer.push({'event': 'new_subscriber'}); ) into the code once the form has been submitted?

Secondly, is it possible to place the datalayer push script within HTML elements.
Example, something like:
Click Me!

    Julius Fed (Fedorovicius)

    Hey,

    1. You can follow this guide to track AJAX forms - https://www.analyticsmania.com/google-tag-manager-ajax-form-tracking/. You should be able to solve this task without developer's input.
    2. Yes, you can insert a dataLayer.push on a link, like this:
    PDF download

srijith

I have custom javascript variable which return the form title in Ninja forms and i have created Custom HTML script which runs when the form is submitted and it pushes an event. however as i have mentioned earlier the custom javascript variable which collects the form title becomes "undefined" as soon as form submission event is fired in datalayer, however i can see the javascript variable returning the form title just below my event which was gtm.click event..can anyone please advise how can i move the custom javascript variable value to the form submission event datalayer?

Ali

Hi Julius can you help me with setup of datalayer for my opencart e-commerce store

    Julius Fedorovicius

    Hey, I recommend reading the following guides for you to better understand how to implement Ecommerce tracking:
    - Standard Ecommerce tracking https://www.analyticsmania.com/post/ecommerce-tracking-with-google-tag-manager/
    - Enhanced Ecommerce tracking https://www.simoahava.com/analytics/enhanced-ecommerce-guide-for-google-tag-manager/

      Ali

      I'm not comfortable adding the code to website that's why requested for help if you can do it thanks in advance

        Julius Fedorovicius

        Currently, I don't take new projects.

        These codes must be generated server-side by the developer. Just simply pasting JavaScript to the page will not work. A developer must code some PHP functions that generate dataLayer codes in the front-end of the website.

        So in this case, you should either contact a developer or maybe Opencart has some plugin that does that (however, I'm not very experienced with Opencart and cannot recommend any particular plugins).

Daniel

What about the gtag() calls?

What is the difference between dataLayer.push and gtag() calls.

    Julius Fedorovicius

    gtag calls are designed only for Google Analytics. dataLayer.push pushes data to the Data Layer that can be later caught by the GTM and then GTM can transfer that info as triggers or variables in tags.

Anand

Hi Julius I new to data layer and i love to read and explore more content on your website.I really looking to track the user id plus user location from data layer for that how to write the code as per the example which you mentioned about userid : 12345 as by default you set the id but In real how should I track user id in the array and their location.

Help me in this??.?

    Julius Fedorovicius

    Hey, sorry, but I didn't quite get the question. Could you rephrase it? As for the User ID, I have just published another guide that you might find helpful https://www.analyticsmania.com/post/google-analytics-user-id-with-google-tag-manager/

Pawel

What if you want to preload some data, in the meaning that load some data before someone has the 1st contact with our website? (1st pv)

Is it better to already load the page with the preloaded dataLayer or to load the page normally and perform a push?

    Julius Fedorovicius

    It depends on how accurate do you want your data to be. The sooner you'll preload dataLayer with some data points (even on the first pv), the better.

    If you push some data later, it won't be available on Page View event thus some tags will not access it and you'll miss it in, say, Google Analytics (of course, this one depends on a scope)

Elena

So you're saying I have to declare this window.dataLayer = window.dataLayer || []; even when I push an event right?

window.dataLayer.push({
'event': 'Button clicked'
});

    Julius Fedorovicius

    It's enough to have this code added once but "just in case" I fire it before every dataLayer.push. this code isn't heavy and does not have negative impact.

Badhan

Hi Julius,

Thanks for sharing all the great posts. These are really helpful for people like me to get an understanding. We are working on a task to track user login and account creation on our website; however, we handle login and account creation process through Centralized account / sub-domain. i.e. if I try to login from a landing page --> it takes to the sub-domain --> after authentication, user returns back to the landing page.
Looking for your suggestion, what will be the best approach to track login using data layer in multi domain cases.

Thanks!

    Julius Fedorovicius

    Tracking visitors across the main domain and its subdomains is not a "multi-domain tracking". It's still happening on the same domain. Just keep the "cookieDomain: auto" in your GA Settings Variable and you're good to go.

      Badhan

      Thanks Julius

David Martin

Hi,
We use Oracle Infinity as Analytics tool. I have added Oracle Infinity tag to GTM and data is being correctly sent to tool for standard variables.

We have custom variables we need added. I have added a Custom HTML Tag in GTM to trigger on a button click which is clicked after a user makes specific selections. Developer added code to site to push data(user selections) to dataLayer.

When I test, GTM has current dataLayer values but what is sent when tag fires( dcs call ) is always previous data (previous user selections).
Is triggering tag on button click wrong solution?
here is code:
//Oracle Infinity UDO testing

dataLayer.push({'o_filteraction':'AdvancedSearch'});
dataLayer.push({'o_filtertype':checkTypes.join(';')});
dataLayer.push({'o_filterfeature':checkFeatures.join(';')});
dataLayer.push({'o_filtercategory':checkCategory.join(';')});
dataLayer.push({'o_filteraccommodation':checkAccommodation.join(';')});
dataLayer.push({'o_filterlocation':checkLocation.join(';')});
dataLayer.push({'o_filterdates':checkDates.join(';')});
dataLayer.push({'o_filterprice':checkPrice.join(';')});

    Julius Fedorovicius

    Hi, if you want to use the latest data from the data layer in your tags, your dataLayer.push codes need to have 'event' key).

    E.g.
    dataLayer.push({
    'event' : 'some_event_name', //this could be the same for all the pushes that you listed in your comment
    'o_filteraction':'AdvancedSearch'
    });

    Then create a custom event trigger that will be activated on "some_event_name". That way you will get the latest data in your tags.
    Read more about the custom event trigger - https://www.analyticsmania.com/post/google-tag-manager-custom-event-trigger/

      David Martin

      Sorry, your suggestion worked PERFECTLY!!! I had syntax error. Thank you very much for your help!!!

David Martin

Thanks Julius for answering so quickly!! Even with custom event the Tag is still firing before dataLayer push. Not sure what I'm missing in GTM.. I don't see anything in GTM to delay the tag firing until after custom event/dataLayer push?

Regards,
David

Andre

Hey Julio, alright? I have some custom variables that are used for standard GA events ... For example:

window.dataLayer.push ({
'event': 'dataevent',
'mycategory': "Group",
'myaction': "Clik",
'mylabel': "button x"
});

Now in a single push I need to send multiple events at once.
Is that what I should do?

window.dataLayer.push({
'event': 'dataevent',
'mycategory': {[“Grupo”]}, // this is the string unique for all
'myaction': {[”Click one, Click two”]}, // these change
'mylabel': {[“button x, buton y”]} // these change
});

Thank you for your help

Leave a comment

Your email address will not be published. Required fields are marked *