About custom variables

In Tag Manager, you can use built-in variables or create your own custom ones. When you create a custom variable, you pick what type it is. In this article, we’ll explain how each type works.

Custom JS variable

A custom JS variable is the most powerful of all possible variables. To create one, you need to write a JavaScript function that ends with a return statement. The variable value will be whatever the function returns.

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

Here are some examples that show how powerful a JavaScript variable can be:

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 example, the URL https://example.com/#about will assign the value about to the variable. If the URL doesn’t contain a hash (#), the variable value will be an empty string.

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

Detect a mobile browser: This variable will detect visitors using mobile browsers and return a true or false value. Based on this variable, you can create a trigger that will fire a tag for visitors who use 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 of all. 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 strings will be converted to boolean values.

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. Just be aware that all numeric strings will be converted to numbers and TRUE, true, FALSE, false strings will be converted to boolean values. 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 in your site’s source code. For more on data layers, see this article.

Document variable

A document variable lets you access any document object property. For example, you can access 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. Those mentioned above are strings.

DOM element variable

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

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

• Element ID: You can select an element ID on your page. Just type in the ID in variable settings. The element ID is unique to each page, so it’s the only element that will be used in determining the variable value.

  Note: When copy-pasting element IDs, remember to exclude additional characters. Element IDs should not be preceded by tag names or the hash symbol (#).

• 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.
  • a[title] will return all a elements that have a title attribute.
  • #main will return the element with the main ID.
• 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 a 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).

You can also extract the text content of an element. Here’s how it will influence the value:

• When Extract text content of an element isn’t selected, variables will hold boolean values — true if the element is found, false otherwise.
• When Extract text content of an element is selected, variables will hold texts extracted from the element (and all its descendants). If the element doesn’t include text, the variable value will be an empty string.

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 mapping different values, such as campaign IDs, product IDs and product names. It can also help you organise and categorise your data.

To use a lookup table variable, you first need to 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 see if it matches any of the inputs in the lookup table. If it does, the variable value will be 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 the lookup table variable:

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

• The input variable can be either a built-in or custom 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 type of 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 where 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 returns a random value between 0 and 1 (inclusive of 0, but not 1). This variable always has 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 the page URL is https://clearbank.com?source=newsletter&medium=email, we can extract the newsletter value.

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

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

  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 strings will be converted to boolean values.

• Query: This option will pass a complete query string for your variable. For example, for the page URL https://clearbank.com?source=newsletter&medium=email, it’ll pass source=newsletter&medium=email.

  When your query string is empty, this value will be an empty string.

• Protocol: This variable will receive and pass http or https as a value.