Server-side custom template permissions

This document outlines the permissions for server-side custom templates.

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_bigquery

Display name:Accesses BigQuery

Description:Allows access to BigQuery on Google Cloud Platform.

Configuration:Option to allow specified project, dataset, and table combinations to be used with BigQuery. Setting a project ID configuration of GOOGLE_CLOUD_PROJECT will allow using the GOOGLE_CLOUD_PROJECT environment variable as the project ID when projectId is excluded from the BigQuery API parameter .

Required by: BigQuery

Query signature: queryPermission('access_bigquery', <operation>, <options>)

Notes: <operation> is a string and can have the following values:

write

<options> is an object containing the following items:

  { 
  
 'projectId' 
 : 
  
< project_id 
> , 
  
 'datasetId' 
 : 
  
< dataset_id 
> , 
  
 'tableId' 
 : 
  
< table_id 
> }

Example code

  const 
  
 BigQuery 
  
 = 
  
 require 
 ( 
 'BigQuery' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 connectionInfo 
  
 = 
  
 { 
  
 'projectId' 
 : 
  
 'gcp-cloud-project-id' 
 , 
  
 'datasetId' 
 : 
  
 'destination-dataset' 
 , 
  
 'tableId' 
 : 
  
 'destination-table' 
 , 
 }; 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_bigquery' 
 , 
  
 'write' 
 , 
  
 connectionInfo 
 )) 
  
 { 
  
 const 
  
 rows 
  
 = 
  
 [{ 
  
 'column1' 
 : 
  
 'String1' 
 , 
  
 'column2' 
 : 
  
 1234 
 , 
  
 }]; 
  
 const 
  
 options 
  
 = 
  
 { 
  
 'ignoreUnknownValues' 
 : 
  
 true 
 , 
  
 'skipInvalidRows' 
 : 
  
 false 
 , 
  
 }; 
  
 BigQuery 
 . 
 insert 
 ( 
 connectionInfo 
 , 
  
 rows 
 , 
  
 options 
 ) 
  
 . 
 then 
 ( 
 data 
 . 
 gtmOnSuccess 
 , 
  
 data 
 . 
 gtmOnFailure 
 ); 
 }

access_firestore

Display name:Accesses Google Firestore

Description:Allows access to Google Firestore.

Configuration:Option to allow specified project and path (wildcard syntax supported) combinations to be used with Firestore. Setting a project ID configuration of GOOGLE_CLOUD_PROJECT will allow using the GOOGLE_CLOUD_PROJECT environment variable as the project ID when projectId is excluded from the Firestore API parameter .

Required by: Firestore

Query signature: queryPermission('access_firestore', <operation>, <options>)

Notes: <operation> is a string and can have the following values:

read - Grants access to read and query APIs
write - Grants access to write API
read_write - Grants access to read, write, and query APIs

<options> is an object containing the following items:

  { 
  
 'projectId' 
 : 
  
< project_id 
> , 
  
 'path' 
 : 
  
< path 
> }

Example code

  const 
  
 Firestore 
  
 = 
  
 require 
 ( 
 'Firestore' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 options 
  
 = 
  
 { 
  
 'projectId' 
 : 
  
 'gcp-cloud-project-id' 
 , 
  
 'path' 
 : 
  
 'collection/document' 
 , 
 }; 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_firestore' 
 , 
  
 'read' 
 , 
  
 options 
 )) 
  
 { 
  
 Firestore 
 . 
 read 
 ( 
 'collection/document' 
 , 
  
 { 
  
 projectId 
 : 
  
 'gcp-cloud-project-id' 
 , 
  
 }). 
 then 
 ( 
 data 
 . 
 gtmOnSuccess 
 , 
  
 data 
 . 
 gtmOnFailure 
 ); 
 }

access_response

Display name:Accesses response

Description:Accesses the response body, headers, or status.

Configuration:Option to allow any or specific access, with sub-options for controlling access to various subcomponents.

Required by: setPixelResponse , setResponseBody , setResponseHeader , setResponseStatus

Query signature: queryPermission('access_response', 'write', <component>[, <optional component name>])

Notes:Governs whether the outgoing HTTP response component can be accessed.

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 setResponseBody 
  
 = 
  
 require 
 ( 
 'setResponseBody' 
 ); 
 const 
  
 setResponseHeader 
  
 = 
  
 require 
 ( 
 'setResponseHeader' 
 ); 
 const 
  
 setResponseStatus 
  
 = 
  
 require 
 ( 
 'setResponseStatus' 
 ); 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_response' 
 , 
  
 'write' 
 , 
  
 'header' 
 , 
  
 'Content-Type' 
 )) 
  
 { 
  
 setResponseHeader 
 ( 
 'Content-Type' 
 , 
  
 'text/plain' 
 ); 
 } 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_response' 
 , 
  
 'write' 
 , 
  
 'body' 
 )) 
  
 { 
  
 setResponseBody 
 ( 
 'Not Found' 
 ); 
 } 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_response' 
 , 
  
 'write' 
 , 
  
 'status' 
 )) 
  
 { 
  
 setResponseStatus 
 ( 
 404 
 ); 
 }

