Custom template policies

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;
  }
});