About user-defined variables

In Tag Manager, you can use built-in variables or custom (user-defined) variables. When creating a custom variable, you choose a variable type. In this article, we’ll try to explain how each type works.

Custom JS variable

A custom JS variable is the most powerful one. To create it you need to write a JavaScript function that ends with a return statement. What is returned from this function will be assigned to the variable.

Because JavaScript runs in a browser, you can use the following objects: window, document, location, and localStorage. You can use all values available in JavaScript.

Here are some examples that will show you the power of a JavaScript variable:

The random number between 0 and 10: The assigned value will be a number.

function() {
    return Math.floor(Math.random() * Math.floor(10));
}

Constant array (10 primes): The assigned value will be an array.

function() {
    return [2, 3, 5, 7, 11, 13, 17, 19, 23, 29];
}

DOM element: The assigned value will be a Boolean value. True, if an element with an ID for the main-header exists, false in other cases.

function() {
    return null !== document.getElementById('main-header');
}

URL hash: The assigned value will be a string. For the URL https://example.com/#about we will have about assigned to the variable. If the URL won’t have a hash (#), the variable will have an empty string.

function() {
    return location.hash.replace(/^#/, '');
}

Detect a mobile browser: This variable will detect when a visitor uses a mobile browser and return true and false value. Based on that, you can create a trigger that will fire a tag for visitors who uses mobile browsers.

function() {
    if (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
        return 'true';
    } else {
        return 'false';
    }
}

Constant variable

The constant variable is the simplest one. You can use it to store a constant value. For example, you can type in public API keys for your tracking code and access it via a variable.

All numeric strings will be converted to numbers and TRUE, true, FALSE, false string will be converted to a Boolean value.

Cookie variable

The cookie variable lets you read cookie values. To make it work, type in a cookie name.

Cookies are strings so in most cases you will get a string as a result. Only know that, all numeric strings will be converted to numbers and TRUE, true, FALSE, false string will be converted to a Boolean value. If your cookie is more complex than that — for example, JSON — you will need to handle it differently.

Data layer variable

A data layer variable lets you pass data from the data layer added to your site’s source code. For more, see an article about the data layer.

Document variable

A document variable lets you access any document object property. For example, you can assign a location.hash property.

Here are the most common properties you could use: title, location.protocol, location.host, location.href, location.hash, location.pathname, location.search, domain, URL, documentURI, and referrer.

This variable always has a value and its type depends on an assigned document property. All mentioned above are a string.

DOM element variable

A DOM element variable lets you use elements from your website as a variable. For example, an element with an ID, or with a CSS class, or with the XPath.

Here’s a detailed description of each element that can be used in this variable:

• Element ID: You can select an element ID used on your page. Just type in the ID in a variable settings. The element ID is unique on the page so only one element will be used to get the variable value.

  Note: Please remember to paste an element id without any additional characters. It should not be preceded by the element’s tag name, nor by a hash (#).

• CSS selector: You can select one or more elements using CSS selectors. For example:
  • div.section will return all div elements that have a section class (this is hard with XPath).
  • a[title] will return all a elements that have title attribute.
  • #main will return element with the ID main.
• XPath: You can select one or more elements using XML path language. For example:
  • //div[contains(@class, 'section')] will return all div elements that have a section as a substring of class attribute.
  • //a[@title] will return all a elements that have a title attribute.
  • //p//a will return all p elements with an a child (this is impossible to select with CSS selectors).

Additionally, you can select to extract the text content of an element. Here’s how it will influence the value:

• When Extract text content of an element is unchecked a variable will hold a value of the Boolean type — true if the element is found, false otherwise.
• When Extract text content of an element is checked a variable will hold a text extracted from the element (and all its descendants). If the element doesn’t have a text, the empty string will be held.

Lookup table variable

Available from 16.33.0

A lookup table variable uses an input variable and a lookup table to determine its value. This is useful for creating a mapping between different values, such as campaign IDs, product IDs, and product names. It can help you organize and categorize your data.

To use a lookup table variable, you first define the input variable, for example, {{Referrer}}. Then, you create a lookup table that maps inputs and outputs. The lookup table variable will use an input variable to check if it matches any of the inputs in the lookup table. If it does, the variable value is set to the corresponding output value. Here’s an example:

• Input variable: {{Referrer}}
• Lookup table:
  • Input: https://big-promo.example.com/
  • Output: big promo

In this case, if {{Referrer}} is https://big-promo.example.com/, the variable value will be set to big promo. This is a useful way to quickly access and use data from a lookup table.

Here’s a table that can also help you understand lookup table variable:

Here’s some key information about the lookup table variable:

• The input variable can be either a built-in or user-defined variable.
• The input variable value is always converted to a string for comparison with the lookup table inputs, so set it to a variable whose value is a string, number or boolean for best results.
• The input and output values are case-sensitive and can be any string (including an empty string) or reference to another variable, for example, {{variable}}.
• You can add as many pairs of inputs and outputs as you like to the lookup table.
• If the input variable matches multiple inputs, the variable will return the output for the last match.
• You can set a default value for cases when no match is found in the lookup table. This default value can also reference other variables, for example, {{variable}}.
• If no match is found and no default value is set,  the lookup table variable will return undefined.

Random number variable

A random number variable gives a random value between 0 and 1 (inclusive of 0, but not 1). This variable has always a value and its type is numerical.

Here are examples of values for a random number variable:

• 0.8452040655517055
• 0.6075614549571422
• 0.44718786263204824
• 0.13507537026019567

URL variable

A URL variable lets you access components of the current page URL. For example, if we have a page URL  https://clearbank.com?source=newsletter&medium=email we can pull out the newsletter value.

Here’s a detailed description of each element that can be used in this variable:

• GET parameter: You can pass selected GET parameter to this variable. For example for the page URL https://clearbank.com?source=newsletter&medium=email you can choose source to pass newsletter to your variable.

  When your GET parameter is not present or has no value, the variable value will be an empty string. Numeric strings will be converted to numbers. TRUE, true, FALSE, false string will be converted to Boolean values.

• Query: With this option our variable will get full query string. For example for URL https://clearbank.com?source=newsletter&medium=email you will get source=newsletter&medium=email as your variable’s value.

  When your query string is empty, this value holds empty string.

• Protocol: Here your variable will receive http or https as a value. This variable will always hold either http or https.