GTM variables part 2: user-defined variables

Google Tag Manager user-defined variables

In one of earlier articles, I mentioned user-defined variables in Google Tag Manager. It is a way to have custom variables in GTM.
Here you can find the easiest ways of use :

  • ID storage for Universal Analytics(it looks like UA-XXXXXXXX-X);
  • Extraction of some particular GET-parameter (e.g., request from internal search on a website) from URL;
  • Getting a value of some cookie parameter (e.g.”user_id”).

Types of user-defined variables

Currently there is a list of following user-defined variables in GTM:

  • 1st Party Cookie;
  • Auto-Event Variable;
  • Constant;
  • Container ID;
  • Container Version;
  • Custom Event;
  • Custom JavaScript;
  • Data Layer Variable;
  • Debug Mode;
  • DOM Element;
  • Environment Name;
  • HTTP Referrer;
  • JavaScript Variable;
  • Lookup Table;
  • Random Number;
  • URL.

1st Party Cookie

It is really handy to use variable: you just need to set cookie name in settings,
it should be the name of cookie the value of which is needed for you.
There is also “URI-decode cookie” option: if your cookie is URL-coded (e.g. “Jack%20London”), than after this option is activated we will get “decoded” value – “Jack London”).

Auto-Event Variable

This type of variable represents the set of 12 options, which are available in “Variable Type” option:

  • Element
    Variable returns a data object for an HTML-element, after any of events from brackets happen (, gtm.linkClick, gtm.linkClick, gtm.formSubmit etc.). You can find this object in dataLayer with gtm.element name.
  • Element Attribute
    You can choose HTML-attribute for this variable type with “Attribute name” option, its value will be returned if any of events happen. For example, if you set ‘alt’ attribute and click on any image ( tag) then the variable value will be set to “alt” current image.
  • Element Classes
    This variable type returns value of “class” HTML – attribute for element after an event.
    For example, after click on <span class=”myspan red”> element this variable will be equal to myspan red.
  • Element ID
    This variable type returns value of “id” HTML-attribute for element after an event.
    For example, after submit of <form id=”lead-form” class=”big-form”> form this variable will be equal to “lead-form”.
  • Element Target
    Returns target HTML-property for an element after an event.
    Example: after click on <a target=”_blank” href=””> link variable will return _blank value.
  • Element Text
    Returns text of an element after an event.
    Example: after click on <a href=”/about”>About me</a> this variable will return “About me” value.
  • Element URL
    This variable returns URL of an element after an event.
    Example: after click on <a href=””> variable will return “”.
  • History New Element Fragment
    Returns hash value after some event in history.
    For example, user navigated from /checkout#step1 to /checkout#step2 (URL of a page is the same but hash is different now).
    The variable value will be step2 (new hash).
  • History Old Element Fragment
    Returns hash value after some event in history.
    User navigates from from /checkout#step3 to /checkout#step4.
    In this case, variable value will be step3 (previous hash).
  • History New State
    Returns history status object after some event in a history(JS-method history.pushState() was executed).
  • History Old State
    Returns history status object before some event in a history(JS-method history.pushState() was executed).
  • History Change Source
    Returns event string which caused history object change.
    For example, pushState and popState.


Another useful variable: some constant string.
A classy example of use is – storage of Universal Analytics(UA-XXXXXXXX-X) ID. In a Google documentation, you can find recommendation to use variable with gaProperty name. It is really handy when e.g. you have around 20 tags linked with Universal Analytics and you need to change ID: then you will only need to make a one change and that is it. However, it is only for the case when you used this variable in all tags. Otherwise, you will have to adjust all 20 tags manually.

Container ID

This variable contains ID of GTM container.
Example: GTM-PFKH9T
There is another equal variable, it can be found in a list of built-in variables and it is called “Container ID”.

Container Version

Returns current version of CGT container.
Example of value: 19.
There is another equal variable, it can be found in a list of built-in variables and it is called “Container Version”.

Custom Event

Returns a substring containing type of an event which happened on a website.
Example of values: “gtm.load”, “gtm.js”, “gtm.formSubmit”, “gtm.Click”.
There is another equal variable, t can be found in a list of built-in variables and it is called “Event”.

Custom JavaScript

In my humble opinion, one of the key types of user-defined variables is the one which allows executing JavaScript code and returns result to a user. Another GMT-variables can be used in this code which is really useful: it is possible to generate a value using a set of variables. For example, you can get id’s of products from dataLayer for Universal Analytics transaction and create string array for another tag (e.g., Adwords Remarketing). It is mandatory to use “return” command otherwise, variable will return “undefined”.

Use Case:

Data Layer Variable

This variable allows referring to values from dataLayer.

  • Data Layer Variable Name: variable name in dataLayer, which needs to be referred to;
  • Set default Value: allows to set set value “by default”. If it is not set, then variable will return “undefined”, when it is not possible to define the value.
  • Data Layer Version: dataLayer version.
    Version 1: this option can be used when variable name contains dots(‘.’). For example, with this data structure:

    Version 2: interpretes dots(‘.’) as nested values.
    For example, if in this case we use “” name, it means that we will refer to “id” field of parent object with name equal to “user”.
    It will suit to this data structure:

