Macros

Macros are name-value pairs for which the value is populated during runtime. For example, the pre-defined macro named “url” has been defined such that its value is the current page URL.

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

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 “Fire when” rule:

Transaction Amount greater than $100

Since the macro Transaction Amount doesn’t exist, you’d need to define it. You’d tell Google Tag Manager to look for the value of Transaction Amount in, for example, a JavaScript variable transactionAmt.

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

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

Macro Types (Web)

  • Constant String: The value is set to the string you provide. Since this string will always be the same, and is simply the string that you provide here, the Constant String macro type is limited in usefulness. However, if you want to set a standard company name across your site, for example, you could define it as a Constant String type macro. This would allow you to easily update the string in Google Tag Manager and see it reflected across all the tags that use this macro.

  • 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 macro type, below), and it's not visible in the DOM (see DOM macro types, below), it's possible that the value can be retrieved from a JavaScript variable. Use this macro type if you can find the value you're looking for in the source of the page in the form of a JavaScript variable.

  • 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}}}.
    If your IT team has implemented a data layer as recommended in the developer documentation, all your data should be accessible via the Data Layer macro type. A data layer is an object that contains all of the information that you want to pass to Google Tag Manager (or the tags deployed therein). Instead of referencing variables, transaction information, page categories, and other important signals scattered throughout your page, Google Tag Manager is designed to easily reference information that you put in this data layer. Your IT team can provide you with the data names they have set up. The IT team can also pre-populate the macro list with data names from which you can choose.

    You can provide a Default Value to be used if the data layer value is not present on the page. For example, if the macro retrieves the current value of goods in a shopping cart, you can provide a default value to be used in the event that the shopping cart is empty.

  • DOM Text: The value is set to that of the element ID that you specify from the Document Object Model. (The Document Object Model (DOM) contains all the HTML elements on the page.)

    If the value you're looking for was not set up in the data layer (see Data Layer macro type, above), it's possible that the value can be retrieved from the Document Object Model of the page. Use this macro type if you can find the value you're looking for in the DOM.

  • DOM Attribute: The value is set to that of the element ID:attribute you specify from the Document Object Model. (The Document Object Model (DOM) contains all the HTML elements on the page.)

    If the value you're looking for was not set up in the data layer (see Data Layer macro type, above), it's possible that the value can be retrieved from the Document Object Model of the page. Use this macro type if you can find the value you're looking for in the DOM.

  • URL: The value is set to the current URL. By default, the URL macro will be be the whole URL, but you can also choose subcomponents of the URL to set as a macro. The URL components you can choose from are: Protocol, Hostname, Port, Path, Query, and Fragment.

  • Custom Event: The value is set to "eventNameXYZ" when the following code on your website is executed: dataLayer.push({'event':'eventNameXYZ'})
    This macro type should only be used when creating rules; do not create a new macro of this type.

  • 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. This macro type should only be used when creating rules; do not create a new macro of this type.

  • 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.

  • 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 macro called "lowerUrl" that operates on the predefined {{url}} macro:
    function () {
      return {{url}}.toLowerCase();
    }

  • Lookup Table: The value is set according to the instructions in the lookup table. The lookup table contains two columns:

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

    The Lookup Table type allows you to create a macro for which the value varies according to the value in another macro. 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 macro 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.

Macros for Event Tracking

  • element: For use in custom JavaScript macros and custom HTML tags. The value is always populated by an Event Listener, otherwise it is undefined. The value is the DOM element that triggered the event. For example: {{element}}.parentNode.id can be used in a rule or a tag to get the ID of the element's parent.

    This macro is only set when an Event Listener tag is fired. However, once fired, you can continue to use it (i.e. not only in a tag fired by the Event Listener). This can allow you to determine the last element clicked.

  • element classes: The value is always populated by an Event Listener, otherwise it is undefined. The value is the 'class' attribute of the DOM element that triggered the event. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

  • element id: The value is always populated by an Event Listener, otherwise it is undefined. The value is the 'id' attribute of the DOM element that triggered the event. For example, a click on the link <a href="http://www.google.com" id="google">Google</a> would result in an element id value of google. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

  • element target: The value is always populated by an Event Listener, otherwise it is undefined. The value is the 'target' attribute of the DOM element that triggered the event. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

  • element url: The value is always populated by an Event Listener, otherwise it is undefined. The value is the 'href' or 'action' attribute of the DOM element that triggered the event, depending on the type of element. For example, a click on the link <a href="http://www.google.com">Google</a> would result in an element url value of http://www.google.com. Note that checking the value only works in a rule that's used by the tag that fires in response to the listener. Read Google Analytics Events for examples.

Macro Types (Mobile)

  • Application Name: The value is set to the currently running application. A predefined macro of this type is provided in mobile app containers; you don't need to define a new macro of this type.

  • Application Version: The value is set to the version of the currently running application. A predefined macro of this type is provided in mobile app containers; you don't need to define a new macro of this type.

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

  • 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 predefined macro of this type is provided in mobile app containers; you don't need to define a new macro of this type.

  • 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).

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

  • Operating System Version: The value is set to the version of the operating system in which the application is installed.

  • Platform: The value is set to the platform of the currently running application (one of "Android" or "iOS"). A predefined macro of this type is provided in mobile app containers; you don't need to define a new macro of this type.

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

  • 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 predefined macro of this type is provided in mobile app containers; you don't need to define a new macro of this type.

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

  • Value Collection: This macro 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" macro 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 macro 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 macro has rules associated with it. For configuration values that apply to all instances and versions of your app, set the enabling rule to the predefined Always. Refer to the developer documentation (Android or iOS) for details on how to use the Value Collection macro.