Custom template permissions

Each permission is:

  • Checked by APIs that require them.
  • Automatically detected in sandboxed JavaScript, based on what APIs are used. This happens as edits are made in the custom template editor (for a fast feedback loop), and when code is compiled (to validate that the correct permissions are enforced).
  • Editable in the custom template editor, to make the permission more specific.
  • Queryable in sandboxed JavaScript via the queryPermission API.

access_globals

Display name: Accesses Global Variables

Description: Allows access to a global variable (potentially including sensitive APIs).

Configuration: List of keys that can be accessed. Each key is a dot separated path. For example: foo.bar The first token in each path must not be a predefined key on browser global scope, nor a JavaScript keyword. Has read, write, and execute checkboxes that govern access.

Required by: setInWindow, copyFromWindow, callInWindow, createQueue, createArgumentsQueue

Query signature: queryPermission('access_globals', 'read', <key to read from>) or queryPermission('access_globals', 'write', <key to write to>) or queryPermission('access_globals', 'readwrite', <key to read and write>) or queryPermission('access_globals', 'execute', <key of function to execute>)

Notes: Controls whether a custom template can read and/or write to global values.

Example code

const query = require('queryPermission');
const createQueue = require('createQueue');
if (query('access_globals', 'readwrite', 'dataLayer')) {
  const dataLayerPush = createQueue('dataLayer');
}

get_cookies

Display name: Reads cookie value(s)

Description: Reads the values of the cookies with the specified name.

Required by: getCookieValues

Query signature: queryPermission('get_cookies', <name>)

Notes: Governs whether a cookie can be read, depending on its name.

Example code

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

get_referrer

Display name: Reads Referrer URL

Description: Permits read access to narrowed portions of the referrer.

Configuration: The following booleans govern which part of the referrer can be read. A given part of the referrer can only be read if the corresponding part is true. The caller can call getReferrerUrl without a component specified to get the full referrer URL if all these booleans are set to true. If no value is set, the default value is all. If a value is set, the value must be an array of components where a component is one of the following: protocol, host, port, path, query, or extension.

queryKeys: If query is selected, then the template author may further limit the set of query keys they can read from. This is a simple array of keys, with no wildcards.

Required by: getReferrerUrl, getReferrerQueryParameters

Query signature: queryPermission('get_referrer', <url_component>)

Example code

const queryPermission = require('queryPermission');
const getReferrerUrl = require('getReferrerUrl');
let referrer;
if (queryPermission('get_referrer', 'query')) {
  referrer = getReferrerUrl('queryParams');
}

get_url

Display name: Reads URL

Description: Returns part or all of the URL of the current page.

Configuration: The following booleans govern which part of the URL can be read. A given part of the URL can only be read if the corresponding part is true. The caller can call getUrl without a component specified to get the entire URL if and only if all these booleans are set to true. If no value is set, the default value is all. If a value is set, the value must be an array of components where a component is one of the following: protocol, host, port, path, query, extension, or fragment.

queryKeys: If query is selected, then the template author may further limit the set of query keys they can read from. This is a simple array of keys, with no wildcards.

Required by: getUrl

Query signature: queryPermission('get_url', <optional url component>, <optional query key>)

If supplied, Url component should be one of 'protocol', 'host', 'port', 'path', 'query', 'extension', 'fragment'. If omitted, the permission query is a request for access to the whole URL.

If supplied, query key should be the query string argument that the template code wants to read. Notes: Controls whether a custom template can read from the current location. Allows limiting to a specific part of the location.

Example code

const query = require('queryPermission');
const getUrl = require('getUrl');
if (query('get_url', 'query', 'gclid')) {
  const gclid = getUrl('query', false, null, 'gclid');
}

inject_hidden_iframe

Display name: Injects Hidden Iframes

Description: Injects an invisible iframe with a given URL.

Configuration: List of URL patterns

Required by: injectHiddenIframe

Query signature: queryPermission('inject_hidden_iframe', <url>)

