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](https://support.google.com/tagmanager/answer/6107167#CustomHTML) and [custom JavaScript variables](https://support.google.com/tagmanager/answer/7683362).

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](https://developers.google.com/tag-platform/tag-manager/templates#export_and_import) and share it with others in your organization, and
templates can be developed for broader distribution in the
[Community Template Gallery](https://developers.google.com/tag-manager/templates/gallery).

> [!NOTE]
> **Note:** Custom and Community Templates are only available for web and server-side properties at this time. Template support for mobile platforms will be added at a later date.

## 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](https://lh3.googleusercontent.com/edAcJnyKtTVo5rILkISRWMfEbCtTcAPk_uLyMB5H09Qo-VgaYyy2nlJt-VZ3IAgDNoc=w24)) 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](https://lh3.googleusercontent.com/dW0yyTPf131NnuLju8o-VuiHWYkxcb6MLAfu8hKNjYOoA3euoyQEGc9YiruwUjhzJ9U8=w18-h18)) 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](https://developers.google.com/tag-manager/templates/api#sendpixel).

The second line of code, `const encodeUriComponent =
require('encodeUriComponent')`, imports the [`encodeUriComponent` API](https://developers.google.com/tag-manager/templates/api#encodeuricomponent).

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](https://support.google.com/tagmanager/answer/6238868) or
[preview mode](https://support.google.com/tagmanager/answer/6107056).

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

Some Template APIs have [permissions](https://developers.google.com/tag-manager/templates/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](https://lh3.googleusercontent.com/dW0yyTPf131NnuLju8o-VuiHWYkxcb6MLAfu8hKNjYOoA3euoyQEGc9YiruwUjhzJ9U8=w18-h18)) 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](https://developers.google.com/tag-manager/templates/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.