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.
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.
- 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 () 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 (). 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.
// 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
The second line of code,
const encodeUriComponent = require('encodeUriComponent'), imports the
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
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.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 () 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
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 "
Specify additional URL match patterns on separate lines.
10. Click Test 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:
- In Google Tag Manager, click Tags > New.
- Your new tag will appear in the Custom section of the New Tag window. Click it to open the tag template.
- Fill in the necessary fields for the tag template configuration.
- Click Triggering and select an appropriate trigger for when the tag should fire.
- 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.