Google Tag Manager Data Layer Explained Graphically

A developer's guide to the Data Layer

A step-by-step guide to work with the Data Layer

Written by Lars Skjold Iversen

“Hello Friendly Developer, I need you to push something to the Data Layer - can you do that?” Does that sound familiar to you? If you’re a developer and you’re working closely with marketers, it probably does. But why are marketers so excited about it? And how do you make sure you set everything up correctly in the code? In this blog post I’ll guide you through what you need to know about it to make life easier for you and your marketers.

If you’re a developer you might not have a long and extensive history of working with the Data Layer. So when a marketer asks you to implement it or push data to it, you might wonder why it matters.

Today I’ll try to take you through it - step-by-step. In the end you will take away 3 things:

  1. An understanding of what the Data Layer is and why it’s important to marketers (and your business!)

  2. A step-by-step developer’s guide to implementing a Data Layer and how to push data to it the right way (spoilers: following official documentation is a bad idea...)

  3. A list of questions to ask a marketer to ensure you’re on the same page in order to ensure your Data Layer setup is as effective as possible.


If you’re already familiar with what the Data Layer is and why it’s important to marketers, there’ll be no hard feelings if you jump straight to the developer’s step-by-step guide to the Data Layer 😉

But before I get started, let’s just clear something up:


What’s the difference between Data Layer and dataLayer?

When you’re reading blog posts and documentation about the Data Layer you might run into “dataLayer” instead of “Data Layer”. The difference is whether it’s referring to the overall concept of a Data Layer or if it’s about the data structure that is used by the tag management solution. When working with Google Tag Manager (which I’ll be doing in this post), the name of the Data Layer will be “dataLayer”. So when you’re working with Data Layer in the code, you should always remember to use dataLayer.


What is a Data Layer?

A Data Layer is a virtual layer between your website (code and server) and your tag management solution (such as Google Tag Manager), where you can store, process and pass data. Technically speaking it is a JavaScript object, which in some cases will also be referred to as a Universal Data Object (UDO).

Think of it like a virtual “master” layer of all data accessible on the website. When data is put into the Data Layer, it makes data from the website easily readable by their tag management solution and thereby easy to pass on to various analytics or marketing tools (Google Analytics, Google Ads, Facebook, LinkedIn, etc.).

Google Tag Manager Data Layer Explained Graphically

The more data that is put into this layer, the more knowledge a marketer will get about user behavior. With this added knowledge it is easier to serve better and more relevant content, ads and campaigns to the users, which in the end makes everyone win (better content = happier users = more sales).

But let’s take it a step further. A step that’ll not just reveal why marketers love working with the Data Layer, but also why it’s important that both marketers and developers have an understanding of how it works as otherwise, there won’t be that much “winning” going on:


What is the deal with marketers and the Data Layer? (and why developers should care)

The ultimate goal for marketers today is to sell products or services. To do that, they need to serve relevant content to their users. But in order to know what is relevant - and more importantly, what is NOT - you need an understanding of what your users like and dislike. Traditionally, this insight has come through surveys, polls and trial-and-error, but with the rise of the internet and online marketing, this user data has become more readily available through online tracking tools.

And this is exactly where the Data Layer comes in.

The Data Layer expands the pool of data available for a marketer in a way that is easy to work with and understand. Marketers love using the Data Layer because it gives them more data to process and use to understand the behavior of their users. In web analytics tracking it is not enough to just know if someone saw a page - you want to know more. You want to know more about the users who visit and you want to know more about the actions these users take on your website.

Only then will you be able to get a better understanding of their behavior, which will enable you to answer more complex questions like:

  • Do your users prefer to read about zebras or horses?
  • How much of your videos do people watch before they get bored?
  • Did they submit a contact form on your campaign page? (I actually wrote an entire post about this specific topic, if you’re curious 😉)
  • Did they end up completing a purchase - and if so, which products did they buy?


Thanks to the Data Layer, the answer to these questions are now within the grasp of a marketer. And while a lot can be accomplished with Google Tag Manager’s built-in functions without involving a developer, there are limitations. This is especially true when the marketer wants to access data that is stored on the website’s server. That could be data such as a user ID or transactional data about a purchase which is not readily available on the website. To get this data into the Data Layer, a developer’s help is needed.

