GTM Variables Reference 📚

Built-In Variables Reference

You can enable each under the built-in variable configuration panel, accessible from a button in the container variables section. Disabling any built-variable requires that you remove any tags, other variables or triggers referencing said {{variable}}. Here is a brief description and use case for each of the standard variables accessible via Google Tag Manager (GTM).

• Click Classes references the clicked HTML tags class attribute, parsed for Hyper-Text Markup Language (HTML) entities with no inherent cascading style sheet (CSS) validation

  • Useful when setting conditions for Click triggers, your clicked element matches a specific class or combination

  • To match a valid CSS rule use this variable with the appropriate "matches CSS selector" as a trigger condition.

• Click Element returns the JavaScript (JS) object complete with all parameters when referenced within a custom variable or custom Hyper-Text Markup Language (HTML) tag, else this variable returns a string representation of the object type

  • Useful when interrogating the Document Object Model (DOM) for JS properties of the clicked object, or confirming the tag type when making a string comparison.

• Click ID references the clicked HTML tags id attribute, id attributes are used by pages are unique identifiers for elements on the Document Object Model (DOM). Sometimes also used for bookmarking with the Uniform Resource Locator (URI) hash fragment

  • Useful when filtering trigger conditions to fire only when a unique element on your webpage is engaged with

• Click Target returns the target attribute of the clicked element

  • Useful when detecting a hyperlink opening in a new window or in the same window with the _blank directive

• Click Text returns the parsed and trimmed inner HTML of the clicked element, parsing includes all  Hyper-Text Markup Language (HTML) tags contained within clicked element

  • Careful when using this variable to fire events; A/B tests, browser extensions and translators can cause unpredictable results when querying this variable

  • We suggest using Click DOM Path or Click ID or Parent ID to identify specific elements rather than contextual matching user visible content with your tags

  • WARNING: passing this variable back to your analytics platform may inadvertently leak Personally Identifiable Information (PII) to a 3rd party in potential breach the privacy policy of your website

  • For these reasons above we highly recommend Disabling the Click Text variable to pre-empt any possibility of this occurring

• Click URL returns the URL encoded web address of the clicked hyperlink HREF attribute, essentially the destination path of the clicked link

  • Useful for detecting internal or outbound link destinations, catching links that exit the current page using Page Hostname does not match {{hostname}} condition

  • Can also be used to identify clicks by the  filename extension (MIME types), subfolders or subdomains or vanity URLs

• Form Classes references the bubbled (or parent) form containers class attribute, parsed for Hyper-Text Markup Language (HTML) entities with no inherent Cascading Style Sheet (CSS) validation

  • To match your form condition a valid CSS rule use the "matches CSS selector" operator when setting up triggers

• Form Element returns the bubbled forms JavaScript (JS) object complete with all parameters

  • Useful when interrogating the forms Document Object Model (DOM) for JS properties of the clicked objects container form

• Form ID references the bubbled parent form of the clicked elements id attribute, id attributes are used by pages and are unique identifiers for elements on the Document Object Model (DOM). 

  • Useful when filtering trigger conditions to fire only when a unique element on your webpage is engaged with

• Form Target returns the target attribute of the bubbled parent form container

  • Useful when detecting a form submission opening in a new window or in the same window with the _blank directive

• Form Text returns the parsed and trimmed inner HTML of the bubbled form container, parsing includes all Hyper-Text Markup Language (HTML) tags contained within the form

  • Be careful when using this variable to fire events; A/B tests, browser extensions and inline translators can cause unpredictable results when querying this variable

  • WARNING: passing this variable back to your analytics platform may inadvertently leak Personally Identifiable Information (PII) to a 3rd party in potential breach the privacy policy of your website

• Form URL returns the URL encoded web address of the forms action attribute, essentially this is the destination path the browser will GET/POST and navigate the user once submitted

  • Useful for detecting the (usually internal) destinations, like a thank you page

