April 13, 2020
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:
- By adding Data Layer snippet above the Google Tag Manager 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:
<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:
- 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> - 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.
55 COMMENTS
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!
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
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/
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!!!
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.
How I configure it to run also in normal mode
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.
Sure
Hi Julius,
I'm currently trying to push data into squarespace Post-submit HTML. Due to the event is gtm.submit, and the formID is unknown (From google tag manager, variable tab can be seen). I have addded the following code to push the formID. So it can be added into Google tag manager to track form.
<script>
console.log('THIS IS FIRING');
dataLayer.push({
'event': 'formSubmission',
'formType': 'contactUs',
'formPosition': 'contactPage',
'formID': 'contact001'
})
</script>
I'm in a lost of why it can't push the data in. What should I do?
Thanks for your help
Do you see the console.log in the console? If yes, then here are some fixes:
- semicolon is missing after the dataLayer.push.
- also, I've added an additional line in the beginning to initiate the dataLayer (because maybe at that moment it is still not created by the GTM).
Here's the code:
<script>
console.log('THIS IS FIRING');
window.dataLayer = window.dataLayer || [];
dataLayer.push({
'event': 'formSubmission',
'formType': 'contactUs',
'formPosition': 'contactPage',
'formID': 'contact001'
});
</script>
If you don't see the console.log in the console, then maybe squarespace does not allow custom js? I don't know its limitations.
Thanks for the reply, I can't see the console.log in the console. maybe I should delete it instead?
Cause when I choose to click on a button as 1 submission it works. but dropdown menu requires a formID and i can't locate it. That is why I uses JS script to add-in.
According to what I know, squarespace allow custom js. That's why I have such a doubt that why it cant be fired.
Thanks for your help :)
If you cannot see the console.log, this means that the entire code is not activated (including the dataLayer.push). I would contact squarespace suport, maybe they will give you some hints (because this looks like something squarespace-specific).
Hi Julius,
I have just retry the code, and it works.
Thanks so much for your help.
Million Thanks,
Leon
Just one more question.
Let say if I have a drop down menu with 3 options.
because I doesn't have a formID, I have uses the code to give the form an ID. At the developer tools, Console. I can see the code is fired.
The question is:
When I find the drop down menu list at DataLayer, the data is empty.
let say is the 8 click:
it show: [7] [""gtm.element""].value
It doesn't have the gtm.element "the number I need to track" . value.
Is this also need to use some code to inject in?
Thanks
For subscription based affiliate tracking (ex. I want to track an affiliate that generated usd5 every month.) The trigger only fires once from the client. Is there a way to fire the trigger from the server (from a callback to the payment gateway) instead?
If you want to send the data from the backend when the user is not logged in, then GTM won't help you. A developer must directly send the data to GA via a thing called Measurement protocol.
Hi Julius and others.
The website I work for has a search field and the client needs the list of search queries, since the dev's do ajax call, we don't have track on the searches.
I tried the below-
<script>window.dataLayer = window.dataLayer || [];window.dataLayer.push({'searchQuery': 'value'});</script>
and created an event, whenever earch button is clicked, value from searchQuery will be sent to GA, but since the variable will be null, I cant track the searches correctly.
Now, how can I delay the tag and wait for the searchQuery variable to get the search value and then send the value to GA?
Thanks in Advance,
Thomas
You can use the following code:
<script>window.dataLayer = window.dataLayer ||[];
window.dataLayer.push({
'searchQuery': 'value',
'event' : 'searchComplete'
});</script>
Then create a custom event trigger that activates on "searchComplete" event and only then fire the tag.
Hi Julius,
Is there a way to use the info in a Data Layer variable set via website1, in a different portal(website2)?
The task: the user perform an action in website1 and as a result we set a value in a variable ("true"). We need to read that value in website2 before executing some code (via a GTM tag).
We can not use cookies for this, as apparently you can not (not allowed) to access cookies set in other websites.
Many thanks
You could try passing the variable via URL. When the visitor goes from website1 to website2, the URL should be decorated with the value of the variable.
Hey Julius
Great article, but I have a question too:
How can I push a parent class into the data layer?
nav class
ul class
li class
a class
In gtm.linkclick events I got the a class, but I need the nav class as well, to distinguish between different navigations.
any idea?
Hey, use this https://www.simoahava.com/analytics/capturing-the-correct-element-in-google-tag-manager/
Thanks for article Julius.
What if I wanted to pass a variable via a URL. For instance, for a specific URL I wanted to display a list of products (associated with article). The data would come from database, Google sheets, etc.
Any suggestions would be greatly appreciated.
For that, you can use URL variable in GTM, also Custom Javascript variable is useful if you know how to code.
Hi Julius,
Need a small help. I have created a custom event. The label has a variable which captures the search (a section search not internal site search) phrases. Used DLV type for creating a variable to capture the value.
Event is also firing perfectly. In preview mode, under tags, the label value is firing as undefined. However, under datalayer tab, I can see the value passing to DLV variable. But this data is not being pushed to analytics. Here is the code placed on website
window.dataLayer = window.dataLayer || [];
window.dataLayer.push
({
'event': 'Ideas Search'
‘dlv_ideas_search_term’: ‘value’
})
Kindly assist.
Regards,
Swapna
This means that your data layer variable is incorrect. Check the grammar error.
Swapna, I had the same problem. We had to change the trigger to Window Loaded rather than Page View because PV fired too early to actually capture the data.
Once we changed to WL, the data started making it into Analytics.
Good luck!
This will work is dataLayer.push occurs very late. If dataLayer.push was above the GTM container (in the code), then All Pages trigger would work well.
I have one question regarding the push function. If I want to push my custom event before any gtm.start or load or error. How can I achieve that?
Place your code above GTM container.
thank you so much for the reply
This makes no sense.
"Although this method is mentioned in the official Google Tag Manager documentation, you should not use it. Why?"
You never actually explain this statement, you just babble on about what is written on the GA site.
Please explain why this is bad? Especially since this (the snippet of code on your and the official GA site) will be at a page level
The explanation is literally in the next paragraphs after what you quoted.
dataLayer.push ( { "event": "newsletter_unsubscribe"} )
Can we use above one without quote
dataLayer.push ( { event: newsletter_unsubscribe} )
No. Unless that newsletter_unsubscribe refers to some variable in that function.
Hi Julius,
I have read many of your tutorials but stuck in one common scenario. I have following data structure to push using dataLayer:
{
event: 'loginSuccess',
category: 'Login',
action: 'loginSuccess',
noninteraction: false, // Optional
loginType: 'Google',
userID: dataObj.user_id
userEmail: dataObj.user_email.
}
I have created the variables in GTM and while creating a loginSuccess event tag to send data to GA I am not able to figure out how to send all the other variables as most of the example show one variable that too they pass in the "label" mapping of GA in the GTM.
I need to send all the variables and track in GA this is one sample there are many such events with 4-5 data variables in each of them.
I am so confused as not able to figure out this small issue.
Thanks in advance.
You need to create datalayer variables for each data point. And then it's up to you how you can to send them. It can be event action, category, label, custom dimensions, etc.
Hey Julius,
Thanks for the great info here and also in your courses (which we have completed). We have a legacy implementation that we'll update in time in which we set the dataLayer variable immediately above the GTM loading script.
When debugging or inspecting GTM and the dataLayer, these values are preserved. However, GTM never sees DOM Ready or Window Loaded events.
The events do not appear in the new debugger/preview, and Tags that should trigger on those events do not fire.
This problem occurs on an ASP.NET website on a subdomain. The same code (without the dataLayer init) on our primary domain works as expected with all events firing.
Have you ever seen something like this? How would you go about finding the problem?
Thanks in advance for your insights!