Unfortunately, this often leads to issues, due to a combination of 2 things:

  1. The marketer lacks the technical knowledge about the Data Layer. It is quite technical and requires some knowledge of JavaScript, which not all marketers have.
  2. The developer lacks experience with the Data Layer. Not all developers have prior knowledge of the dataLayer and the structured data model used by Google Tag Manager.


What happens is that the marketer won’t know enough to give a thorough specification of what they want the developer to do, and the developer won’t have the necessary knowledge of the structured data model to know exactly what to do.


This really is no one's fault, but unfortunately, the combination often leads to a lot of confusion and wasted time for everyone involved. And a simple task like adding a dataLayer.push to a JavaScript event then becomes a frustrating and tedious task for everyone involved.

To help you avoid all of those frustrating issues, I’ll introduce you to my developer’s step-by-step guide, so you’ll be ready to help your marketer out when they need your help.


A developer’s step-by-step guide to the Data Layer

Working with the Data Layer is not that complicated as long as you know the basics about how to implement and structure it.

To uncover this black box, I’ve chosen to go through it step-by-step and split it into the following steps that covers the basics you need to know:


How to implement a Data Layer for Google Tag Manager

If you want to send data to the Data Layer, then you first need to make sure that it is actually implemented on the website. Luckily, a Data Layer implementation is often not even needed - it will already be implemented for you. But instead of assuming that the Data Layer implementation is on point, let's quickly make sure that it is. Here’s how you can check (and implement, if it’s not there for some reason).

First step is to check the source code of your website and look for either a Google Tag Manager snippet or a Google Optimize snippet in the <head>. 

 Google Tag Manager container snippet


 Google Optimize snippet


If you find either of those on your website, then it will already have the dataLayer implemented and ready to be used.

As you can see in both of the snippets, they have references to “dataLayer”, which is what both tools use to function properly. As long as you see either of these snippets on the website, the Data Layer is already implemented and you do not have to do more to implement it.

If for some reason, neither of those are on the website and they can’t be added, then you will need to implement it before you can start pushing data to the Data Layer. To do that, you will need to add the following snippet before pushing any data:


As you will see next, part of this code will be used for pushing data as well. That’s it - now the Data Layer is implemented and ready to receive data.


How to get data into the Data Layer

When it comes to actually adding data to the Data Layer there are 2 options:

  1. Using a Data Layer declaration
  2. Doing a Data Layer push (dataLayer.push)

One is the right way, and the other is very wrong.

Let us start with the wrong way of doing it, so we get that out of the way.


The wrong way: Data Layer declaration

One way to get data into the Data Layer is by declaring what should be in there. Even though this method is wrong to use in most situations, it is still mentioned in Google’s official documentation, which has caused a lot of issues over the years.

According to this documentation, If you want to add data with a Data Layer declaration, you would be adding it the following way:


When this data is pushed, an event named “signup” will be pushed to the dataLayer with the information that the “userType” is “Free User”. This is exactly what you want to have in there. There’s just one problem:

By declaring the dataLayer you are effectively overwriting any other data that might be in there - essentially breaking the rest of your tracking.

Ouch (again)!

The reason it is used in the official documentation is that it works in one situation, which is the one described in the documentation: When you add data to the dataLayer above the Google Tag Manager container.

In that case, declaring the Data Layer works, because the Google Tag Manager snippet checks if a dataLayer exists. If it does - which it would in this case - then instead of overwriting it (the bad declaration way), it modifies and adds to it (the lovely dataLayer.push way).

If it happens the other way around (GTM snippet first, then the above declaration) the declaration will not check if dataLayer exists, but will simply overwrite the dataLayer with the values being declared.

Instead of worrying about any of this (and making your marketer sad), you should make it a habit to never use Data Layer declaration and instead do it the right way - with a Data Layer push.


The right way: Data Layer push

Another way to add data to the Data Layer is to use “dataLayer.push”. By using this method you will not run into any issues with overwriting data. Simply by having 1 line of code together with your dataLayer.push, you will effectively avoid any issues further down the line.

