Custom templates quick start guide

Custom templates allow you to write your own tag and variable definitions so that others within your organization can use them alongside the built-in tag and variable templates. The permission-centric, sandboxed nature of custom templates makes it possible to write custom tags and variables in a safer, more efficient manner than when using custom HTML tags and custom JavaScript variables.

Custom tag and variable templates are defined in the Templates section of Google Tag Manager. The main Templates screen will list any tag or variable templates that have already been defined in your container. You can also create new templates from this screen.

You can export a template and share it with others in your organization, and templates can be developed for broader distribution in the Community Template Gallery.

The Template Editor

The Template Editor enables you to create, preview, and test custom templates. It has four primary areas for input to help you define your tag template:

  • Info - Define basic properties of the template, such as the tag or variable name and icon.
  • Fields - This is a visual editor to add input fields to your tag template.
  • Code - Enter sandboxed JavaScript to define how your tag or variable should behave.
  • Permissions - View and set limits on what your tag or variable is permitted to do.

Create your first custom tag template

This example will walk you through how to create a basic example pixel tag. When this tag is fired on a web page, it will send a hit with the correct account information to the tag provider's servers.

1. To begin your first template, click Templates in the left navigation and click the New button under the Tag Templates section.

2. Click Info and define the tag's Name (required), Description, and Icon.

Name is what will be presented to users when they go to implement this tag throughout the Tag Manager user interface.

Description is just what it sounds like – a brief (200 characters or less) description of what this tag does.

Icon lets you choose an image that will appear when the tag is displayed in lists that support the icon property. Icon images should be square PNG, JPEG, or GIF files that are no larger than 50 kB and at least 64px by 64px.

3. Click Refresh to preview your template.

To the right of the field inputs, there is a Template Preview window. Every time a change is made in the editor, the Refresh button will appear. Click Refresh to see what your changes do to the appearance of your tag.

4. Click Fields to add fields to your tag template.

The Template Editor's Fields tab lets you create and edit fields in the tag template. Fields are used to enter custom data, such as an account ID. You can add the standard form elements like text fields, drop down menus, radio buttons, and checkboxes.

5. Click Add Field and select Text input. Replace the default name (e.g. "text1") with "accountId". In the Template Preview, click Refresh.

The field will have familiar variable selector (variable selector icon) icon next to it. Users of this template can click the variable selector icon to choose variables that are active in this container.

The next step is to add a label to the field:

6. Click the expand icon (expand icon) next to the text field to open more options for this field. Enter "Account ID" in the Display name field. In Template Preview, click Refresh.

A text label titled "Account ID" should appear above the field.

7. Click the Code tab and enter sandboxed JavaScript in the editor:

// require relevant API
const sendPixel = require('sendPixel');
const encodeUriComponent = require('encodeUriComponent');

// capture values of template fields
const account = data.accountId;

// use the provided APIs to do things like send pixels
const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account);
sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure);

The first line of code, const sendPixel = require('sendPixel'), imports the sendPixel API.

The second line of code, const encodeUriComponent = require('encodeUriComponent'), imports the encodeUriComponent API.

The next line, const account = data.accountId;, gets the value of accountId that was created in step 5, and stores it in a constant called account.

The 3rd line of code, const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account);, sets up a url constant that concatenates a fixed URL endpoint that logs analytics data and the encoded account ID with which the tag has been configured.

The last line, sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure), runs the sendPixel() function with the required parameters and makes a request to the specified URL. The data.gtmOnSuccess and data.gtmOnFailure values tell Google Tag Manager when the tag has completed or failed its task, and are then used by Google Tag Manager for features such as tag sequencing or preview mode.

8. Click Save to save your progress. This will load any detected permissions into the Template Editor.

Some Template APIs have permissions associated with them that dictate what they can or cannot do. When you use a template API such as sendPixel in your code, Tag Manager will show relevant permissions in the Permissions tab.

9. Click Permissions to refine what domains sendPixel is allowed to send data to. For the Send Pixels entry, click the expand icon (expand icon) and enter https://endpoint.example.com/ in Allowed URL Match Patterns.

When a tag template is configured to send data, you must specify an Allowed URL Match Pattern under the associated permission to restrict where data can be sent to. If the URL specified in your code does not match an allowed URL match pattern, the sendPixel call will fail.

A URL match pattern must use HTTPS and specify both host and path patterns. The host can be a domain (e.g. "https://example.com/") or a specific subdomain (e.g. "https://sub.example.com/"). The path must consist of at least a "/". Use an asterisk (*) as a wildcard to indicate a subdomain or path pattern of any length (e.g. "https://\*.example.com/test/"). The asterisk is a wildcard character that will catch the various possible patterns, e.g. "\*.example.com/" will match www.example.com, shop.example.com, blog.example.com, etc. The asterisk must be escaped with a backslash character: "\*". A URL with no additional characters (e.g. "https://example.com/") is treated as ending in a wildcard (i.e. equivalent to "https://example.com/\*".

Specify additional URL match patterns on separate lines.

10. Click Run Code and look at the Console window for any problems.

Any detected errors will appear in the Console window.

11. Click Save, and close the Template Editor.

The tag template should now be ready for use.

Use your new tag

The process to create a new tag that uses your newly-defined custom tag template is just like any other tag:

  1. In Google Tag Manager, click Tags > New.
  2. Your new tag will appear in the Custom section of the New Tag window. Click it to open the tag template.
  3. Fill in the necessary fields for the tag template configuration.
  4. Click Triggering and select an appropriate trigger for when the tag should fire.
  5. Save the tag and publish your container.

Create your first custom variable template

Custom variable templates are similar to tag templates, with a few notable differences:

  • Custom variable templates must return a value.

    Instead of calling data['gtmOnSuccess'] to indicate completion, variables return a value directly.

  • Custom variables templates are used in different parts of the Tag Manager UI.

  • Instead of going to Tags > New to create a new variable based on your custom variable, you go to Variables > New

See create a custom variable for a full guide to creating a custom variable template.

Export and import

To share a custom template with your organization, you can export the custom template and import it into other Tag Manager containers. To export a template:

  1. In Tag Manager, click Templates.
  2. Click the name of the template you wish to export from the list. This will open the template in the Template Editor.
  3. Click the More Actions menu () and select Export.

To import a template:

  1. In Tag Manager, click Templates.
  2. Click New. This will open a blank template in the Template Editor.
  3. Click the More Actions menu () and select Import.
  4. Select the .tpl file that you would like to import.