June 12, 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 = [{}])?
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:
|
1 2 3 4 5 6 7 |
<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 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 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. 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 Data Layer. Actually, there is only one that you should be using, but for sake of knowledge I’ll mention both:
- By adding Data Layer snippet above the GTM container snippet ( dataLayer = [] ). This method is also mentioned in the official GTM documentation.
- 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:
|
1 2 3 4 5 6 7 8 |
<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 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:
- 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:
1234<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)).
1234567<script>window.dataLayer = window.dataLayer || [];window.dataLayer.push({'formLocation': 'footer','event': 'new_subscriber'});</script> - 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:
|
1 2 3 4 5 6 |
<script> window.dataLayer.push({ 'formLocation': 'footer', 'event': 'new_subscriber' }); </script> |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<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.
dataLayer.push FTW!
57 COMMENTS
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
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.
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.
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 =)
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!
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.
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.
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!
Do you see that event in real-time reports?
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!
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!
It was that type of thing, so embarrassing, I forgot to Publish the changes!
It's ok now!
Hahaha been there, done that! Great you managed it!
Hey Julius,
Is there way to reset data layer after transaction complete ?
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.
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
Can you provide GTM implementation in share point 2013 website using visual studio.
Hey, I doubt that. The current schedule is a bit overcrowded and I never needed to track Sharepoint before.
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?
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
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!
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 downloadI 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?
Hi Julius can you help me with setup of datalayer for my opencart e-commerce store
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/
I'm not comfortable adding the code to website that's why requested for help if you can do it thanks in advance
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).
What about the gtag() calls?
What is the difference between dataLayer.push and gtag() calls.
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.
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??.?
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/
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?
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)
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'
});
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.
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!
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.
Thanks Julius
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(';')});
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/
Sorry, your suggestion worked PERFECTLY!!! I had syntax error. Thank you very much for your help!!!
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
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
You should better send separate events, not everything at once. This means separating dataLayer.push as well. Category, action and label accept only strings, not arrays or objects.
Why GTM fires some tags in debug mode only??
Maybe you have configured them to fire only in the debug mode. If you want help, you have to provide more information.
How I configure it to run also in normal mode
Have you published the container? If yes, then you have to do a better job explaining what have you configured so far. Otherwise, I cannot help you.
Yes I have published data has been passed to analytics in preview mode. But normal mode nothing happen.
In my validation success function I defined like this
window.dataLayer.push({
'event':'questionCreationComplete',
'questionCreationTimeDuration':questionCreationTimeDuration,
'questionType':questionType
});
So I create a custom event trigger and add event name 'questionCreationComplete'
Yes I have published data has been passed to analytics in preview mode. But normal mode nothing happen.
In my validation success function I defined like this
window.dataLayer.push({
'event':'questionCreationComplete',
'questionCreationTimeDuration':questionCreationTimeDuration,
'questionType':questionType
});
So I create a custom event trigger and add event name 'questionCreationComplete'
Does it happen only with one tag or many tags? Share the link to preview and debug mode and tell me how to reproduce that dataLayer.push.
I have use only for one tag. I couldn't understand this sentence 'Share the link to preview and debug mode and tell me how to reproduce that dataLayer.push'
Good night! Congratulations on the content! Your website is great! One question: for Google Ads, is it right to use conversionValue or Price to calculate ROI?
Hi!!!
Can we add Track type as Timing for GTM tag using trigger as custom event??
Sure
Hi..
Anyone has any idea about custom metric should be number error display in tag manger assistant
Sounds pretty obvious - you're a string as a custom metric. Also, please, do not post questions that are not related to the topic under the blog posts.