About user-defined variables

Tag Manager

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

Custom JS variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

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

Constant variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Cookie variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Tip: If you use authentication on your website, you can extend User ID tracking to return users without them needing to authenticate. This can be done with a cookie.

Tip: You can save the number of visits in the cookie and then, for example, fire a different tag for the first time and x time visitor.

Data layer variable

Data layer variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Document variable

Document variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Tip: An activeElement property returns the currently focused element in the document so based on the element that is returned you can trigger a specific tag.

DOM element variable

DOM element variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Tip: A DOM element variable is useful when you want to fire an event only if a certain element is on the page.

Random number variable

Random number variable in Piwik PRO

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

URL variable in Piwik PRO

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.

Note: Available from 16.30.0 You can use a variable inside another variable. Just keep in mind that a variable can’t contain a circular dependency. Don’t create a closed loop. Example: A depends on B, B depends on C, C depends on A.

Was this article helpful?

Technical support

If you still have some questions, visit our community.
There’s always someone ready to help!

Back to help center