{"id":99258,"date":"2025-02-20T10:43:35","date_gmt":"2025-02-20T10:43:35","guid":{"rendered":"https:\/\/accountants4yourbusiness.co.uk\/analytics\/custom-templates-guide-for-google-tag-manager\/"},"modified":"2025-02-20T10:43:35","modified_gmt":"2025-02-20T10:43:35","slug":"custom-templates-guide-for-google-tag-manager","status":"publish","type":"post","link":"https:\/\/accountants4yourbusiness.co.uk\/?p=99258","title":{"rendered":"Custom Templates Guide For Google Tag Manager"},"content":{"rendered":"


\n<\/p>\n

\n
\n

Last updated 12 August 2020<\/strong>: Added details about server-side tagging<\/a>.<\/p>\n<\/blockquote>\n

As I have finally managed to pick up my jaw from the floor, it\u2019s now time to tell you what\u2019s got me so excited. Google Tag Manager<\/a> recently released a new feature called Custom Templates<\/strong><\/a>. Actually, it\u2019s not fair to call it a feature<\/em>. It\u2019s a full-blown paradigm shift in how we use Google Tag Manager. It\u2019s a suite<\/em> of features designed to help brands, companies, and users create and share their own custom JavaScript and HTML setups with ease, while taking care that the code is optimized for delivery in the web browser.<\/p>\n

\n

<\/p>\n

\"custom<\/p>\n

<\/a><\/p>\n<\/div>\n

Custom Templates<\/strong>, in short, are tag, variable, and Client templates that you<\/strong> can create and configure. In other words, if you have a cool idea for a tag (e.g. an analytics tracking tag for a vendor not natively supported by GTM), a variable (e.g. a Custom JavaScript variable that does something with a string), or a Client (e.g. a server-side endpoint for some new analytics tool), you can now turn them into reusable templates which can, in turn, be shared with other users and containers via template export and import. You can also use the Community gallery<\/a> to distribute your templates.<\/p>\n

\n

<\/p>\n

\"Example<\/p>\n

<\/a><\/p>\n<\/div>\n

Templates use a customized, sandboxed version of JavaScript, which has its own idiosyncratic vernacular that you must learn (with the help of this guide, of course). The reason for this added complexity is that with templates you can ensure that the code being executed is safe, unintrusive, and optimized.<\/p>\n

Furthermore, templates you create will define certain permissions<\/strong> that are required for the template code to be able to run. An additional level of governance is provided by way of policies<\/strong> defined on the web page itself where the template code might be run. The interplay between these permissions and policies is a core feature of template security.<\/p>\n

There are lots and lots of things to cover in this guide, so let\u2019s just get started.<\/p>\n


\n X<\/span><\/p>\n

\n
\n The Simmer Newsletter<\/strong>\n <\/p>\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

How to read this guide<\/h2>\n

This is a long guide. It has to be – there\u2019s so much about custom templates that needs to be addressed in any document whose purpose is to provide a comprehensive treatment of the subject matter.<\/p>\n

However, don\u2019t interpret my inability to write concise prose as indicative of how complex custom templates are<\/strong>. I can assure you – they\u2019re absolutely manageable by anyone who\u2019s been using Google Tag Manager for a while.<\/p>\n

This guide is a reference<\/strong>. Its purpose is to offer you documentation to support your work with custom templates.<\/p>\n

Because of this, I want to suggest some different ways to approach this guide.<\/p>\n

Be sure to check out my other guide on how to create a Facebook pixel template<\/a> – it should shed more light on how templates work. You can also check the corresponding video<\/a> if you prefer watching rather than reading.<\/p>\n

You can also view all the custom templates I have created and\/or collected in this GitHub repository<\/a> and in the Templates<\/a> section of this site.<\/p>\n

Custom Templates in a nutshell<\/h2>\n

Google Tag Manager\u2019s Custom Templates offer a way to build a user interface around the custom code you might want to run on the site using Google Tag Manager. The user interface is what you\u2019ve come accustomed to when using GTM\u2019s tags and variables. It comprises text input fields<\/strong>, settings<\/strong>, tables<\/strong>, labels<\/strong>, drop-down menus<\/strong>, and so forth.<\/p>\n

\n

<\/p>\n

\"Tag<\/p>\n

<\/a><\/p>\n<\/div>\n

Obviously, the UI itself is already a huge asset. Being able to offer a user interface in lieu of a complicated code block will minimize problems arising from input errors, and will help keep the code stable.<\/p>\n

However, the templates have another, less apparent (but no less impactful) function. They add layers of protection<\/strong> and security<\/strong> to the code they abstract. Templates use a custom JavaScript framework<\/strong><\/a> which introduces a handful of APIs<\/a> (application programming interfaces) that you must use if you want the code to actually do anything.<\/p>\n

This introduces a steep learning curve, because you can\u2019t just copy-paste code from Stack Overflow<\/a> any more. If you want to set a global window<\/code> property, you need to use an API for that<\/a>. If you want to log to console, you need to use an API for that<\/a>. If you want to check the value of a cookie, guess what, you need to use an API for that<\/a>.<\/p>\n

\n

<\/p>\n

\"API<\/p>\n

<\/a><\/p>\n<\/div>\n

Basically any code that tries to access the global state of the page or run any native JavaScript functions defined on the global level requires an API call.<\/p>\n

So why this added complexity? Well, for one, these APIs make sure that potentially dangerous and\/or intrusive modifications to the global state are done in a controlled manner.<\/p>\n

Whenever you want to use an API, you must require()<\/code> it in the template code. And when you introduce an API like that, the template automatically generates a set of configurable permissions<\/a> for that API call.<\/p>\n

\n

<\/p>\n

\"API<\/p>\n

<\/a><\/p>\n<\/div>\n

In a nutshell, templates encapsulate the logic you would otherwise introduce with custom code. By introducing APIs with permissions<\/strong>, the templates can be configured to work in a secure and easily managed context.<\/p>\n

An added level of security is the introduction of policies<\/strong><\/a>, where you as the site owner can add some code to the web page itself, which can have additional levels of control over how template permissions are resolved.<\/p>\n

For example, if I have a tag configured to send hits to some endpoint, I can write a policy on the page that only allows pixel requests to one of the many endpoints configured in the tag.<\/p>\n

\n
window<\/span>.dataLayer = window<\/span>.dataLayer || [];\nfunction<\/span> gtag(){dataLayer.push(arguments);}\n\ngtag('policy'<\/span>, 'send_pixel'<\/span>, function<\/span>(container, policy, data) {\n  if<\/span> (data.url !== 'https:\/\/snowplow.simoahava.com\/i'<\/span>) {\n    throw<\/span>('Invalid pixel endpoint!'<\/span>);\n  } else<\/span> {\n    return<\/span> true<\/span>;\n  }\n});\n<\/code><\/pre>\n<\/div>\n
\n
    <\/p>\n
    \"Tag<\/p>\n
    <\/a><\/p>\n<\/div>\n
An additional perk of using templates is that you don\u2019t have to add the nasty unsafe-eval<\/code> keyword to your Content Security Policy<\/a>. Any code run through a template is compiled into JavaScript when the container is written, and thus doesn\u2019t require the use of eval()<\/code>.<\/p>\n
Conversely, with Custom HTML tags and Custom JavaScript variables, the code is written into a string which is then compiled with eval()<\/code> at runtime. This is a bad practice and requires a huge compromise in security if using a Content Security Policy.<\/p>\n
I hope you can see the usefulness of Custom Templates. Imagine a library of Custom Templates, where anyone can share their own work for others to download and use in their containers. Smaller brands and companies could finally get their tools and platforms out there for the masses using Google Tag Manager.<\/p>\n
\n
Update 2 October 2019<\/strong>: You no longer have to imagine such a library as it now exists. Check out the Community Template Gallery<\/a> as well as my introduction<\/a> to it.<\/p>\n<\/blockquote>\n
Getting started<\/h2>\n
Before exhausting you with all the details about custom templates (and trust me, there\u2019s a lot<\/strong> to digest in the feature), I want to start by walking you through creating a tag template<\/strong> and a variable template<\/strong>. We won\u2019t use all the most complex features for this, but it should serve as a nice intro to how custom templates work in Google Tag Manager.<\/p>\n
Be sure to check out this guide<\/a> for a walkthrough of building a Client template for server-side tagging<\/strong>.<\/p>\n
Don\u2019t forget to check out my other article, which covers the creation of a Facebook pixel template<\/a>. It should provide a more comprehensive (and more overwhelming) look at how templates are created.<\/p>\n
Tag template walkthrough<\/h3>\n
In this walkthrough, we\u2019ll go through how to create a simple script injection tag<\/strong>. This is how many of the third-party vendors out there want their scripts to be loaded.<\/p>\n
We\u2019ll use a wonderful company called Conductrics<\/a> as an example. They have developed a tool with which you can do A\/B-testing and personalization, using ML-driven targeting logic, dynamic goals, server-side and client-side deployment options, and a whole host of other features to help you answer those difficult business questions you have with data<\/strong>.<\/p>\n
\n
    <\/p>\n
    \"Conductrics<\/p>\n
    <\/a><\/p>\n<\/div>\n
Note!<\/strong> You can of course replace the Conductrics-specific stuff with some other vendor source URL, if you want. The steps you take in this guide would still be identical.<\/p>\n
The tag template is simple, by design. Conductrics offers the option to host the required JavaScript for you, so all you need to do is add the <\/code> tag to the page that loads the JavaScript library from Conductrics\u2019 server.<\/p>\n
However, I\u2019ve added some UI sugar to make the setup slightly more interesting.<\/p>\n
Basically, all templates comprise four components:<\/p>\n
    \n
  1. \n
    The details, which determine the template name, logo, and description.<\/p>\n<\/li>\n
  2. \n
    The user interface, which governs the fields and field configurations the template has.<\/p>\n<\/li>\n
  3. \n
    The code editor, which makes use of whatever the user input into the fields to run the actual template code.<\/p>\n<\/li>\n
  4. \n
    Permissions, which determine what type of code can be run by the tag.<\/p>\n<\/li>\n<\/ol>\n
    We\u2019ll walk through each of these steps here.<\/p>\n
    Step 1 – Create and set the details of the tag template<\/h4>\n
    The first thing you need to do is create a new tag template:<\/p>\n
    \n
        <\/p>\n
        \"Create<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Next, fill in some details. For the image, I used the logo<\/a> created by Conductrics\u2019 brand designer Joshua McCowen<\/a>.<\/p>\n
    \n
        <\/p>\n
        \"Conductrics<\/p>\n
        <\/a><\/p>\n<\/div>\n
    You can Save<\/strong> the template by clicking the respective icon in the top-right corner now. You should see the logo and the template title in the preview window.<\/p>\n
    \n
        <\/p>\n
        \"Tag<\/p>\n
        <\/a><\/p>\n<\/div>\n
    There! Almost done. Well, not quite.<\/p>\n
    Step 2 – Create the UI<\/h4>\n
    Now we need to create the bells and whistles of the tag\u2019s actual user interface.<\/p>\n
    First, click the Fields<\/strong> tab to open the Fields editor<\/a>. Then, click the blue Add Field<\/strong> button.<\/p>\n
    \n
        <\/p>\n
        \"Add<\/p>\n
        <\/a><\/p>\n<\/div>\n
    In the overlay that opens, select Text input<\/strong>.<\/p>\n
    \n
        <\/p>\n
        \"Choose<\/p>\n
        <\/a><\/p>\n<\/div>\n
    You should see a text input<\/a> field appear in the Fields editor. Rename the field to sourceUrl<\/strong>, and edit the Display name<\/a> setting. The field name is used in the code editor, and the Display name<\/strong> setting is what the user sees above the field when editing the tag settings.<\/p>\n
    \n
        <\/p>\n
        \"Rename<\/p>\n
        <\/a><\/p>\n<\/div>\n
    The UI could be ready now – it\u2019s really the only field and the only configuration you\u2019d need.<\/p>\n
    But let\u2019s make it a bit more robust by adding some validation<\/strong>.<\/p>\n
    Click the cogwheel<\/strong> icon associated with the field to open the Field configuration<\/a> overlay. In the overlay, make sure Display name<\/strong>, Help text<\/strong>, and Validation rules<\/strong> are all toggled ON<\/strong>.<\/p>\n
    Each field type has its own set of configurations you can edit to make the field more versatile.<\/p>\n
    \n
        <\/p>\n
        \"Field<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Close the overlay by clicking the X<\/strong> in the corner, or anywhere outside the overlay.<\/p>\n
    Next, add some Help text<\/a>. Help text can be seen by hovering over the little question mark next to the Display name when editing the tag.<\/p>\n
    \n
        <\/p>\n
        \"Add<\/p>\n
        <\/a><\/p>\n<\/div>\n
    You can Save<\/strong> the template periodically to refresh the template preview and see the changes there.<\/p>\n
    Next, let\u2019s add some Validation rules<\/a>. These can be used to ensure the user adds valid values to the fields.<\/p>\n
    Click Add rule<\/strong> and edit the rule to match a regular expression<\/strong> where the expression is ^https:\/\/.*<\/code>. Validation regular expressions look for full matches only<\/strong>, so you need to add leading and\/or trailing .*<\/code> to use an open-ended pattern.<\/p>\n
    \n
        <\/p>\n
        \"First<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Next, click the little action menu in the top corner of the validation rule box, and select Show advanced settings<\/strong>.<\/p>\n
    \n
        <\/p>\n
        \"Show<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Validation rules have two advanced settings. The first is where you can provide a custom error message<\/strong> (which we\u2019ll use). The second is one where you can establish conditions for when<\/strong> this validation rule is active (or inactive).<\/p>\n
    In this case, let\u2019s add a descriptive error message. Set the Error message<\/strong> field to The URL must start with \"https:\/\/\".<\/code>.<\/p>\n
    \n
        <\/p>\n
        \"Error<\/p>\n
        <\/a><\/p>\n<\/div>\n
    You can now quickly test<\/strong> how this works. Click Save<\/strong> in the top right corner, then click the tag template in the preview mode to enter edit mode. Add some string to the text input field that doesn\u2019t<\/strong> start with \u201chttps:\/\/\u201d, and click the Test<\/strong> button in the top-right corner. You should see your error message.<\/p>\n
    \n
        <\/p>\n
        \"Error<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Cool, right?<\/p>\n
    Let\u2019s add two<\/strong> more validation rules. Make them look like this:<\/p>\n
    \n
        <\/p>\n
        \"Last<\/p>\n
        <\/a><\/p>\n<\/div>\n
    The first rule ensures that the script is loaded from a *.conductrics.com<\/code> domain, and the second rule requires that the script URL has the apikey<\/code> parameter.<\/p>\n
    One final thing we\u2019ll add to the user interface is a simple debug<\/strong> toggle.<\/p>\n
    Click the Add field<\/strong> button, and select Checkbox<\/strong> from the overlay.<\/p>\n
    \n
        <\/p>\n
        \"Checkbox\"\/<\/p>\n
        <\/a><\/p>\n<\/div>\n
    Set the field name to debug<\/strong>, and set the Checkbox text<\/strong> field to Log debug messages to console<\/strong>. Feel free to save the template to see how the checkbox looks like in the wild.<\/p>\n
    \n
        <\/p>\n
        \"Checkbox<\/p>\n
        <\/a><\/p>\n<\/div>\n
    We\u2019re all done with the UI, finally!<\/p>\n
    Step 3 – Add some code<\/h4>\n
    Now, select the Code<\/strong> tab from the template editor. You should see some boilerplate code that will help you get started (we\u2019ll replace this with some other stuff soon enough).<\/p>\n
    \n
        <\/p>\n
        \"Code<\/p>\n
        <\/a><\/p>\n<\/div>\n
    For tag<\/strong> templates, the code you write has three components you need to be aware of.<\/p>\n
With that policy in place, the image request will only be executed if the endpoint URL is https:\/\/snowplow.simoahava.com\/i<\/code>. Otherwise, the tag will fail in an error, and you can see the error message in the Errors<\/strong> tab<\/a> of Preview mode.<\/p>\n