Search
Clear search
Close search
Google apps
Main menu
true

Variables

Variables are name-value pairs for which the value is populated during runtime. For example, the predefined variable named "url" has been defined such that its value is the current page URL.

Variables are used in triggers and in tags. In triggers, they are used to define filters that specify when a particular should be executed (e.g.: to execute a pageview trigger when the url variable is “example.com/index.html”). In tags, variables are used to capture dynamic values (e.g.: passing the transaction value and products purchased to a conversion tracking tag).

Google Tag Manager provides a set of predefined variables in each Web or Mobile App container that you create. With these variables, you’re able to create the most commonly needed tags and triggers. However, you can create additional variables to suit your specific requirements.

In this article:

Note: Built-in variables are a special category of variables that are pre-configured by Google Tag Manager. They replace the variables that used to be generated when creating a new container. Once a selection of built-in variables have been enabled, you can use them just like any other type of variable. Built-in variables cover many of the basic and common variables such as page URL, referrer, click ID, random numbers, or events.

Learn more about built-in variables.

Web Example

Let’s say that you want to fire a GDN Remarketing tag whenever a visitor spends more than $100 on your site. To implement this, you’d create a pageview trigger and add this as trigger condition:

Transaction Amount greater than $100

Since the variable “Transaction Amount” doesn’t exist, you would need to define it. You would tell Google Tag Manager to look for the value of Transaction Amount in a JavaScript variable transactionAmt (assuming this Javascript variable is present on the purchase confirmation page of your website).

During runtime, Google Tag Manager would get the value of Transaction Amount from the specified JavaScript variable. Then, the above trigger would evaluate whether the value is greater than $100.

In addition to using Transaction Amount in a trigger, you could also use it to pass the transaction amount to any conversion tracking tag, such as a DoubleClick Floodlight tag, thereby making it possible for DoubleClick reports to display transaction revenue.

Variable Types for Web

1st party cookie: The value is set to the 1st party cookie with the matching name for domain that the user is currently on. In the case that a cookie with same name is deployed on multiple paths or multiple levels of domain within the same domain, the first value will be chosen. This is the same is if you had called document.cookie from within a page and chosen the first result.

Container Version Number: When the container is in preview mode, the container version variable returns the container's preview version number. Otherwise, this variable returns the container's live version number.

Custom JavaScript: The value is set to the result of a JavaScript function. The JavaScript must take the form of an anonymous function that returns a value. For example, you could write a custom JavaScript variable called "lowerUrl" that operates on the predefined {{url}} variable:

function () {
  return {{url}}.toLowerCase();
}

Data Layer: The value is set to ‘value’ when the following code on your website is executed: dataLayer.push({'Data Layer Name': 'value'})

You can specify, in Google Tag Manager, how dots ('.') are to be interpreted in the data layer variable name:

  • Version 1: allow dots in key names. For example, for dataLayer.push('a.b.c': 'value'), interpret the name of the key as "a.b.c" (i.e. {'a.b.c': 'value'}).
  • Version 2: interpret dots as nested values. For example, interpret dataLayer.push({'a.b.c': 'value'}) as three nested levels: {a: {b: {c: 'value'}}}. This allows you to read nested values; you could set the variable name to 'a.b' and it would return the object {c: 'value'} (according to standard JavaScript rules). Nested pushing also allows you to directly edit nested values, so executing:
    dataLayer.push({'a.b.c': 'value'});
    dataLayer.push({'a.b.d': 4});

    on your page would result in a dataLayer that looks like {a: {b: {c: 'value', d: 4}}}.

Debug Mode: The value is set to true if the container is being viewed in debug mode.

DOM Element: The value is set to the text of the DOM (Document Object Model) element or the value of the specified DOM element attribute. If the value you're looking for was not set up in the data layer (see Data Layer variable type, above), it's possible that the value can be retrieved from the DOM. Use this variable type if you can find the value you're looking for in the DOM by entering the value of the element's ID attribute.

If the optional attribute name is set, the variable's value will return the value specified from that attribute (e.g. data-food="cupcakes"); otherwise, the variable's value will be the text within the DOM element.

Element Visibility: The value is set based on the visible state of the specified DOM element. Unlike the Element Visibility trigger, a single Element Visibility variable can only report the visibility of a single element. Choose whether to select an element based on the element ID or a CSS Selector. If multiple elements are matched by a specified CSS Selector, the first matched element will be used.