• Error Message returns the complete error string text posted to the browser console, these can be triggered by the browsers Just in Time (JIT) compiler or by a console error or assert function executed within the websites codebase

  • Useful when detecting ALL or only some errors based on various conditions and filters types

  • We recommend you review your websites codebase to ensure console error messages don't contain any variables or messages that might not adhere to your websites privacy policy

  • If you execute a large amount of 3rd party JavaScript (JS) we recommend you keep this variable disabled.

• Error URL returns the resource on-which the JavaScript (JS) error function was called or where the Just in Time (JIT) compiler detected the syntax error

  • Usually it's a reference to either a 3rd party hosted or first party JavaScript (JS) file

  • Could also refer to your pages Document Object Model (DOM) if the JS is either 

    • in the Head (Render Blocking or Preload)

    • inline on an HTML element

    • injected (like Custom HTML tag)

• Error Line returns the line number and position number - separated by a colon - on-which the JavaScript (JS) error function was called or where the Just in Time (JIT) compiler detected the syntax error

  • This directly relates to the Error URL and helps with debugging

  • In some cases it might be easier to de-minify your JavaScript (JS) libraries if a persistent bug is causing issues on your website

• Page URL returns the full website address as an Uniform Resource Locator (URL,) meaning it includes protocol, subdomains, Top Level Domain (TLD) name, and any subsequent URL paths, parameters and bookmarks (fragments.) 

  • The Page URL is a type of Uniform Resource Indicator (URI) useful for passing resolvable addresses between computer networks and is a foundation of the internet

  • Useful when you need to pass the full website address to another platform

  • Essential if you have a container operating across multiple domains or subdomains and would like to set up complex conditional RegEx queries

  • See Page Path for a shorter hostname and protocol agnostic variable

• Page Path returns the portion of the website address after the Top Level Domain (TLD) or hostname value, any subsequent URL paths, parameters and bookmarks (fragments) are included in the path

  • Useful when querying page specific combinations for trigger conditions, especially where the query is both protocol and hostname agnostic

  • Some Data Management Platforms (DMP) like Google Analytics (GA) prefer passing the page path variable separately because the protocol and host names have their own dimensional references

  • See Page URL for a Uniform Resource Indicator (URI) inclusive of protocols and host names

• Page Hostname returns the portion of the website address after the protocol and before the page path, Hostnames include Top Level Domain (TLD) and any subdomains

  • Useful when passing or setting trigger conditions based on the domain or subdomain name, isolating triggers to match only valid hosting environments

  • Especially important if your container is shared across more than one domain or subdomains

• Referrer returns the full referring page website address, this can be either an internal link or an inbound visitor from a different website

  • Useful for collecting, filtering or detecting the source page of an existing or new visitors hit

  • If this variable is undefined then the visitor either

    • started a new session by typing an web address in the browser

    • opened a link from an independent email client program

    • chose to open a bookmarked link from your website

    • followed an external link with a noreferrer relationship attribute

  • This page referral information is included as standard in the Hypertext Transfer Protocol (HTTP) request for every webpage send by all popular browsers

• Random Number returns a number ranging from zero to 999,999,999 or one to one billion if you add one to the output value

  • Random numerical values have a multitude of uses including

    • as a factor/seed in on-page variations

    • substitute unique identifiers for multiple matching on-page events

    • generating custom pseudo user ID or experiment IDs for A/B tests

    • as cache busters for server requests

  • Generated by the browsers Random Number Generator (RNG) and normalised by Google Tag Manager (GTM)

  • Is not guaranteed to produce unbiased numbers, depending on browser configuration and hardware (HW) support

• Event returns the given value of any pushed object where an 'event' key is present, usually indicating the current or most recent event name to have triggered

  • Used almost exclusively in the Custom Event trigger where the returned string can be matched against an exact or RegEx matching in order to execute a tag

• Container Version returns the current incrementally counted version number of the published container or a string value of 'QUICK_PREVIEW' is returned when preview window is active

  • Useful when detecting if the preview window (or Debug Mode) is active within Custom JavaScript (CJS) variables

  • Keep in mind this variable data type remains a string in spite of its value representing an integer 99% the time

  • Recommend passing this variable to your data management platform for bug testing and version fallbacks if ever this is required

