Universal approach to passing values to dataLayer with .push() method
ライター:JAIN Vibhor
デジタルマーケティングエンジニア 畑岡 大作のコラム「dataLayerへ値を渡す記述を.pushで統一する方法」をデジタルマーケティングエンジニア JAIN Vibhor が英訳したものになります。

The data layer is a variable used by Google Tag Manager (GTM) to pass values from the page data (HTML side) to tags.

From Google’s official guide, there are 2 ways of passing values to this data layer variable: 「using = assignment」or 「calling a .push() method」and it seems, in order to pass proper value each method to be used at an appropriate timing. This has created some confusion during implementation, therefore we discuss a method that can be used at any time.

  1. What is a data layer variable?
  2. Two ways to pass values: 「=」or 「.push()
  3. A universal method to use「.push()」in any case ← main focus of this article
  4. Bonus: How to「.push()」 from child iframe to the dataLayer of the parent frame

What is a data layer variable?

The data layer is one of the Variable types in GTM. It is a recommended way by GTM, and if the page data is output in prescribed format, the value can be automatically used without complex settings in measurement tags such as Google Analytics e-commerce measurement tags.

When GTM loads on the web page, it reads and references the date stored in the JavaScript (JS) variable called dataLayer. This JS dataLayer variable stores the value for the variable, and is automatically acquired by GTM, or you can also pass the data to GTM by executing JS code that passes value from HTML to this JS dataLayer variable. The data passed to the dataLayer variable can then be referenced as a variable.

Create GTM Data Layer Variable

By creating the data layer variable, you make a reference to the specified item in the JS variable called dataLayer.

Data Layer variables are frequently used when you want to pass custom web page data to GTM

If the data you want to use in a certain tag or trigger cannot be registered as a variable, you will need to modify the web page code to pass the data to GTM in some way. However, URLs (referenced by the “URL” variable) cannot be modified so easily, and elements in the body (for ex. div tags, span tags, and other specific HTML parts referenced by the “DOM element” variable) are for display to the user, therefore it is advisable to be careful when modifying the web page code just to pass data to the Google Tag Manager.

In such cases, it is advisable to use data layer variables, which have no particular effect to the user on the screen display.

Besides, another advantage of data layer variables is that simply looking at the page source code you can easily tell that it is a data layer variable (source used by GTM)

Two ways to pass values: 「=」or 「.push()

Following are the two ways to execute the necessary JS code in order to pass data to a data layer variable. In this example, the value of “abc” is passed to the data layer variable “hogehoge”.

    dataLayer = [{'data layer variable name (ex: hogehoge)': 'value to be passed (ex: abc)'}];

    dataLayer.push({'data layer variable name (ex: hogehoge)': 'value to be passed (ex: abc)'});

As you can see, there are two different formats for passing values.
The difference being, the timing at which each method can operate.

FormatFirst time use on pageSubsequent use on the page
dataLayer = [{~~}];Works correctlyWill break GTM and create error
dataLayer.push({~~});JS errorWorks correctly

The first time when dataLayer variable is used on the page, = assignment expression is used; thereafter on any subsequent time, a .push() method is used. This is due to JS rules:  = expression defines a new variable and assigns a new value to it, whereas a  .push() method simply adds a new value to an existing set of values.

A JS error will occur if you try to use the dataLayer variable with the .push() method prior to defining it. 

After having already defined it, on second and subsequent use dataLayer variable already exists with the data defined during assignment at the first occurrence.

However if you use = assignment expression on second and subsequent use , it will erase and overwrite all the data that had been stored so far, and GTM will behave unexpectedly.

The format depends on where it is written on the page.

Note – a default GTM snippet tag also defines a JS dataLayer variable, therefore it is good to be mindful whether your own definition is before or after the GTM snippet. Confusing.

For all these reasons, as we mentioned above, a different format of passing value to data layer variable is used depending on order of processing within the page. This makes it in-convenient, doesn’t it ? and also error prone to use inappropriate format without being aware of the order of processing within the page.

To avoid all this confusion and errors, we propose a universal format that can be used without any problems, irrespective of the first time use or second time and subsequent use of dataLayer.

A universal method to use「.push()」in any case ← main focus of this article

The following method is an order agnostic format of using dataLayer JS variables . Key point is is the Line 2 (highlighted).

    window.dataLayer = window.dataLayer || [];
    dataLayer.push({'data layer variable name (example: hogehoge)': 'value you want to pass (example: abc)'});

What we’re simply doing here is – if there is already an existing dataLayer JS variable, we use that; and if it doesn’t exist we initialize a new empty dataLayer variable. In other words, if the .push() method cannot be used because the dataLayer variable does not already exist, then we go ahead and initialize first. This is the failsafe way to initialize and use a dataLayer variable regardless of the order in which dataLayer variable is used within the page.

The utility of a dataLayer variable increases with the increased usage of e-commerce measurement tags, or advertising tags on the page. If the person adding dataLayer description is aware of the specification of the format, it is okay. However, if the actual code implementation is done by another developer, a common problem that occurs is that the formatting is inappropriate and the page will not operate properly by throwing errors.

In order to avoid such a problem during site operation, the above mentioned unified format of dataLayer is recommended.

Bonus: How to「.push()」 from child iframe to the dataLayer of the parent frame

There are instances when some embedded elements within the page (for ex. iframes) do not have GTM tag snippet installed. Even if you try to use dataLayer.push() method on such a page within the iframe, it will not work because the dataLayer variable does not exist within the iframe. In such instances you can route the value to the parent page’s dataLayer variable.

The following statement can be used to pass value to parent frame

    window.parent.dataLayer.push({'data layer variable name (example: hogehoge)': 'value you want to pass (example: abc)'});

This use case doesn’t appear often, but if you encounter it you can use this format.


JAIN Vibhor