You can choose the output type for this variable:

  • True / False: A boolean value indicating whether the selected element is visible when the variable is referenced. 
  • Percent: A numeric value (0-100) indicating how much of the selected element is visible on screen when the variable is referenced.

If you select “True / False” as the output type, you can also specify a Minimum Percent Visible to indicate how much of the selected element must be visible on screen for the variable to return true.

HTTP Referrer: The value is set to the HTTP referrer, the previous page that the person visited. For example, if a person navigates to one of your product pages from the home page, the referrer will be the home page. An instance of this variable type is automatically created by Google Tag Manager but you can create additional instances if you would like to have expose different part(s) of the referrer URL.

JavaScript Variable: The value is set to that of the global variable you specify. If the value you're looking for was not set up in the data layer (see Data Layer variable type), and it's not visible in the DOM (see DOM Element variable types), it's possible that the value can be retrieved from a JavaScript variable. Use this variable type if you can find the value you're looking for in the source of the page in the form of a JavaScript variable.

Lookup Table: The value is set according to the instructions in the lookup table. The lookup table contains two columns (Table empty to illustrate how data is used later):

When [select variable] equals Set [this variable] to
   

The Lookup Table type allows you to create a variable for which the value varies according to the value in another variable. This is useful if your website is set up in such a way that the appropriate value (for example, a conversion tracking ID) can be mapped to the URL or another aspect of the page. In this example, a variable named Conversion ID is being created. If the URL is “/thanks/buy1.html”, the value is set to “12345”; if the URL is “thanks/buy2.html”, the value is set to “34567”. There is no limit to the number of rows in the lookup table. Fields are case sensitive.

When {{url}} equals Set {{Conversion ID}} to
http://example.com/thanks/buy1.html 12345
http://example.com/thanks/buy2.html 34567
http://example.com/thanks/buy3.html 56789

Random number: The value is set to a random number between 0 and 2147483647.

RegEx Table: A RegEx Table variable works similarly to Lookup Tables, with the addition of being able to run regular expression patterns for the items you want to match.

To illustrate how this works, consider the following RegEx Table settings:

Pattern Output
.*/page[1-3]\.html.* foo
.*/page[4-6]\.html.* bar
.*/page[7-9]\.html.* baz

The output value of the variable will be as follows:

http://example.com/page1.html foo
http://www.example.com/page1.html foo
http://example.com/page2.html#detail foo
http://example.com/page5.html bar
http://example.com/page5.html?status=new bar
http://example.com/page6.html bar
https://example.com/page9.html baz

RegEx Table lookups run from the top of the list to the bottom. When a match is found, the corresponding output value is returned.

Select Set Default Value to set an output value for when a match is not found.

By default, patterns must match the full input string and are case insensitive. This behavior can be adjusted in Advanced Settings:

  • Ignore Case: Patterns will match upper and lower case matches without having to build this into the regular expression explicitly.

  • Full Matches Only: If enabled, patterns must match entire input. This is equivalent to having start (^) and end ($) anchors implicitly around your pattern. If disabled, patterns will match when they are found anywhere in the input. Disabling this option may cause unexpected behavior with "Capture Groups and Replace Functionality".

  • Capture Groups and Replace Functionality: If enabled, you can use dollar-sign replacement syntax to include portions of the input (e.g. from capturing groups in the matched pattern) within the output. For example, if the matched regular expression is /(news)/page(2)\.html, you can use $1 to reference the first capture group ("news") and $2 to reference the second capture group ("2").

    Using "Capture Groups and Replace Functionality" with "Full Matches Only" disabled may result in unexpected behavior (i.e. returning the entire input value with the matched portion replaced).

URL: This type of variable allows you to parse and expose URL components. Google Tag Manager automatically creates 3 instances of this variable type (full url, hostname and path). You can create additional instances to expose different parts of the URL. The URL components you can choose from are: Protocol, Hostname, Port, Path, Query, and Fragment. The input value set for variables of this type is the url of the current page the user is on (retrieved from document.location). By adjusting the URL Source setting, it is possible to tell Google Tag Manager to use another variable as the source of the url value.

Variable Types for Mobile Apps

Advertiser Tracking Enabled: For Android, the variable returns true if ad tracking is enabled, or false if the user has opted out of interest-based ads. Learn more in the Android Developer Center. SDK versions prior to v4 will always return false. For iOS versions 6 and greater, the value is set to the advertisingTrackingEnabled property. Otherwise, the value is set to true. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

App ID: The value is set to the package name (Android) or bundle ID (iOS). A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

