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, for example, 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, for example, '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, for example, '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 (containerId != 'GTM-4321') return true;

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

    case 'read_event_data':
    case 'read_container_data':
    case 'configure_google_tags':
    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';
      return true;

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

Avoid blocking measurement with strict deny-all policies

If you implement a strict "deny-all" policy on your web page using gtag('policy', ...), your Google tag and Tag Manager containers won't send measurement pings unless the permissions required for destination tag measurement are allowed.

To retain measurement, adjust your on-page gtag('policy', ...) implementation to allow the read_event_data, read_container_data, and configure_google_tags permissions:

If your policy blocks individual permissions

Remove any policy checks that reject the required measurement permissions:

// Remove or update policy checks that return false for these permissions:
gtag('policy', 'read_event_data', function(containerId, permissionId, data) {
  // ...
});

gtag('policy', 'read_container_data', function(containerId, permissionId, data) {
  // ...
});

gtag('policy', 'configure_google_tags', function(containerId, permissionId, data) {
  // ...
});

If your policy acts on 'all' permissions

Explicitly allow read_event_data, read_container_data, and configure_google_tags before applying your default restriction logic:

gtag('policy', 'all', function(containerId, permissionId, data) {
  // Allow destination tag permissions required for measurement
  const allowedPermissions = [
    'read_event_data',
    'read_container_data',
    'configure_google_tags',
  ];
  if (allowedPermissions.includes(permissionId)) {
    return true;
  }

  // Pre-existing permission code.
});

Determine if measurement is blocked by a policy

Policies can vary from page to page (including pages behind a login wall), so the absence of a policy on your home page doesn't guarantee that other pages on your site don't enforce a policy.

• Inspect dataLayer: You can check whether a policy is active on a page by inspecting the contents of window.dataLayer in your browser console and looking for an entry beginning with Arguments(3) ['policy', ....
• Verify with Tag Assistant: You can use Tag Assistant to determine whether policy restrictions are blocking measurement. When a policy blocks measurement, Tag Assistant outputs the specific permission ID that must be enabled for destination events to function.