If we want to add the information about “userType” by using a dataLayer.push, the code would look like this:


What happens here is essentially the same as we saw above, but by doing it this way, the dataLayer.push will go through the following process:

  1. Check if a dataLayer already exists
    • If yes, modify it
    • If no, initiate it
  2. Push the data


Instead of using a declaration (even when it would work), you should make it a habit to always use the dataLayer.push snippet. It will work in all possible situations and you will not end up in a situation where you used it the wrong way and broke something.

Oh, and just in case you’re wondering “can I do dataLayer.pop instead”, then the answer is no. Google Tag Manager only listens to “.push” and if you try to do anything else you’ll find yourself at a dead end. So when push comes to shove (yes, that's a pun) you should just accept that dataLayer.push is always the right thing to do.

Now that you know how to implement the dataLayer and push data to it, there’s just one small favour left to ask as a marketer: that you make it easily accessible with a dataLayer.push event. That’s the final step in the guide - I promise.


How to make the data easily accessible

While the actual data being pushed into the dataLayer will vary a lot, there’s always 1 part of it that should be present: an event name.

As shown in the examples above, we have used the special data layer variable called “event”. This will make the life of a marketer about 147 times easier and I’ll show you why.

Below are two screenshots of how the Google Tag Manager preview & debug mode looks like when the above dataLayer.push is done. The first example is with the “event” as part of the push and the second is without.

dataLayer.push with an event

dataLayer.push with an event name.


dataLayer.push without an event

dataLayer.push without an event name.

While the data being pushed is the same - the way a marketer can use it is very different. In the first example, the event name enables a marketer to use it in their triggers where they can fire a tag based on a custom event trigger. Without the event name, this is not possible as no custom event actually occurs in this case.

So if what you’re tracking is some kind of action - say someone fills out a contact form - then you can only fire tags on that event if it has a name. Otherwise it will be impossible, even though the data is pushed correctly to the dataLayer.


To boil it all down, here’s what you should do if a marketer asks you to add data to the Data Layer:

  1. Make sure the Data Layer is implemented

  2. Use the dataLayer.push snippet as shown above (the right way 😉)

  3. Always give your dataLayer.push an event name - even if the marketer forgot to ask for it


Now you’re good to go and will have a much easier time helping out your marketer when they want more data in the Data Layer. As a last thing, I’ve added 3 helpful questions you can ask your marketer colleague to get more clarification on the task if you’re still unclear about what to do.


3 clarification questions to ask the marketer

If the brief given to you by the marketer was unclear and you don’t know what to do, then here’s a few questions you can ask, that should help you solve the task.


When do you need the data to be available?

Hopefully, this should be an easy question to answer for a marketer, but there might be some quirks in it that you as a developer have to be aware of. First of all, you need to know if the data has to be available when a page loads.

If that is the case, then you need to implement the dataLayer.push above the GTM snippet in the <head> of your site’s code.

If you don’t, the data is pushed after all pageview triggers are fired and the data will thus be unavailable (since it wasn’t pushed until after).


When do you need the data to be pushed?

This is largely related to the one above but is still important if it isn’t already clear. Is the data something that should be available on pageview, click, timer or interaction?

If it’s signup data like the push we used in our example, it should only be fired when the signup happens - not just on page load. Once you know when the data needs to be pushed, you can add it at the right time.


What data do you need to be pushed?

While this will most likely be in the brief, it’s very important to agree on which data is being pushed and how it’s structured. This includes how to spell the key-value pairs as they are case-sensitive.

This is fairly easy to do if it’s something simple like the example of “signup” in this post. But if it’s something complex like enhanced ecommerce events, it’s very important that you both know exactly how it is pushed and structured. Otherwise, it can cause issues later on and you’ll need to redo it.

And lastly, remember to ask for the event name of the dataLayer.push. Always.


That’s it - now you’re ready to help your marketer do awesome stuff with the Data Layer - #H5YR!

If you have any questions, comments or additions to the blog post, feel free to send me an email at I love to talk about tracking, data and attribution with anyone who will listen 🙂


Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox