How to use variables in tags and triggers

Tag Manager

In tags and triggers, you can use built-in variables, such as a page URL, page path, referrer, and more. Or, you can create your own variables.

In this article, we’ll explain how you can use variables.

Access a variable in tags and triggers

Both buit-in and custom variables can be accessed from the list of variables in tags and triggers.

Variable in a tag

A variable in a tag in Piwik PRO

Variable in a custom tag

A variable in a custom tag in Piwik PRO

Variable in a trigger

A variable in a trigger in Piwik PRO

Built-in variables

Variable name Description
Click ID Contains the ID of the clicked element. It changes its value when a visitor clicks an element with the chosen ID.
Click Url Contains the URL of the clicked element. It changes its value when a visitor clicks a link with the chosen URL.
Click Classes Contains the class(es) of the clicked element. It changes its value when a visitor clicks an element with the chosen CSS class.
Form ID Contains the ID of the submitted form element. It changes its value when a visitor submits a form with the chosen ID.
Form Url Contains the URL of the submitted form element. It changes its value when a visitor submits a form that sends a request to the chosen URL.
Form Classes Contains the class(es) of the submitted form element. It changes its value when a visitor submits a form with the chosen CSS class.
Form Name Contains the name of the submitted form.
Event The name of the event emitted on a data layer. It changes its value when a chosen custom event occurs in a data layer.
Time on website It changes its value when the visitor is on the website or page for a certain time. For example, it fires a tag when a visitor spends at least 15 seconds on a page or website.
Page Scroll It changes its value when a visitor scrolls to the chosen point on a page. For example, the visitor scrolls 50% of a page or scrolls to 1440 px on a page.
Leave content It changes its value when the cursor leaves a page. You can choose two options for this condition: page exit intent (the cursor leaves a page via the top edge) or cursor leaving the browser’s area (the cursor leaves the page via any edge).
Page Url Contains the whole URL of the current page.
Page Path Contains the path of the URL of the current page.
Page Hostname Contains the hostname of the URL of the current page.
History source Contains information about the last method or event that updated the history object. It changes its value when a pushState, replaceState, popState or hashchange event occurs.
History state Contains the current HTML5 history state. It changes its value when a history state meets a defined condition.
Old history state Contains the previous HTML5 history state. It changes its value when a previous history state meets a defined condition.
History fragment Contains the current anchor (#) in the page URL. It changes its value when an anchor (#) in the page URL meets a defined condition.
Old history fragment Contains the previous anchor (#) in the page URL. It changes its value when an anchor (#) in the previous page URL meets a defined condition.
View within session Contains time in seconds from the last interaction.
Referrer The page URL that linked to the current page.
External referrer The URL of the page from the website with a different hostname that linked to your current website.
Campaign Its value based on the utm_campaign or pk_campaign parameter from the URL.
Traffic source Contains traffic source: campaign, organic search, social, website, direct. It changes its value when a visitor clicks on an element on a page they came to from the traffic source: campaign, organic search, social, referral, direct.
Returning Visitor Logical condition which says if this is the visitor’s first visit or not. It changes its value when a returning visitor clicks an element on the chosen page (this mechanism is based on the cookie).
Consents Contains information about the current and previous state of visitor consent.
Found elements Variable used in the element presence trigger. It contains the class name of the found elements that the trigger was set to look for.

Variables and a context in a custom tag

When you’re using a variable in a custom tag, you need to pay attention to the context. By context, we mean a place where the variable is used. As long as contexts are not mixed everything will work correctly.

Now, we’ll show you a couple of examples of a proper context, and one example of an incorrect context.

Correct context

A custom tag, HTML, a variable in the URL.

<img src="//ab-testing/images/banner_{{abVersion}}.png">

A custom tag, HTML, a variable not in the URL.

<div class="layout-{{abVersion}}">... some content here ...</div>

A custom tag, JavaScript, a variable in the string.

<script type="text/javascript"><br />
    (function (d) {<br />
        setTimeout(function () {<br />
            var f = d.getElementsByTagName('script')[0], s = d.createElement('script'); s.type = 'text/javascript';<br />
            s.async = true; s.src = '//example.com/{{ customerID }}/{{ siteToken }}.js'; f.parentNode.insertBefore(s, f);<br />
        }, 1);<br />
    })(document);<br />
</script>

Note: You may wonder why a variable in a string example is not a mixed context. That is because we are in a JavaScript context all the time. We build a script tag only with JavaScript, we do not output a ready HTML.

A custom tag, JavaScript, a variable not in the string.

<script type="text/javascript"><br />
    var _paq = _paq || [];<br />
    _paq.push(['setCustomUrl', {{ url }}]);<br />
    _paq.push(['setDocumentTitle', {{ title }}]);<br />
    _paq.push(['trackPageView']);<br />
</script>

Incorrect context

A custom tag, mixed context.

An example of a mixed context would be when in one script there is another script dynamically generated with src attribute and injected with document.write.

<script type="text/javascript"><br />
    document.write(decodeURI('%3Cscript%20src="' +<br />
        (document.location.protocol === 'https:' ?<br />
            'https://example.com/{{ partition }}/path/{{ guid }}.js' :<br />
            'http://example.com/{{ partition }}/path/{{ guid }}.js') + '"%20type="text/javascript"%3E%3C/script%3E'));<br />
</script>

As you can see both variables — partition and guid — are used in a JavaScript code, but in fact they are part of the URL of the HTML tag script. Additionally, everything is expected to be URI encoded. This will work as long as variables contain only letters and numbers.

If we were to fix this code, it would look like this:

<script type="text/javascript"><br />
    var partition = encodeURI(encodeURI('{{ partition }}'));<br />
    var guid = encodeURI(encodeURI('{{ guid }}'));</p>
<p>    document.write(decodeURI('%3Cscript%20src="' +<br />
        (document.location.protocol === 'https:' ?<br />
            'https://example.com/' + partition + '/path/' + guid + '.js' :<br />
            'http://example.com/' + partition + '/path/' + guid + '.js') + '"%20type="text/javascript"%3E%3C/script%3E'));<br />
</script>

What we have done here is we double encoded variables. That is because the whole script is passed via decodeURI function but we need URI encoded string to pass it safely to scripts URL.

    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