Types of variables

Tag Manager

When you create a variable, you can choose several types of variables. Each type has specific elements that you can adjust to store data. In this article, we’ll explain how each type of variable 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.

Custom JS variable in Piwik PRO

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. Additionally, all numeric strings will be converted to numbers and TRUE, true, FALSE, false string will be converted to a boolean value.

Note: It may be tempting to use variables inside custom JavaScript variable, but Tag Manager doesn’t support it yet.

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

  • The random number between 0 and 10
    function () {
    return Math.floor(Math.random() * Math.floor(10));
    }

    The assigned value will be a number.

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

    The assigned value will be an array.

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

    The assigned value will be a boolean value. True, if an element with an id for the main-header exists, false in other cases.

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

    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.

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

    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.

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.

Constant variable in Piwik PRO

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

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

Cookie variable in Piwik PRO

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.

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

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.

Data layer variable in Piwik PRO

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.

DOM element variable in Piwik PRO

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 hashtag (#).

  • CSS selector: You can select one or more elements using CSS selectors. For example:
    • div.section — will return all div elements that have section class (this is hard with XPath).
    • a[title] — will return all a elements that have title attribute.
    • #main — will return element with 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 section as a substring of class attribute.
    • //a[@title] — will return all a elements that have title attribute.
    • //pTypes of variables — 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.

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

Document variable

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

Document variable in Piwik PRO

Here are the most common properties you could use: title, location, protocol, host, href, hash, pathname, 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.

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.

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.

Random number variable in Piwik PRO

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.

URL variable in Piwik PRO

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

  • GET pararmeter: 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.

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