Custom template policies

  • Use the gtag('policy', ...) API to control how Tag Manager's custom templates use features like injecting scripts or sending pixels within your web page.

  • Policies are applied by defining functions that evaluate permission requests for specific Tag Manager containers and functionalities, allowing or rejecting them based on your defined criteria.

  • The gtag('policy', ...) API accepts a permission ID like inject_script or send_pixel to define rules for that specific action, or all to handle various permissions within a single function.

  • Policy functions determine whether to allow or reject a permission request by returning true for allowance, false for rejection, or throwing an exception to provide a descriptive error in the debug console.

  • You can implement policies to manage permissions on a granular level, allowing specific scripts to be injected, pixels to be sent to certain URLs, or controlling access to global variables, ensuring enhanced security and control over your website's behavior.

Policies are implemented on a web page. When a container runs on the page, policies are applied to Tag Manager's custom template definitions to control how certain features and functionality can be used. Policies are implemented with the gtag('policy', ...) API.

The gtag('policy', ...) API requires definitions for dataLayer and gtag(). Ensure that dataLayer and gtag() are defined in your code before gtag('policy', ...) is called later in the script:

window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}

Use the gtag('policy', ...) API on a web page to set policies for custom template permissions:

gtag('policy', <permissionId>, <function>)

The <permissionId> argument is any one of the supported permissions types, e.g. inject_script. The policy will be called whenever a container wants to check if that permission is allowed.

gtag('policy', 'inject_script', function(containerId, permissionId, data) {
  // Specific inject_script check goes here.
});

Specify 'all' to interact with all policy checks.

gtag('policy', 'all', function(containerId, permissionId, data) {
  // System-wide check goes here.
});

The third argument—<function>—is a function that implements the indicated policy with this signature:

function(containerId, permissionId, data) {...}
  • containerId is the Tag Manager container ID, e.g. 'GTM-1234'.
  • permissionId is a string that specifies the type of policy to be checked.
  • data is an object that contains any relevant information for the indicated permission type, e.g. 'url' for a 'send_pixel' permission.

A policy function rejects a permission request when it returns false or throws an exception. Any exceptions with a type of string or Error will appear in the Errors section of the debug pane when preview mode is enabled. When multiple policy checks are registered, each check is called, and each check has the ability to reject a policy request.

This example creates a policy that checks the 'inject_script' permission:

gtag('policy', 'inject_script', function(containerId, permissionId, data) {

  // reference the url of the script to be injected
  let url = data.url || '';

  // if the url of the injected script exactly matches, allow it.
  // otherwise throw an error
  if (url === 'https://scripts.example.com/analytics.js') {
    return true;
  } else {
    throw 'Only permitted to inject https://scripts.example.com/analytics.js';
  }
});

This example uses the 'all' keyword to check multiple policy scenarios:

gtag('policy', 'all', function(containerId, permissionId, data) {

  // Only set policy for 1 specific container.
  // This enables other containers loaded on the page to
  // operate without restrictions on permissions.
  if (container != 'GTM-4321') return true;

  // Since the policy is 'all', adjust permissions conditionally.
  switch (permissionId) {

    case 'send_pixel':
      return true;

    case 'write_globals':
      return data.key && data.key == '_gaq';

    case 'inject_script':
      let url = data.url || '';
      if (url.indexOf('https://example.com') != 0)
        throw 'Only example.com scripts are permitted';

    default:
      // IT staff decides that all unknown permissions
      // are rejected.
      return false;
  }
});