access_template_storage

Display name:Accesses Template Storage

Description:Allows access to temporary storage for templates that can persist for the lifetime of the server-side process.

Configuration:None

Required by: templateDataStorage

Query signature: queryPermission('access_template_storage')

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 templateDataStorage 
  
 = 
  
 require 
 ( 
 'templateDataStorage' 
 ); 
 const 
  
 key 
  
 = 
  
 'my_key' 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'access_template_storage' 
 )) 
  
 { 
  
 const 
  
 value 
  
 = 
  
 templateDataStorage 
 . 
 getItemCopy 
 ( 
 key 
 ); 
 }

get_cookies

Display name:Reads cookie value(s)

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

Configuration:List of names of cookies permitted for reading.

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

logging

Display name:Logs to console

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

Configuration:Option to enable logging in production. Defaults to only enable logging in debug/preview. If permission is denied, logToConsole will not throw an error, but will suppress the log message.

Required by: logToConsole

Query signature: queryPermission('logging')

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

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 logToConsole 
  
 = 
  
 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. 
 logToConsole 
 ( 
 'diagnostic info' 
 );

use_message

Display name:Uses messages

Description:Sends or receives messages using the addMessageListener or sendMessage APIs.

Configuration:Option to specify the message type and whether the template can listen, send, or both.

Required by: addMessageListener , sendMessage

Query signature: queryPermission('use_message', <usage>, <message type>)

Notes:Usage can be one of listen , send , or listen_and_send .

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 sendMessage 
  
 = 
  
 require 
 ( 
 'sendMessage' 
 ); 
 if 
  
 ( 
 queryPermission 
 ( 
 'use_message' 
 , 
  
 'send' 
 , 
  
 'set_cookie' 
 )) 
  
 { 
  
 sendMessage 
 ( 
 'set_cookie' 
 , 
  
 { 
 name 
 : 
  
 'foo' 
 , 
  
 value 
 : 
  
 'bar' 
 }); 
 }

read_container_data

Display name:Reads container data

Description:Reads data about the container.

Configuration:None.

Required by: getClientName , getContainerVersion

Query signature: queryPermission('read_container_data')

Notes:Controls whether a custom template can read container data.

Example code

  const 
  
 getContainerVersion 
  
 = 
  
 require 
 ( 
 'getContainerVersion' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_container_data' 
 )) 
  
 { 
  
 return 
  
 getContainerVersion 
 (); 
 }

read_event_data

Display name:Reads event data

Description:Reads data from the event.

Configuration:Option to allow any access, or specific access controlled by a list of allowed key paths (wildcard syntax supported).

Required by: getAllEventData , getEventData

Query signature: queryPermission('read_event_data'[, <optional key>])

Notes:Controls whether a custom template can read event data at a given key path (or all the event data, if no key path is given).

Example code

  const 
  
 getAllEventData 
  
 = 
  
 require 
 ( 
 'getAllEventData' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_event_data' 
 )) 
  
 { 
  
 return 
  
 getAllEventData 
 (); 
 }

  const 
  
 getEventData 
  
 = 
  
 require 
 ( 
 'getEventData' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 keyPath 
  
 = 
  
 'parentField.childField' 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_event_data' 
 , 
  
 keyPath 
 )) 
  
 { 
  
 return 
  
 getEventData 
 ( 
 keyPath 
 ); 
 }

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 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 addEventCallback 
  
 = 
  
 require 
 ( 
 'addEventCallback' 
 ); 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_event_metadata' 
 )) 
  
 { 
  
 addEventCallback 
 (( 
 containerId 
 , 
  
 eventMetadata 
 ) 
  
 = 
>  
 { 
  
 // Read event metadata. 
  
 }); 
 }

read_request

Display name:Reads HTTP request

Description:Reads the request headers, query parameters, body, path, or remote IP address.

Configuration:Option to allow any or specific access, with sub-options for controlling access to various subcomponents.

Required by: extractEventsFromMpv1 , extractEventsFromMpv2 , getRemoteAddress , getRequestBody , getRequestHeader , getRequestPath , getRequestQueryParameter , getRequestQueryParameters , getRequestQueryString

Query signature: queryPermission('read_request', <component>[, <optional component name>])

