I\u2019ve written a new Variable Guide for Google Tag Manager<\/a>, which covers the new GTM UI. This guide is for the old UI.<\/em><\/p>\n You might be vaguely familiar with macros if you\u2019ve ever used a computer. Basically, whenever you perform a complicated task with a simple gesture, or reuse complex code with a simple input mechanism, you\u2019re using macros. Think keyboard shortcuts.<\/p>\n In Google Tag Manager<\/a>, this is the essence of macros. You can do away with a lot of complexity by resorting to macros, especially if you ever find that you need the same piece of code or the same operation over and over again.<\/p>\n This guide will first take a cursory look at what macros really are, before going through the (current) list of available macros. I\u2019ll add short examples and use cases for each, but there\u2019s a whole lot more to be found online.<\/p>\n \n \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n <\/span><\/p>\n In Google Tag Manager, a macro is a construct that you can set up in the UI. However, it\u2019s not a tag in the sense that it would be something you\u2019d tag<\/em> your page with. Rather, macros are turned into a function of the google_tag_manager<\/em> object (more on this later), and they return a value when called.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n So a macro is, in essence, a placeholder for some value that you might need in your tags. Most common uses for macros would be to:<\/p>\n Retrieve a constant string (e.g. your tracking code)<\/p>\n<\/li>\n Retrieve a variable string (e.g. the href<\/strong> attribute of a clicked element)<\/p>\n<\/li>\n Retrieve the result of some simple function (e.g. the date and time of the current visit)<\/p>\n<\/li>\n<\/ul>\n Macros are thus used to call for and to retrieve certain values. You can surely see how they facilitate your day-to-day GTM use, can\u2019t you? It\u2019s much easier to just refer to a macro name rather than having to write the value-retrieving function over and over again.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Without macros, whenever you rewrite your hard-coded functions or variables, you have to remember to change them wherever they were used. It\u2019s much easier to just have a macro refer to the original location.<\/p>\n DISCLAIMER: Note that the following analysis is my own and only for illustrative purposes. Don’t attempt to use the DOM functions uncovered here in your own code, since they are liable to change without notice. Use macros only via the GTM UI using the syntax required by the tool.<\/p><\/blockquote>\n Well my skills at reverse engineering minified JavaScript code are pretty sparse, but you can uncover a lot just by going through the DOM (Document Object Model) tree of a page where macros are active. You can do this by using a JavaScript console in your browser\u2019s developer tools. Just type window<\/strong> and click enter.<\/p>\n For example, if you go through the DOM, you\u2019ll find an object called google_tag_manager<\/strong>:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Here you can see the google_tag_manager array and its contents. There\u2019s an index for your container ID (GTM-XXXX), under which you\u2019ll find the macro function. The function is actually defined in gtm.js, which you load in the GTM container snippet.<\/p>\n The macro<\/strong> function accepts a single parameter and returns something else.<\/p>\n It appears that the parameter is a numeral value which refers to a certain macro that you\u2019ve set up in GTM. I didn\u2019t find any way to actually identify which number returns which macro value, but just by testing you can find a lot of stuff. For example, I have a macro which stores the number of images on the page. Twiddling around with the macro function I finally found the correct index:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n So as you can see, when you refer to a macro in your tag setup, e.g. {{number_of_images}}, it actually translates to a JavaScript function call that returns the value.<\/p>\n This is also the reason why your macros don\u2019t accept parameters. The macro itself is a function call which only takes the index number of the macro as its parameter. Runtime evaluation is done on the spot with only elements found in the Document Object Model to work with.<\/p>\n This is why you\u2019ll see undefined<\/em> for those indices which expect a value in the data layer that hasn\u2019t been pushed yet. As soon as the value is pushed into the data layer, you\u2019ll find that the macro index returns the appropriate value.<\/p>\n To use a macro, you refer to it in GTM with its name between two sets of curly brackets:<\/p>\n {{macro name}}<\/strong><\/p>\n Note that this is case-sensitive, so {{macro name}} and {{Macro name}} refer to different things.<\/p>\n You can use macros in any GTM fields which accept a text string, e.g.:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n On top of that (and this is really cool), you can refer to macros in your custom HTML tags:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Here, I check whether or not the clicked link href<\/strong> contained the text \u201c.pdf\u201d. Since it\u2019s an auto-event macro<\/a> I\u2019m using, the macro won\u2019t return a proper value until the auto-event variable is pushed into the data layer. So upon page load the macro {{element url}} would return undefined<\/em>, but after I click a link, it would return the href attribute of the link. This means that in order for this tag to work like it should, I need a firing rule which prevents it from firing until after the auto-event variable is pushed into the data layer. Runtime evaluation, remember?<\/p>\n You can also, and this is really REALLY cool, refer to macros in other macros!<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n This returns the tag name of the first child of the clicked element.<\/p>\n There\u2019s a small point to make about using macros and JavaScript. You can only treat a macro as a JavaScript object in the context of a script<\/strong>. This means that you can freely access macro properties with dot notion, e.g. {{element}}.innerText<\/strong>, in Custom HTML tags and Custom JavaScript macros. However, this won\u2019t work in other GTM fields where you can use macros (e.g. Event Category), because these fields do not run JavaScript functions. So if you want to access a property of a macro in a tag field, for example, you will need to create a separate macro for this property<\/strong>.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n You\u2019ll also use macros a lot in your firing and blocking rules:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n This rule would fire only when visits are tracked to my GA debug account.<\/p>\n Here\u2019s the key takeaway:<\/p>\n Use a macro whenever you need to reuse a certain value or value-returning function.<\/strong><\/p>\n I won\u2019t add a separate section for when not<\/strong> to use a macro, but suffice to say, if you only need a certain value once or you have a function which you know won\u2019t be reused, don\u2019t bother creating a macro for it. Just hard-code it into your custom HTML tag or use the value directly in your tags. A macro is always, after all, another function call, which does increase the complexity of your code.<\/p>\n Rules are a bit different, since you must<\/strong> use macros in rules. You can\u2019t write an ad hoc function into your rule; you must have a macro which you evaluate on runtime.<\/p>\n Here, I\u2019ve listed all the different macro types you can create in Google Tag Manager (at the time of writing). I\u2019ve added a short description, and an example use case for each.<\/p>\n All macros need a name, which you refer to (case-sensitive) using two sets of curly brackets, e.g. {{macro name}}.<\/p>\n Also, you can give a default value<\/strong> to some of the macros. It\u2019s a good practice to use a default value, because you can use that as a blocking rule (e.g. {{macro}} equals \u201cdefault\u201d) in your tags, and you can avoid getting the pesky undefined<\/em> as a return value.<\/p>\n Note also that there\u2019s a difference between macro type<\/strong> and macro instance<\/strong>. Below, I list all the different macro types<\/em> you can use to create different macro instances<\/em>. You can have as many instances of a macro type as you want (as long as they have different names). Macro types are provided by GTM, and you can\u2019t edit or create new macro types.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n When you create a new container, you get the following pre-populated macro instances<\/strong>. Encased in brackets is the type of macro the pre-populated macro is an instance of:<\/p>\n element (Auto-Event Variable \/ Element)<\/p>\n<\/li>\n element classes (Auto-Event Variable \/ Element Classes)<\/p>\n<\/li>\n element id (Auto-Event Variable \/ Element ID)<\/p>\n<\/li>\n element target (Auto-Event Variable \/ Element Target)<\/p>\n<\/li>\n element url (Auto-Event Variable \/ Element URL)<\/p>\n<\/li>\n event (Custom Event)<\/p>\n<\/li>\n referrer (HTTP Referrer)<\/p>\n<\/li>\n url (URL \/ URL)<\/p>\n<\/li>\n url hostname (URL \/ Host Name)<\/p>\n<\/li>\n url path (URL \/ Path)<\/p>\n<\/li>\n<\/ul>\n So you might be a bit confused at first, since you have these pre-populated macros which are named the same as the macro types they are instances of. But you\u2019ll get the hang of it soon enough, don\u2019t worry.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n The 1st Party Cookie macro returns the value of the cookie whose name you indicate in the Cookie Name field. For example, if you set up a cookie named \u201cfront-page-visits\u201d which increases by one every time the visitor visits your front page, you can set up this macro to return the value (i.e. number of visits) every time the macro is used.<\/p>\n USE CASE<\/strong><\/p>\n Check my previous article on the session cookie<\/a> for a nice use case for this macro.<\/p>\n Basically this macro can be used to replace any code you used to have for retrieving cookie values.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n When you set up an event listener<\/a> using GTM, you can use the auto-event variable macros to return the value of various attributes of the element you were listening to.<\/p>\n You need to specify the variable type of the auto-event variable you want to use. Here are the different types.<\/p>\n Element<\/em>: This returns the element that was clicked. Note that the macro returns an object, not a string, so the best use of it is for traversing the DOM tree of the clicked element (e.g. {{Element}}.children[0].tagName<\/strong> returns the tag name of the first child of the clicked element).<\/p>\n Element classes<\/em>: This returns the class attribute of the element that was clicked. For example, if the element was Element ID<\/em>: This returns the ID attribute of the element that was clicked. For example, if the element was Element target<\/em>: This returns the target attribute of the element that was clicked. For example, if the element was Element text<\/em>: This returns the text content (if any) of the element that was clicked. It returns either the innerText or the textContent property (depending on what browser the visitor uses).<\/p>\n Element URL<\/em>: This returns the href (in e.g. links) or action (in e.g. forms) attribute of the clicked (or submitted) element. For example, if the element was History New URL Fragment<\/em>: The History<\/em> macros are populated by the History Listener. History New URL Fragment returns the URL fragment set in the current history state. You can use this to fire your tags (e.g. pageview) when a certain URL fragment is in the URL.<\/p>\n History Old URL Fragment<\/em>: Returns the URL fragment set in the previous history change event. For example, if you first navigate to #aboutus<\/strong> then to #contact<\/strong>, History New URL Fragment will return \u201caboutus\u201d and History Old URL Fragment will return \u201ccontact\u201d.<\/p>\n History New State<\/em>: History New State returns the state object stored in the current history entry (if any). You can access the properties of this object to set up your content and fire your dynamic tags. Note that it\u2019s an object<\/em> that is returned, so you can\u2019t use it directly in any GTM fields. You\u2019ll need to use some programming logic to access the properties of this object if you want to send them as strings with your tags.<\/p>\n History Old State<\/em>: The previous state stored in browser history (if any). You can use this to determine what the previous browser history state was, for example if navigation patterns determine the tags you want to fire.<\/p>\n USE CASE<\/strong><\/p>\n There\u2019s a million different things you can use auto-event variables for. The variables are most frequently used to refer to certain aspects of the element in event descriptions. You could, for example, add {{element url}} as the action of a GA event which measures link clicks on your different pages.<\/p>\n Check my tutorial on auto-event tracking<\/a> to see how the different auto-event variables can be used to improve your site measurement.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n This macro can be used to store a string you\u2019d use over and over again. In other words, it\u2019s a time-saver.<\/p>\n USE CASE<\/strong><\/p>\n Store your GA tracking code in this, so you don\u2019t have to remember it in every single tag. Just add the UA-XXXXXXX-X into the \u201cValue\u201d field, and name the macro \u201cGA Tracking Code\u201d or something similar. After that, whenever your tracking code is required (e.g. in tags), you can just use the macro {{GA Tracking Code}}.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n This returns your GTM container version number. If you\u2019re in the Preview mode (as you should be whenever you\u2019re testing), this returns the preview container version number.<\/p>\n USE CASE<\/strong><\/p>\n A nice way to use it is to output the version number into the console using console.log({{container version}});<\/strong> in your Custom HTML tag. This way you can always check the console if you\u2019re unsure which version you\u2019re currently running. It\u2019s a good way to debug your live implementation.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n This macro returns the data layer \u201cevent\u201d value of the last event that was pushed into the array. So if you\u2019ve just executed dataLayer.push({\u201cevent\u201d: \u201cmyEvent\u201d});<\/strong>, this macro will return \u201cmyEvent\u201d.<\/p>\n USE CASE<\/strong><\/p>\n This should be one of your most familiar macros. It comes with every container setup under the name {{event}}. There are about a zillion use cases for this, most notably in firing and blocking rules. For example, if you only want a tag to fire when the event \u201cfireNow\u201d has been pushed into the data layer, you can add the rule {{event}} equals fireNow<\/strong> to your tag. Then, as soon as you execute dataLayer.push({\u201cevent\u201d: \u201cfireNow\u201d});<\/strong> the event macro will be populated with the value \u201cfireNow\u201d and your firing rule will trigger.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n DESCRIPTION<\/strong><\/p>\n Use this macro to perform a simple JavaScript function using either ad hoc values or elements in the DOM tree. The JavaScript function has<\/strong> to be encased in a function structure, it has<\/strong> to return a value and it can\u2019t<\/strong> take parameters of its own.<\/p>\n USE CASE<\/strong><\/p>\n You could use it with auto-event tracking to return the value \u201cOutbound link\u201d for all outbound links and \u201cIn-site link\u201d for all in-site links. You can then use these as your Event Category in the event where you send information about the link that was clicked. The function would look like this:<\/p>\n See how I\u2019m referring to another macro within this macro? \ud83d\ude42 \u201cwww.my-domain.com\/\"<\/a> would naturally need to be replaced with your hostname.<\/p>\n Another neat trick is to use a Custom JavaScript macro to retrieve the file extension of the link that was clicked. You can use this to create more dynamic tags. Check out the tip on this Google+ post<\/a>.<\/p>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nWhat is a macro<\/h2>\n
![\"Macros](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macro-in-ui.jpg#ZgotmplZ\")
<\/p>\n\n
![\"An](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macro-example.jpg#ZgotmplZ\")
<\/p>\nTechnical details<\/h2>\n
![\"Google](\"https:\/\/www.simoahava.com\/images\/2014\/02\/google-tag-manager-macro.jpg#ZgotmplZ\")
<\/p>\n![\"Testing](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macro-test.jpg#ZgotmplZ\")
<\/p>\nHow to use macros<\/h2>\n
![\"Macros](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macros-in-fields.jpg#ZgotmplZ\")
<\/p>\n![\"Macro](\"https:\/\/www.simoahava.com\/images\/2014\/02\/custom-html-macro.jpg#ZgotmplZ\")
<\/p>\n![\"Macro](\"https:\/\/www.simoahava.com\/images\/2014\/02\/custom-javascript-macro.jpg#ZgotmplZ\")
<\/p>\n![\"Macro](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macro-in-fields.jpg#ZgotmplZ\")
<\/p>\n![\"Firing](\"https:\/\/www.simoahava.com\/images\/2014\/02\/fire-only-debug.jpg#ZgotmplZ\")
<\/p>\nThe different macro types in GTM<\/h2>\n
![\"Macro](\"https:\/\/www.simoahava.com\/images\/2014\/02\/macro-instance-type.jpg#ZgotmplZ\")
<\/p>\n\n
1. 1st Party Cookie<\/h3>\n
![\"1st](\"https:\/\/www.simoahava.com\/images\/2014\/02\/1st-party-cookie.jpg#ZgotmplZ\")
<\/p>\n2. Auto-Event Variable<\/h3>\n
![\"Auto-Event](\"https:\/\/www.simoahava.com\/images\/2014\/02\/auto-event-variable.jpg#ZgotmplZ\")
<\/p>\n<\/p>\n<\/code>, the macro would return \u201chome-link\u201d.<\/p>\n<\/code>, the macro would return \u201cblank\u201d.<\/p>\n3. Constant String<\/h3>\n
![\"GA](\"https:\/\/www.simoahava.com\/images\/2014\/02\/custom-string.jpg#ZgotmplZ\")
<\/p>\n4. Container Version Number<\/h3>\n
![\"Container](\"https:\/\/www.simoahava.com\/images\/2014\/02\/container-version-number.jpg#ZgotmplZ\")
<\/p>\n5. Custom Event<\/h3>\n
![\"Event](\"https:\/\/www.simoahava.com\/images\/2014\/02\/event.jpg#ZgotmplZ\")
<\/p>\n6. Custom JavaScript<\/h3>\n
<\/p>\nfunction<\/span>() {\n if<\/span>({{element url}}.indexOf(\"http:\/\/www.my-domain.com\"<\/span>) >= 0<\/span>) {\n return<\/span> \"In-site link\"<\/span>;\n } else<\/span> {\n return<\/span> \"Outbound link\"<\/span>;\n }\n}\n<\/code><\/pre>\n<\/div>\n7. Data Layer Variable<\/h3>\n
![\"Data](\"https:\/\/www.simoahava.com\/images\/2014\/02\/data-layer-variable.jpg#ZgotmplZ\")
<\/p>\n![\"Debug](\"https:\/\/www.simoahava.com\/images\/2014\/02\/debug-mode.jpg#ZgotmplZ\")
<\/p>\n![\"DOM](\"https:\/\/www.simoahava.com\/images\/2014\/02\/dom-element.jpg#ZgotmplZ\")
<\/p>\n![\"HTTP](\"https:\/\/www.simoahava.com\/images\/2014\/02\/http-referrer.jpg#ZgotmplZ\")
<\/p>\n