App Name: The value is set to the name of the currently running application. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

App Version Code: The value is set to the version of the currently running application. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Constant: The value is set to the string you provide.

Container ID: The value is the container's public ID (e.g. GTM-ABC42). A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Container Version Number: When the container is in preview mode, this variable's value is the container's preview version number. Otherwise, this variable's value is the container's live version number. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Device ID: For Android, the value is set to the device ID. For legacy iOS containers, the value is set to '' (the empty string). This variable is not available in Firebase (iOS) containers. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Device Name: The value is set to the device name of the currently running application (e.g., "Samsung Android", "Android SDK built for x86"). A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Event Name: The value is set to "eventNameXYZ" when the following code in your app is executed:

Android:
FirebaseAnalytics.getInstance(mContext).logEvent("eventNameXYZ", null);

iOS:
[FIRAnalytics logEventWithName:@"eventNameXYZ" parameters:parameters];

A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Event Parameter: The value is set to the value of a logged Firebase Analytics event parameter for the given key.

Firebase User Property: The value is set to the Firebase Analytics user property value for the given key.

Function Call: The value is set to the return value of a call to a pre-registered function. To learn more, refer to the SDK documentation (Android or iOS).

ID for Advertising: For Android, the value is set to the Advertising ID. More info in the Android Developer Center. SDK versions prior to v4 will always return '' (the empty string). For iOS versions 6 and greater, the value is set to the identifier for advertising (IDFA). Otherwise, the value is set to '' (the empty string).

Language: The value is set to the two letter language code representing the user-set device language. A predefined variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Lookup Table: The value is set according to the instructions in the lookup table. The lookup table contains two columns (Table empty to illustrate how data is used later):

When [select variable] equals Set [this variable] to
   

The Lookup Table type allows you to create a variable for which the value varies according to the value in another variable. This is useful if your app is set up in such a way that the appropriate value (for example, a conversion tracking ID) can be mapped to the App Version Code or another aspect of the app. In this example, a variable named Conversion ID is being created. If the App Version Code is 1.0, the value is set to “12345”; if the App Version Code is 1.1, the value is set to “34567”. There is no limit to the number of rows in the lookup table. Fields are case sensitive.

When {{App Version Code}} equals Set {{Conversion ID}} to
1.0 12345
1.1 34567
1.2 56789

Operating System Version: The value is set to the version of the operating system in which the application is installed. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Platform: The value is set to the platform of the currently running application (e.g., "Android"). A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Random Number: The value is set to a random number between 0 and 2147483647. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Screen Resolution: The value is set to the screen resolution of the device of the currently running application. The format is '<width>x<height>', e.g. '1024x768'. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

SDK Version: The value is set to the SDK version of the operating system in which the application is installed. A built-in variable of this type is provided in mobile app containers; you don't need to define a new variable of this type.

Legacy Value Collections

Value Collection (legacy containers only): This variable contains a set of key-value pairs expressed in JSON format. You use a Value Collection to set the configuration values for your application. For a race driving game app, for example, you might define an "App settings" variable of type Value Collection with the following:

{
  "max-fuel": 200,
  "starting-fuel": 100,
  "fuel-burn-rate": 20
}

Your mobile app can retrieve a value in the variable by providing the key. For example:

public class MainActivity {

  // Add your public container ID.
  private static final String CONTAINER_ID = "XXX-YYY";
  
  // Container configuration value keys, used later
  // for retrieving values.
  private static final String MAX_FUEL_KEY = "max-fuel";
  private static final String INIT_FUEL_KEY = "init-fuel";
  private static final String FUEL_BURN_KEY = "fuel-burn-rate";

  // Rest of your onCreate code.
  }
}

/*
* Method to update game configuration values using a
* Google Tag Manager container.
*/
public void updateConfigurationFromContainer(Container container) {

  // Get reference to the container.
  Container container = mFutureContainer.get();

  // Update game settings using Container 
  // configuration value keys.
  maxFuel = mContainer.getDoubleValue(MAX_FUEL_KEY);
  startingFuel = mContainer.getDoubleValue(INIT_FUEL_KEY);
  burnRate = mContainer.getDoubleValue(FUEL_BURN_KEY);
}

A Value Collection variable has triggers associated with it. For configuration values that apply to all instances and versions of your app, set the enabling trigger to the predefined Always. Refer to the developer documentation (Android or iOS) for details on how to use the Value Collection variable. 

Was this article helpful?
How can we improve it?