Notes:Governs whether the incoming HTTP response component can be accessed.

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 getRequestBody 
  
 = 
  
 require 
 ( 
 'getRequestBody' 
 ); 
 const 
  
 getRequestHeader 
  
 = 
  
 require 
 ( 
 'getRequestHeader' 
 ); 
 let 
  
 body 
 , 
  
 contentType 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_request' 
 , 
  
 'body' 
 )) 
  
 { 
  
 body 
  
 = 
  
 getRequestBody 
 (); 
 } 
 if 
  
 ( 
 queryPermission 
 ( 
 'read_request' 
 , 
  
 'header' 
 , 
  
 'content-type' 
 )) 
  
 { 
  
 contentType 
  
 = 
  
 getRequestHeader 
 ( 
 'content-type' 
 ); 
 } 
 if 
  
 ( 
 body 
 && 
 contentType 
  
 == 
  
 'application/json' 
 ) 
  
 { 
  
 ... 
  
 }

return_response

Display name:Returns response

Description:Returns response to the caller.

Configuration:None

Required by: returnResponse

Query signature: queryPermission('return_response')

Notes:This permission has no fields to narrow, and is typically not queried for.

run_container

Display name:Runs the container

Description:Runs the container with an event

Configuration:None

Required by: runContainer

Query signature: queryPermission('run_container')

Notes:This permission has no fields to narrow, and is typically not queried for.

send_http

Display name:Sends HTTP requests

Description:Sends an HTTP request to a specified URL.

Required by: getGoogleScript , sendEventToGoogleAnalytics , sendHttpGet , sendHttpRequest

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

Notes:Governs whether an HTTP request can be made, depending on the URL. To ensure a secure connection, only secure (HTTPS) URLs are permitted.

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 const 
  
 url 
  
 = 
  
 'https://example.com/search?query=foo&results=10' 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'send_http' 
 , 
  
 url 
 )) 
  
 { 
  
 sendHttpGet 
 ( 
 url 
 ); 
 }

send_pixel_from_browser

Display name:Sends pixels from browsers

Description:Sends a GET request to a specified URL from the browser.

Required by: sendPixelFromBrowser

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

Notes:Governs whether a request can be sent from the browser, depending on the URL.

Example code

  const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 sendPixelFromBrowser 
  
 = 
  
 require 
 ( 
 'sendPixelFromBrowser' 
 ); 
 const 
  
 url 
  
 = 
  
 'https://example.com/search?query=foo&results=10' 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'send_pixel_from_browser' 
 , 
  
 url 
 )) 
  
 { 
  
 sendPixelFromBrowser 
 ( 
 url 
 ); 
 }

set_cookies

Display name:Sets a cookie

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

Configuration:A table of allowed cookie names, each with optional restrictions on name, domain, path, secure attribute, and expiration.

Required by: setCookie

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

Notes:Governs whether a given 'Set-Cookie' header can be added to the response, depending on the cookie name, domain, path, secure attribute, and expiration.

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

use_custom_private_keys

Display name:Uses custom private keys

Description:Uses private keys from a JSON key file for cryptographic operations.

Configuration:A list of allowed key IDs. The IDs must match the keys in the JSON key file referenced by the SGTM_CREDENTIALS environment variable on the server.

Required by: hmacSha256

Query signature: queryPermission('use_custom_private_keys', <key id>)

Notes:Governs the list of allowed private keys.

Example code

  const 
  
 hmacSha256 
 = 
  
 require 
 ( 
 'hmacSha256' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 keyId 
  
 = 
  
 'key1' 
 ; 
 let 
  
 result 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'use_custom_private_keys' 
 , 
  
 keyId 
 )) 
  
 { 
  
 result 
  
 = 
  
 hmacSha256 
 ( 
 'my_data' 
 , 
  
 keyId 
 ); 
 }

use_google_credentials

Display name:Uses Google Application Default Credentials

Description:Uses the Google default credentials to make calls to Google APIs.

Configuration:A list of allowed Google OAuth 2.0 scopes .

Required by: getGoogleAuth

Query signature: queryPermission('use_google_credentials', <scopes>)

Notes:Restricts the allowed Google OAuth 2.0 scopes for use with Google APIs.

Example code

  const 
  
 getGoogleAuth 
  
 = 
  
 require 
 ( 
 'getGoogleAuth' 
 ); 
 const 
  
 queryPermission 
  
 = 
  
 require 
 ( 
 'queryPermission' 
 ); 
 const 
  
 scopes 
  
 = 
  
 [ 
  
 'https://www.googleapis.com/auth/datastore' 
 ]; 
 let 
  
 auth 
 ; 
 if 
  
 ( 
 queryPermission 
 ( 
 'use_google_credentials' 
 , 
  
 scopes 
 )) 
  
 { 
  
 auth 
  
 = 
  
 getGoogleAuth 
 ( 
 scopes 
 ); 
 }

Server-side custom template permissions Stay organized with collections Save and categorize content based on your preferences.

access_bigquery

access_firestore

access_response

access_template_storage

get_cookies

logging

use_message

read_container_data

read_event_data

read_event_metadata

read_request

return_response

run_container

send_http

send_pixel_from_browser

set_cookies

use_custom_private_keys

use_google_credentials

Server-side custom template permissions