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. The value of the custom JS variable is based on the result of the JavaScript function. Just remember, a JavaScript function needs to end with a return statement.

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. The value of the constant variable is set to the string you provide. It’s useful for storing API keys, account IDs and other numbers.

All numeric strings will be converted to numbers and TRUE, true, FALSE, false strings will be converted to boolean values.

Cookie variable

The value of the cookie variable is based on the cookie you provide.

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

The value of the data layer variable is set to the data pushed to the data layer. For more on data layers, see this article.

Document variable

The value of the document variable is based on the document object’s properties, such as document.location.hash or document.title.

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

The value of the DOM element variable is based on a specific site element like element 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

The value of the lookup table variable is based on the instructions in the lookup table. It’s useful for creating a variable that varies according to the value of another variable. It can help you map campaign IDs, product IDs and product names, as well as 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

The value of the random number variable is set as a random value from 0 to 1, including 0 but not 1.

Here are examples of values for a random number variable:

• 0.8452040655517055
• 0.6075614549571422
• 0.44718786263204824
• 0.13507537026019567

URL variable

The value of the URL variable is based on the components of the page URL. For example, it can extract a ‘newsletter’ value from https://example.com?source=newsletter.

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.