• Debug Mode returns true when preview window is active,

  • Useful when detecting if the preview window (or Debug Mode) is active within Custom HTML tag and Custom JavaScript (CJS) variables

  • We prefer using the container version as this variable can help too when backdating issues in your telemetry

• Container ID returns the Google Tag Manager (GTM) container identifier

  • This code is used to load the container in the  Hyper-Text Markup Language (HTML) head

  • Without loading the container via this ID means that no tags can be executed

• HTML ID references the parent <HTML> container id attribute

  • Useful when passing success and failure signals from Custom HTML tags using the onHtmlFailure() and onHtmlSuccess() methods

  • Practical when loading tags sequentially

• Video Variables return various values from the most recently played YouTube or Vimeo video player or currently being played on the webpage, these built-in variables can be activated and deactivated depending on your needs

  • Video Provider is useful for determining which platform the video is being streamed from, usually YouTube

  • Video Status is useful to determine if the video is playing or has been paused or stopped

  • Video URL is used to return the full website address or Uniform Resource Locator (URL) of the video currently occupying the in-page player viewpoint

  • Video Title is useful when passing the videos full name or YouTube title back to your Data Management Platform (DMP)

  • Video Duration us useful for determining how long a particular videos length may be, returned in seconds, this can be divided by 60 to represent minutes

  • Video Percent returns the percentage (%) value of the video consumed as an integer, this does take into consideration user initiated seek actions

  • Video Current Time returns the current video seek bar counter in seconds

  • Video Visible is useful for detecting how much of the video player frame occupies the visitors viewport

• Scroll Depth Threshold returns an integer percentage (%) that the current viewport has progressed through the document body element within the current web-pages Document Object Model (DOM)

  • Useful detecting both horizontal and commonly vertical scroll depth consumed on the current webpage, returns the last threshold reached

  • Scroll Direction returns the last axis on which a scroll event was detected, vertical or horizontal for the X and Y axis respective

  • Scroll Depth Units returns the threshold unit of measurement as percent or pixels, representing either a percentage or pixel depth measure of scroll distance event fired

  • Containers, iframes and slider style elements with overflow selectors set to scroll are not measured by this variable, only scrolling in the page body element is reported

  • WARNING: Progressive Web Apps (PWA,) Parallax Scrolling pages and webpages with highly dynamic content might cause this variable to trigger depths prematurely before any scroll has actually taken place, see Scrolling Thresholds for more

• History Source and Fragments are used to capture the virtual page changes pushed to the browser page view history

  • Useful when detecting virtual pageviews, progression or state changes controlled by Client-Side Rendering (CSR) systems or Progressive Web Apps (PWA)

  • New History Fragment and Source returns the latest (or currently viewed) navigation fragment, which is the string path from the webpages address bar following the hash symbol

  • Old History Fragment and Source returns the previous navigation fragment -- if one existed, which is the string path from the last virtual paged Uniform Resource Locator (URL) following the hash

  • Browser history is the same data storage and navigation mechanism used to control the back and forward buttons on your web-browsers native window interface

  • Some internet browsers can create pop-out/up windows that lack the navigation buttons and other window dressing, but the history storage still exists and operates on these pages in-spite of the visual changes

• Percent Visible is related to the last Element Visibility trigger to fire within this container, returns the percentage of the matching element to be occupied within the browser viewport

  • Useful when setting conditions or passing viewport placement telemetry, relative to matching element selectors, value is returned as an integer from 1 (just come into view) to 100 (in full view)

  • Using a selector ID type to bind the visibility lookup to an element ID attribute would only ever match a single element, making this a predictable variable, however...

  • WARNING: When using a Cascading Style Sheet (CSS) Selector, this variable will bind to all elements matching this CSS rule, causing the variable to align with each trigger only when it fires

  • Calling this variable from other triggers, tags or variables (not the one that initiated it) means this variable would return the last matching eligible percentage visible in the order the elements relative position on the Document Object Model (DOM) hierarchy

  • On-Screen Duration returns the element visibility required in-order to successfully trigger the event, this is an optional selection for each trigger