I always go with “Version 2”, it is easier to understand and use a hierarchy of dataLayer object. For example, you can get “id” attribute of parent element for a link clicked by user:

Debug Mode

This variable is set to true when you are in a debug mode otherwise it is set to false.
Use: e.g. we send data to one Universal Analytics profile in a debug mode and to another Universal Analytics profile on the live website (when debug mode is turned off).

DOM Element

This variable returns text or a value of a particular attribute of chosen DOM-element.

  • Selection Method: here you set how DOM-elements will be chosen – by ID, or by CSS-selector;
  • Element ID / Element Selector: depending on what was chosen in a first option we set ID or CSS-selector. In general, CSS-selector allows using element ID and wider range of elements;
  • Attribute name: DOM-element attribute name. If it is set then the variable will return value of an attribute. If not then variable will return the text of DOM-element.

Use Case:
Let’s imagine, that we need to get an “href” attribute value for a link of this HTML:

Then we need to use next configuration:
[Selection Method]: CSS Selector
[Element Selector]: a
[Attribute Name]: href

Environment name

Name of environment for new GTM feature used for debugging and testing.

HTTP referrer

Variable contains data about URL which was used by a user to navigate to this page.
Let’s assume that a user navigated to current page from this URL “”.

Variable has “Component Type” option which consists of 7 different variants:

  • Full URL: full URL, from which user navigated to our current page.
    Example: ‘’;
  • Protocol: variable contains protocol of data transfer for referral URL.
    Example: ‘http’;
  • Host Name: contains host name of referral URL.
    This variant contains following option ‘strip www’ – if it is activated then ‘www’ part will be removed from a host name.
    Example: ‘’ or ‘'(if ‘strip www’ option is active).
  • Port: referral URL port number.
    Example: ’80’ for HTTP or ‘443’ for HTTPS.
  • Path: host path.
    Example: “/articles/555/index.php”

    This variable has “Default Pages” option, which allows removing the last element of URL string, which is not a folder if it is in a “Default Pages” list. For example, if we add this “index.php” string to this list, then a variable will return “/articles/555/” instead of “/articles/555/index.php”.

  • Query:
    This variable has ‘Query Key’ option.
    If ‘Query Key’ option is not set, then variable will return the whole query after ‘?’ sign.
    Example: q=gtm+article&page=1;

    If ‘Query Key’ option is set (and some particular GET-parameter is chosen), then variable will contain only the value of this parameter.
    Example: if we use “page” as a “Query key”, then a variable will return ‘1’.
  • Fragment: a variable contains a fragment of referral URL after “#” sign.
    Example: ‘part2’ for URL from the example above.

JavaScript variable

Returns value of a global JavaScript-variable, the name of which is set in “Global Variable Name” field.
This variable can be useful if e.g. it is known that 3rd party JS-script stores date in some global variable and these data are not accessible through dataLayer or DOM.

Example: if “Global Variable Name” field is set with “window.location.hostname” value, then variable will contain a host name.

Lookup Table

Setup of this variable includes setup of “input variable”. A couple of “key-value” pairs, in the output variable, will be defined using values set up on previous steps.
For example, on our website we have 3 buttons of socials networks with id “button-facebook”, “button-twitter”, “button-gplus”.
Let’s assume that after clicking on any of them we need to send data to Universal Analytics describing which button was clicked exactly.

  • In “Input Variable” option we chose {{Click ID}} variable;
  • In “Lookup Table” option we click on “Add Row” and set
    [“button-facebook”] [Facebook]
    [“button-twitter”] [Twitter]
    [“button-gplus”] [Google+]
    as “key-value” pairs.
  • If we need we can also set “Set Default Value” option with some default value.
  • And save the variable.

What happens next: after one of social network buttons is clicked its ID is sent to already created “Lookup Table” variable, in which we have a process which checks for relevance to one of “key-value” pairs. If {{Click ID}} value is equal to one of “keys”(e.g.,”button-twitter”) then “Lookup Table” variable will return (“Twitter”) value, which corresponds to current key.

Unfortunately, variable checks for a full match only so it is not possible to use logical expressions like “Matches RegEx” or “Begins with”.

Random Number

This variable just returns a random number from 0 to 2147483647, it doesn’t have any other options.


This variable has two options:

  • Component Type – this option (and its variants) is absolutely identical to “Component Type” option of “HTTP referrer” variable, thus we won’t discuss it in more details.
  • “URL Source” option allows choosing URL source: e.i. Input variable URL of which can be divided into needed parts.
  • For example, a website contains a couple of external links which can be potentially used by users to leave the website and after each click we will need to send domain names of links to Universal Analytics. Then we will need to set [Component type] with a “Host Name” option, and choose {{Click URL}} variable as an input variable for [URL Source].

    Then after clicking on “” link the value of a variable will be “”.


    User-defined variables are a powerful instrument of the Google Tag Manager for the GTM container use. On the one hand almost all of these variables can replace often used JavaScript templates. On another hand wide opportunities for customization allow creating personalized variables for any needs using JavaScript as a base.

Digital analytics consultant.

Want to improve your website performance?
Contact me!