Variables Guide in Google Tag Manager——User-Defined Variables

Table of Contents

Update time: January 14, 2025

This article introduces User-Defined Variables

What are User-Defined Variables?

Create custom user-defined variables in Google Tag Manager to suit specific requirements that might not already be covered by built-in variables.

Enable User-Defined Variables

In GTM, click 「Variables」——「New」——「Choose a variable type to begin setup…」:

You can choose different User-Defined Variables types to customize, and the custom setting interface for each User-Defined Variables is different.

User-Defined Variables Categories

Different container types have different User-Defined Variables, such as Web, AMP, and iOS.

This article mainly introduces the Web type, which provides 5 categories and 23 User-Defined Variables.

Let’s introduce them one by one:

Navigation

The Pages type has 2 User-Defined Variables:

HTTP Referral：The value is set to the HTTP referer, which is the URL of the previous page that the person visited. It contains different Component Types, eg:
- Full URL：Returns the full URL without the hash fragment
- Protocol：Returns the protocol of the URL，Usually http or https
- Host Name：Returns the hostname of the URL without the port number
- Port : Returns the port number used in the URL，Generally http is 80, https is 443, Will not be displayed in the URL
- Path：Returns only the path name in the URL
- Query：Returns the entire query parameter string
- Fragment：Returns the value after #
URL：This type of variable allows you to parse and expose URL components. It contains different Component Types, eg:

- Full URL：Returns the full URL without the hash fragment
- Protocol：Returns the protocol of the URL，Usually http or https
- Host Name：Returns the hostname of the URL without the port number
- Port : Returns the port number used in the URL，Generally http is 80, https is 443, Will not be displayed in the URL
- Path：Returns only the path name in the URL
- Filename Extension : File type, such as html, zip
- Query：Returns the entire query parameter string
- Fragment：Returns the value after #

Page Variables

Page Variables has 4 User-Defined Variables:

1st Party Cookie：The value is set to the first value of the 1st party cookie with the matching name.

Custom JavaScript：This variable uses the provided JavaScript function to calculate its value in the browser. Each time this variable is used, the function will be executed and its return value will be used.

Data Layer Variable：The value is set when data is pushed to the data layer via the dataLayer.push() call.
- Version 1: allow dots in key names. For example, for dataLayer.push("a.b.c": "value"), interpret the name of the key as “a.b.c” (i.e. {"a.b.c": "value"}).
- Version 2: interpret dots as nested values. For example, interpret dataLayer.push({"a.b.c": "value"}) as three nested levels: {a: {b: {c: "value"}}}

JavaScript Variable：The value is set to that of the global JavaScript variable you specify.

Page Elements

Page Elements has 3 User-Defined Variables:

Auto-Event Variable :Captures information about an item that triggered an event (e.g. clicks, form submissions, element visibility, etc.)
- Element: Returns the element object. Can be treated like an object for custom JavaScript, e.g. {{Element}}.title, or in CSS selectors, e.g. {{Element}} matches CSS Selector div.foo.
- Element Type: Returns the value element.tagName, e.g. “A”, “BUTTON”, “IMG”.
- Element Attribute: Specify an attribute name and this option will return the value of that attribute.
- Element Classes: Returns the list of classes found in the element’s class attribute.
- Element ID: Returns the value of the id attribute.
- Element Target: Returns the value of the target attribute, e.g. “_blank”.
- Element Text: Returns the value of the text content of the element.
- Element URL: Returns the URL of the element, gathered from the href or action attribute.
- History New URL Fragment: Returns the new URL fragment from browser history, e.g. “#summary”.
- History Old URL Fragment: Returns the old URL fragment from browser history, e.g. “#intro“.
- History New State: The new history state object, controlled by the site’s calls to pushState.
- History Old State: The old history state object, controlled by the site’s calls to pushState.
- History Change Source: Returns the event that caused a history change, e.g. “pushState”, “replaceState“, etc.
DOM Element: The value is set to the text of the DOM element or the value of the specified DOM element attribute.

Element Visibility : The value is set based on the visible state of the specified DOM element.

Utilities

Utilities has 11 User-Defined Variables

Constant: The value is set to a string you provide, usually set to ID, such as Tracking ID, Measurement ID, Pixel ID……
Custom Event: The value is set to the name of the custom event that was pushed to the data layer. The value is set to “eventNameXYZ” when the following code on your website is executed: dataLayer.push({‘event’: ‘eventNameXYZ’});
Environment Name: Returns the name of the environment, by default there are live and last environment, click「Admin」——「Environments」：
~~Google Analytics Settings~~: Used in UA version, has been abandoned

Google Tag: Configuration Settings ：This variable enables you to configure Google Analytics 4 settings for use across multiple Google Analytics 4 tags.
Google Tag: Event Settings ：This variable enables you to configure Event Parameter and User Property settings for use across multiple Google Analytics 4 tags.

Lookup Table：The value is set according to the instructions in the lookup table. The lookup table contains two columns. (Table is empty to illustrate how data is used later):

When [select variable] equals	Set [this variable] to

The Lookup Table allows you to create a variable for which the value varies according to the value of another variable. This is useful if your website is set up in such a way that the appropriate value (for example, a conversion ID) can be mapped to the URL, DOM element, or other part of the page. In this example, a variable named Conversion ID is created. If the URL contains “/thanks/buy1.html”, the value is set to “12345”; if the URL contains “thanks/buy2.html”, the value is set to “34567”.

When {{url}} contains	Set {{Conversion ID}} to
/thanks/buy1.html	12345
/thanks/buy2.html	34567
/thanks/buy3.html	56789

Random Number：Random Number returns an integer random number between 0 and 2147483647, no configuration required.
RegEx Table：A RegEx Table variable is similar to a Lookup Table variable, with the addition of being able to run regular expression patterns for the items you want to match.

For this RegEx Table configuration:

Pattern	Output
`./page[1-3]\.html.`	foo
`./page[4-6]\.html.`	bar
`./page[7-9]\.html.`	baz

The output value of the variable will be as follows:

Matched result	Value
http://example.com/page1.html	foo
http://www.example.com/page1.html	foo
http://example.com/page2.html#detail	foo
http://example.com/page5.html	bar
http://example.com/page5.html?status=new	bar
http://example.com/page6.html	bar
https://example.com/page9.html	baz

RegEx Table lookups run from the top of the list to the bottom. When a match is found, the corresponding output value is returned.

Undefined Value：Contains the JavaScript ‘undefined’ value.
User-Provided Data：This variable enables you to configure user-provided data for supported tags.

Container Data

Container Data has 3 User-Defined Variables:

Container ID：Returns the ID of the Tag Manager container, no configuration required. e.g. ‘GTM-PHXQ69M’.
Version Number：Returns the current container version number, if it is preview mode, it will return the container’s preview version number. If it is live, it will return the container’s live version number. No configuration required.
Debug Mode：If it is preview mode, the return is true; and false if not. No configuration required.

The use of User-Defined Variables

Built-In Variables have two uses:

Variables in triggers are used to define filters that specify when a particular tag should fire. Example: Fire a pageview trigger when the url variable is “example.com/index.html”.
Variables in tags are used to capture dynamic values. Example: Capture and apply the transaction value and products purchased to a key events tag.

If you don't understand, You can leave a comment below.