Notes: Governs whether a custom template can inject an invisible iFrame, and from which origin it can do so.

Example code

const query = require('queryPermission');
const iframe = require('injectHiddenIframe');
const url = 'https://www.example.com/iframes';
if (query('inject_hidden_iframe', url)) {
  iframe(url);
}

inject_script

Display name: Injects Scripts

Description: Injects a script into the page.

Configuration: List of URL patterns

Required by: injectScript

Query signature: queryPermission('inject_script', <url>)

Notes: Governs whether a custom template can inject JavaScript, and from what origin it can do so.

Example code

const query = require('queryPermission');
const injectScript = require('injectScript');
const url = 'https://www.example.com?api.js';
if (query('inject_script', url)) {
  injectScript(url);
}

logging

Display name: Logs to Console

Description: Logs to the developer console and GTM's preview mode.

Configuration: Option to enable logging in production. Defaults to only enable logging in debug/preview. Required by: Used by logToConsole. If permission is denied, then logToConsole will noOp instead of throwing an error.

Required by: logToConsole

Query signature: queryPermission('logging')

Notes: Controls whether a custom template can log to the developer console .

Example code

const query = require('queryPermission');
const log = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
log('diagnostic info');

read_data_layer

Display name: Reads Data Layer

Description: Reads data from the dataLayer.

Configuration: Set of key match expressions, where a key match can be a leading series of dotted references, with a trailing wildcard. Key match expressions govern which properties may be read from the data layer.

Required by: copyFromDataLayer

Query signature: queryPermission('read_data_layer', <data layer key to read from>)

Notes: Controls whether a custom template can read from the data layer.

Example code

const query = require('queryPermission');
const dlKey = 'foo.bar';
const copyDL = require('copyFromDataLayer');
if (query('read_data_layer', dlKey)) {
  const dlContents = copyDL(dlKey);
}

read_character_set

Display name: Reads Document Character Set

Description: Reads document.characterSet.

Configuration: None

Required by: readCharacterSet

Query signature: queryPermission('read_character_set')

Notes: Governs whether a custom template can read the document.characterSet.

Example code

const query = require('queryPermission');
const readCharacterSet = require('readCharacterSet');
if (query('read_character_set')) {
  const characterSet = readCharacterSet();
}

read_event_metadata

Display name: Reads Event Metadata

Description: Reads Event Metadata in Event Callbacks

Configuration: None

Required by: addEventCallback

Query signature: queryPermission('read_event_metadata')

Notes: Controls whether a custom template can read event metadata in callbacks.

Example code

const query = require('queryPermission');
const addEventCallback = require('read_event_metadata);
if (query('read_event_metadata)) {
  addEventCallback((ctid, eventData) => {
    // Read eventData.
  });
}

read_title

Display name: Reads Document Title

Description: Reads document.title.

Configuration: None

Required by: readTitle

Query signature: queryPermission('read_title')

Notes: Governs whether a custom template can read the document.title.

Example code

const query = require('queryPermission');
const readTitle = require('readTitle');
if (query('read_title')) {
  const title = readTitle();
}

send_pixel

Display name: Sends Pixels

Description: Sends a GET request to a specified URL. Response is not processed.

Configuration: List of whitelisted URL patterns.

Required by: sendPixel

Query signature: queryPermission('send_pixel', <url>)

Notes: Governs whether a custom template can send a GET request, and to which origin it can do so.

Example code

const query = require('queryPermission');
const sendPixel = require('sendPixel');
const url = 'https://www.example.com?foo=3';
if (query('send_pixel', url)) {
  sendPixel(url);
}

set_cookies

Display name: Sets a cookie

Description: Sets a cookie with the specified name and parameters.

Required by: setCookie

Query signature: queryPermission('set_cookies', <name>, <options>)

Notes: Governs whether a cookie can be written, depending on its name, domain, and path, secure flag, and expiration parameters.

Example code

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}