Custom template APIs

Core APIs

These APIs work with sandboxed JavaScript to build custom templates in Google Tag Manager. Each API is added with a require() statement, e.g.:

  const 
  
 myAPI 
  
 = 
  
 require 
 ( 
 'myAPI' 
 ); 
 

addConsentListener

Registers a listener function to execute when the state of the specified consent type changes.

The given listener will be invoked every time the state for the specified consent type changes from denied to granted or from granted to denied. A consent type with no state is considered granted, so the listener won't be called if an unset consent type is updated to granted. Listener functions will be in charge of ensuring their code runs the appropriate number of times.

Example:

  const 
  
 isConsentGranted 
  
 = 
  
 require 
 ( 
 'isConsentGranted' 
 ); 
 const 
  
 addConsentListener 
  
 = 
  
 require 
 ( 
 'addConsentListener' 
 ); 
 if 
  
 ( 
 ! 
 isConsentGranted 
 ( 
 'ad_storage' 
 )) 
  
 { 
  
 let 
  
 wasCalled 
  
 = 
  
 false 
 ; 
  
 addConsentListener 
 ( 
 'ad_storage' 
 , 
  
 ( 
 consentType 
 , 
  
 granted 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 wasCalled 
 ) 
  
 return 
 ; 
  
 wasCalled 
  
 = 
  
 true 
 ; 
  
 const 
  
 cookies 
  
 = 
  
 getMyCookies 
 (); 
  
 sendFullPixel 
 ( 
 cookies 
 ); 
  
 }); 
 } 
 

Syntax

addConsentListener(consentType, listener)

Parameters

When a listener is invoked, it will be passed the consent type that is being changed and the new value of that consent type:

Associated permissions

access_consent permission with read access for the consent type.

addEventCallback

The addEventCallback API allows you to register a callback function that will be invoked at the end of an event. The callback will be invoked when all the tags for the event have executed, or if an in page event timeout is reached. The callback is passed two values, the id of the container that invokes the function and an object that contains information about the event.

Syntax

addEventCallback(callback)

Parameters

The eventData object contains the following data:

Example

  addEventCallback 
 ( 
 function 
 ( 
 ctid 
 , 
  
 eventData 
 ) 
  
 { 
  
 logToConsole 
 ( 
 'Tag count for container ' 
  
 + 
  
 ctid 
  
 + 
  
 ': ' 
  
 + 
  
 eventData 
 [ 
 'tags' 
 ]. 
 length 
 ); 
 }); 
 

Associated permissions

read_event_metadata

aliasInWindow

The aliasInWindow API lets you create an alias (e.g. window.foo = window.bar ), which helps to support certain tags that require aliasing. Assigns the value in the window object found at the fromPath to the key in the window object at the toPath . Returns true if successful, false otherwise.

Syntax

aliasInWindow(toPath, fromPath)

Parameters

Example

  aliasInWindow 
 ( 
 'foo.bar' 
 , 
  
 'baz.qux' 
 ) 
 

Associated permissions

access_globals is required for both toPath and fromPath ; toPath requires write access, fromPath requires read access.

callInWindow

Allows you to call functions from a path off the window object, in a policy- controlled way. Calls the function at the given path in window with the given arguments and returns the value. If the return type can't be directly mapped to a type supported in sandboxed JavaScript, undefined will be returned. The eight types supported in sandboxed JavaScript are null , undefined , boolean , number , string , Array , Object , and function . If the given path does not exist, or does not reference a function, undefined will be returned.

Syntax

callInWindow(pathToFunction, argument [, argument2,... argumentN])

Parameters

Associated permissions

access_globals with execute permission enabled.

callLater

Schedules a call to a function to occur asynchronously. The function will be called after the current code returns. This is equivalent to setTimeout(<function>, 0) .

Syntax

callLater(function)

Parameters

copyFromDataLayer

Returns the value currently assigned to the given key in the data layer: The value found at the given key if it's a primitive type, function, or object literal, or undefined otherwise.

Syntax

copyFromDataLayer(key[, dataLayerVersion])

Parameters

Associated permissions

read_data_layer

copyFromWindow

Copies a variable from window object. If the value in window can't be directly mapped to a type supported in sandboxed JavaScript, undefined will be returned. The eight types supported in sandboxed JavaScript are null , undefined , boolean , number , string , Array , Object , and function . Returns the fetched (and coerced) value.

Syntax

copyFromWindow(key)

Parameters

Associated permissions

access_globals

createArgumentsQueue

Creates a queue that is populated with argument objects, in support of tag solutions that require it.

Creates a function in global scope (i.e. window ), using the fnKey argument (same semantics as createQueue ). After the function is created, this API then creates an array in window (if it doesn't already exist) using the arrayKey argument.

When the function created under fnKey is called, it pushes its arguments object onto the array created under arrayKey . The API's return value is the function created under fnKey .

This function requires the read and write setting for fnKey and arrayKey on the access_globals permission.

Example:

  const 
  
 gtag 
  
 = 
  
 createArgumentsQueue 
 ( 
 'gtag' 
 , 
  
 'dataLayer' 
 ); 
 gtag 
 ( 
 'set' 
 , 
  
 { 
 'currency' 
 : 
  
 'USD' 
 }); 
 

Syntax

createArgumentsQueue(fnKey, arrayKey)

Parameters

Associated permissions

access_globals

createQueue

Creates an array in window (if it doesn't already exist) and returns a function that will push values onto that array.

This function requires the read and write setting for arrayKey on the access_globals permission.

Example:

  const 
  
 dataLayerPush 
  
 = 
  
 createQueue 
 ( 
 'dataLayer' 
 ); 
 dataLayerPush 
 ({ 
 'currency' 
 : 
  
 'USD' 
 }, 
  
 { 
 'event' 
 : 
  
 'myConversion' 
 }); 
 

Syntax

createQueue(arrayKey)

Parameters

Associated permissions

access_globals

decodeUri

Decodes any encoded characters in the provided URI. Returns a stringthat represents the decoded URI. Returns undefined when provided with invalid input.

Example:

  const 
  
 decode 
  
 = 
  
 require 
 ( 
 'decodeUri' 
 ); 
 const 
  
 decodedUrl 
  
 = 
  
 decode 
 ( 
 data 
 . 
 encodedUrl 
 ); 
 if 
  
 ( 
 decodedUrl 
 ) 
  
 { 
  
 // ... 
 } 
 

Syntax

decodeUri(encoded_uri)

Parameters

Associated permissions

None.

decodeUriComponent

Decodes any encoded characters in the provided URI component. Returns a stringthat represents the decoded URI component. Returns undefined when provided with invalid input.

Example:

  const 
  
 decode 
  
 = 
  
 require 
 ( 
 'decodeUriComponent' 
 ); 
 const 
  
 decodedUrl 
  
 = 
  
 decode 
 ( 
 data 
 . 
 encodedUrl 
 ); 
 if 
  
 ( 
 decodedUrl 
 ) 
  
 { 
  
 // ... 
 } 
 

Syntax

decodeUriComponent(encoded_uri_component)

Parameters

Associated permissions

None.

encodeUri

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a stringthat represents the provided string encoded as a URI. Returns undefined when provided with invalid input (a lone surrogate).

Example:

  sendPixel 
 ( 
 'https://www.example.com/' 
  
 + 
  
 encodeUri 
 ( 
 pathInput 
 )); 
 

Syntax

encodeUri(uri)

Parameters

Associated permissions

None.

encodeUriComponent

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a stringthat represents the provided string encoded as a URI. Returns undefined when provided with invalid input (a lone surrogate).

Example:

  sendPixel 
 ( 
 'https://www.example.com/?' 
  
 + 
  
 encodeUriComponent 
 ( 
 queryInput 
 )); 
 

Syntax

encodeUriComponent(str)

Parameters

Associated permissions

None.

fromBase64

The fromBase64 API lets you to decode strings from their base64 representation. Returns undefined when provided with invalid input.

Syntax

fromBase64(base64EncodedString)

Parameters

Example

  const 
  
 fromBase64 
  
 = 
  
 require 
 ( 
 'fromBase64' 
 ); 
 const 
  
 greeting 
  
 = 
  
 fromBase64 
 ( 
 'aGVsbG8=' 
 ); 
 if 
  
 ( 
 greeting 
  
 === 
  
 'hello' 
 ) 
  
 { 
  
 // ... 
 } 
 

Associated permissions

None

generateRandom

Returns a random number(integer) within the given range.

Syntax

generateRandom(min, max)

Parameters

Associated permissions

None.

getContainerVersion

Returns an objectcontaining data about the current container. The returned object has the following fields:

  { 
  
 co 
 nta 
 i 
 ner 
 Id 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 debugMode 
 : 
  
 boolea 
 n 
 , 
  
 e 
 n 
 viro 
 n 
 me 
 nt 
 Name 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 e 
 n 
 viro 
 n 
 me 
 nt 
 Mode 
 : 
  
 boolea 
 n 
 , 
  
 previewMode 
 : 
  
 boolea 
 n 
 , 
  
 versio 
 n 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
 } 
 

Example

  const 
  
 getContainerVersion 
  
 = 
  
 require 
 ( 
 'getContainerVersion' 
 ); 
 const 
  
 sendPixel 
  
 = 
  
 require 
 ( 
 'sendPixel' 
 ); 
 if 
  
 ( 
 query 
 ( 
 'read_container_data' 
 )) 
  
 { 
  
 const 
  
 cv 
  
 = 
  
 getContainerVersion 
 (); 
  
 const 
  
 pixelUrl 
  
 = 
  
 'https://pixel.com/' 
  
 + 
  
 '?version=' 
  
 + 
  
 cv 
 . 
 version 
  
 + 
  
 '&envName=' 
  
 + 
  
 cv 
 . 
 environmentName 
  
 + 
  
 '&ctid=' 
  
 + 
  
 cv 
 . 
 containerId 
  
 + 
  
 '&debugMode=' 
  
 + 
  
 cv 
 . 
 debugMode 
  
 + 
  
 '&previewMode=' 
  
 + 
  
 cv 
 . 
 previewMode 
 ; 
  
 if 
  
 ( 
 query 
 ( 
 'send_pixel' 
 , 
  
 pixelUrl 
 )) 
  
 { 
  
 sendPixel 
 ( 
 pixelUrl 
 ); 
  
 } 
 } 
 

Syntax

getContainerVersion();

Associated permissions

read_container_data

getCookieValues

Returns the values of all cookies with the given name.

Syntax

getCookieValues(name[, decode])

Parameters

Associated permissions

get_cookies

getQueryParameters

Returns the first or all of the parameters for the current URL's queryKey . Returns the first value from the queryKey or an Array of values from the queryKey .

Syntax

getQueryParameters(queryKey[, retrieveAll])

Parameters

For example, if the current URL is https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo , then:

• getQueryParameters('var') == 'foo'
• getQueryParameters('var', false) == 'foo'
• getQueryParameters('var', null) == 'foo'
• getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Associated permissions

get_url must allow the query component, and must specify the queryKey in the allowed query keys (or allow any query key.)

getReferrerQueryParameters

The getReferrerQueryParameters API acts the same way as getQueryParameters , except it acts on the referrer instead of the current URL. Returns the first or all of the parameters for the given referrer's queryKey . Returns the first value from the queryKey or an Array of values from the queryKey .

Syntax

getReferrerQueryParameters(queryKey[, retrieveAll])

Parameters

For example, if the referrer URL is https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo , then:

• getReferrerQueryParameters('var') == 'foo'
• getReferrerQueryParameters('var', false) == 'foo'
• getReferrerQueryParameters('var', null) == 'foo'
• getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

Associated permissions

get_referrer must allow the query component, and must specify the queryKey in the allowed query keys (or allow any query key.)

getReferrerUrl

Given a component type, the API reads the document object for the referrer and returns a string that represents a portion of the referrer. If no component is specified, full referrer URL is returned.

Syntax

getReferrerUrl([component])

Parameters

Associated permissions

get_referrer must allow the query component, and must specify the queryKey in the allowed query keys (or allow any query key.)

getTimestamp

Deprecated.Prefer getTimestampMillis .

Returns a numberthat represents the current time in milliseconds since Unix epoch, as returned by Date.now() .

Syntax

getTimestamp();

Associated permissions

None.

getTimestampMillis

Returns a numberthat represents the current time in milliseconds since Unix epoch, as returned by Date.now() .

Syntax

getTimestampMillis();

Associated permissions

None.

getType

Returns a stringdescribing the given value's type. Unlike typeof , getType differentiates between array and object .

Syntax

getType(data.someField)

Notes

The following table lists the strings returned for each input value.

Associated permissions

None.

getUrl

Returns a stringthat represents all or a portion of the current URL, given a component type, and some configuration parameters.

Syntax

getUrl(component)

Parameters

Associated permissions

get_url

gtagSet

Pushes a gtag set command to the data layer, to be processed as soon as possible after the current event and any tags it triggered are finished processing (or the tag processing timeout is reached). The update is guaranteed to be processed in this container before any queued items in the data layer queue.

For example, if called by a tag fired on Consent Initialization , the update will be applied before the Initialization event is processed. Examples would be ads_data_redaction being set to true or false or url_passthrough being set to true or false .

Examples:

  const 
  
 gtagSet 
  
 = 
  
 require 
 ( 
 'gtagSet' 
 ); 
 gtagSet 
 ({ 
  
 'ads_data_redaction' 
 : 
  
 true 
 , 
  
 'url_passthrough' 
 : 
  
 true 
 , 
 }); 
 

Syntax

gtagSet(object)

Parameters

Associated permissions

write_data_layer checks write permission to dataLayer for all the specified keys. If input to gtagSet is a plain object, the API will check for write permission to all the flattened keys inside that object, e.g. for gtagSet({foo: {bar: 'baz'}}) , the API will check for write permission to foo.bar .

If the input to gtagSet is a key and some non-plain object value, the API will check for write permission to that key, e.g. for gtagSet('abc', true) , the API will check for write permission to 'abc' .

Note that if there is a cycle in the input object, only keys before reaching the same object will be checked.

injectHiddenIframe

Adds an invisible iframe to the page.

Callbacks are given as function instances, and are wrapped in JavaScript functions that call through to them.

Syntax

injectHiddenIframe(url, onSuccess)

Parameters

Associated permissions

inject_hidden_iframe

injectScript

Adds a script tag to the page to load the given URL asynchronously. The callbacks are given as function instances, and are wrapped in JavaScript functions that call through to them.

Syntax

injectScript(url, onSuccess, onFailure[, cacheToken])

Parameters

Associated permissions

inject_script

isConsentGranted

Returns true if the specified consent type is granted.

Consent for a particular consent type is considered to be granted if the consent type has been set to 'granted' or not set at all. If the consent type is set to any other value it will be considered not granted.

The Tag Manager user interface for tag settings will offer an option to always fire. If a tag with always fire turned on uses this API, consent is considered granted and true will be returned, regardless of the actual state of consent.

Example:

  const 
  
 isConsentGranted 
  
 = 
  
 require 
 ( 
 'isConsentGranted' 
 ); 
 if 
  
 ( 
 isConsentGranted 
 ( 
 'ad_storage' 
 )) 
  
 { 
  
 sendFullPixel 
 (); 
 } 
  
 else 
  
 { 
  
 sendPixelWithoutCookies 
 (); 
 } 
 

Syntax

isConsentGranted(consentType)

Parameters

Associated permissions

access_consent permission with read access for the consent type.

JSON

Returns an object that provides JSON functions.

The parse() function parses a JSON string to construct the value or object described by the string. If the value cannot be parsed (e.g. malformed JSON), the function will return undefined . If the input value is not a string, the input will be coerced to a string.

The stringify() function converts the input into a JSON string. If the value cannot be parsed (e.g. the object has a cycle), the method will return undefined .

Syntax

  JSON 
 . 
 parse 
 ( 
 stringInput 
 ) 
 JSON 
 . 
 stringify 
 ( 
 value 
 ); 
 

Parameters

JSON.parse

JSON.stringify

Example

  const 
  
 JSON 
  
 = 
  
 require 
 ( 
 'JSON' 
 ); 
 // The JSON input string is converted to an object. 
 const 
  
 object 
  
 = 
  
 JSON 
 . 
 parse 
 ( 
 '{"foo":"bar"}' 
 ); 
 // The input object is converted to a JSON string. 
 const 
  
 str 
  
 = 
  
 JSON 
 . 
 stringify 
 ({ 
 foo 
 : 
  
 'bar' 
 }); 
 

localStorage

Returns an object with methods for accessing local storage.

Syntax

  const 
  
 localStorage 
  
 = 
  
 require 
 ( 
 'localStorage' 
 ); 
 // Requires read access for the key. Returns null if the key does not exist. 
 localStorage 
 . 
 getItem 
 ( 
 key 
 ); 
 // Requires write access for the key. Returns true if successful. 
 localStorage 
 . 
 setItem 
 ( 
 key 
 , 
  
 value 
 ); 
 // Requires write access for the key. 
 localStorage 
 . 
 removeItem 
 ( 
 key 
 ); 
 

Associated permissions

access_local_storage

Example

  const 
  
 localStorage 
  
 = 
  
 require 
 ( 
 'localStorage' 
 ); 
 if 
  
 ( 
 localStorage 
 ) 
  
 { 
  
 const 
  
 value 
  
 = 
  
 localStorage 
 . 
 getItem 
 ( 
 'my_key' 
 ); 
  
 if 
  
 ( 
 value 
 ) 
  
 { 
  
 const 
  
 success 
  
 = 
  
 localStorage 
 . 
 setItem 
 ( 
 'my_key' 
 , 
  
 'new_value' 
 ); 
  
 if 
  
 ( 
 success 
 ) 
  
 { 
  
 localStorage 
 . 
 removeItem 
 ( 
 'my_key' 
 ); 
  
 } 
  
 } 
 } 
 

logToConsole

Logs arguments to the browser console.

Syntax

logToConsole(obj1 [, obj2,... objN])

Parameters

Associated permissions

logging

makeInteger

Converts the given value to a number(integer).

Syntax

makeInteger(value)

Parameters

Associated permissions

None.

makeNumber

Converts the given value to a number.

Syntax

makeNumber(value)

Parameters

Associated permissions

None.

makeString

Returns the given value as a string.

Syntax

makeString(value)

Parameters

Associated permissions

None.

makeTableMap

Converts a simple table object with two columns to a Map . This is used to change a SIMPLE_TABLE template field with two columns into a more manageable format.

For example, this function could convert a table object:

  [ 
  
 { 
 'key' 
 : 
  
 'k1' 
 , 
  
 'value' 
 : 
  
 'v1' 
 }, 
  
 { 
 'key' 
 : 
  
 'k2' 
 , 
  
 'value' 
 : 
  
 'v2' 
 } 
 ] 
 

into a Map:

  { 
  
 'k1' 
 : 
  
 'v1' 
 , 
  
 'k2' 
 : 
  
 'v2' 
 } 
 

Returns an Object: The converted Map if key-value pairs have been added to it, or null otherwise.

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parameters

Associated permissions

None.

Math

An object providing Math functions.

Syntax

  const 
  
 Math 
  
 = 
  
 require 
 ( 
 'Math' 
 ); 
 // Retrieve the absolute value. 
 const 
  
 absolute 
  
 = 
  
 Math 
 . 
 abs 
 ( 
 - 
 3 
 ); 
 // Round the input down to the nearest integer. 
 const 
  
 roundedDown 
  
 = 
  
 Math 
 . 
 floor 
 ( 
 3.6 
 ); 
 // Round the input up to the nearest integer. 
 const 
  
 roundedUp 
  
 = 
  
 Math 
 . 
 ceil 
 ( 
 2.2 
 ); 
 // Round the input to the nearest integer. 
 const 
  
 rounded 
  
 = 
  
 Math 
 . 
 round 
 ( 
 3.1 
 ); 
 // Return the largest argument. 
 const 
  
 biggest 
  
 = 
  
 Math 
 . 
 max 
 ( 
 1 
 , 
  
 3 
 ); 
 // Return the smallest argument. 
 const 
  
 smallest 
  
 = 
  
 Math 
 . 
 min 
 ( 
 3 
 , 
  
 5 
 ); 
 // Return the first argument raised to the power of the second argument. 
 const 
  
 powerful 
  
 = 
  
 Math 
 . 
 pow 
 ( 
 3 
 , 
  
 1 
 ); 
 // Return the square root of the argument. 
 const 
  
 unsquared 
  
 = 
  
 Math 
 . 
 sqrt 
 ( 
 9 
 ); 
 

Parameters

Math functions parameters are converted to numbers.

Associated permissions

None.

Object

Returns an object that provides Object methods.

The keys() method provides the Standard Library Object.keys() behavior. It returns an array of a given object's own enumerable property names in the same order that a for...in... loop would. If the input value is not an object, it will be coerced to an object.

The values() method provides the Standard Library Object.values() behavior. It returns an array of a given object's own enumerable property values in the same order that a for...in... loop would. If the input value is not an object, it will be coerced to an object.

The entries() method provides the Standard Library Object.entries() behavior. It returns an array of a given object's own enumerable property [key, value] pairs in the same order that a for...in... loop would. If the input value is an not an object, it will be coerced to an object.

The freeze() method provides the Standard Library Object.freeze() behavior. A frozen object can no longer be changed; freezing an object prevents new properties from being added to it, existing properties from being removed, and the values of existing properties from being changed. freeze() returns the same object that was passed in. A primitive or null argument will be treated as if it were a frozen object, and will be returned.

The delete() method provides the Standard Library delete operator behavior. It removes the given key from the object unless the object is frozen. Like the Standard Library delete operator, it returns true if the first input value ( objectInput ) is an object that is not frozen even if the second input value ( keyToDelete ) specifies a key that does not exist. It returns false in all other cases. However, it differs from the Standard Library delete operator in the following ways:

• keyToDelete cannot be a dot-delimited string that specifies a nested key.
• delete() cannot be used to remove elements from an array.
• delete() cannot be used to remove any properties from the global scope.

Syntax

  Object 
 . 
 keys 
 ( 
 objectInput 
 ) 
 Object 
 . 
 values 
 ( 
 objectInput 
 ) 
 Object 
 . 
 entries 
 ( 
 objectInput 
 ) 
 Object 
 . 
 freeze 
 ( 
 objectInput 
 ) 
 Object 
 . 
 delete 
 ( 
 objectInput 
 , 
  
 keyToDelete 
 ) 
 

Parameters

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Example

  const 
  
 Object 
  
 = 
  
 require 
 ( 
 'Object' 
 ); 
 // The keys of an object are enumerated in an array. 
 const 
  
 keys 
  
 = 
  
 Object 
 . 
 keys 
 ({ 
 foo 
 : 
  
 'bar' 
 }); 
 // The values of an object are enumerated in an array. 
 const 
  
 values 
  
 = 
  
 Object 
 . 
 values 
 ({ 
 foo 
 : 
  
 'bar' 
 }); 
 // The key/value pairs of an object are enumerated in an array. 
 const 
  
 entries 
  
 = 
  
 Object 
 . 
 entries 
 ({ 
 foo 
 : 
  
 'bar' 
 }); 
 // The input object is frozen. 
 const 
  
 frozen 
  
 = 
  
 Object 
 . 
 freeze 
 ({ 
 foo 
 : 
  
 'bar' 
 }); 
 // The key is removed from the input object. 
 const 
  
 obj1 
  
 = 
  
 { 
 deleteme 
 : 
  
 'value' 
 }; 
 Object 
 . 
 delete 
 ( 
 obj1 
 , 
  
 'deleteme' 
 ); 
 // Only a top-level key can be specified as the key to delete. 
 const 
  
 obj2 
  
 = 
  
 { 
 nested 
 : 
  
 { 
 key 
 : 
  
 'value' 
 }}; 
 Object 
 . 
 delete 
 ( 
 obj2 
 , 
  
 'nested.key' 
 ); 
  
 // This has no effect. 
 Object 
 . 
 delete 
 ( 
 obj2 
 . 
 nested 
 , 
  
 'key' 
 ); 
  
 // This deletes the nested key. 
 

parseUrl

Returns an object that contains all of a given URL's component parts, similar to the URL object.

This API will return undefined for any malformed URL. For properly formatted URLs, fields not present in the URL string will have a value of an empty string, or in the case of searchParams , an empty object.

The returned object will have the following fields:

  { 
  
 hre 
 f 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 origi 
 n 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 pro 
 t 
 ocol 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 user 
 na 
 me 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 password 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 hos 
 t 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 hos 
 tna 
 me 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 por 
 t 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 pa 
 t 
 h 
 na 
 me 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 search 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
  
 searchParams 
 : 
  
 Objec 
 t<str 
 i 
 n 
 g 
 , 
  
 (s 
 tr 
 i 
 n 
 g|Array) 
> , 
  
 hash 
 : 
  
 s 
 tr 
 i 
 n 
 g 
 , 
 } 
 

Example

  const 
  
 parseUrl 
  
 = 
  
 require 
 ( 
 'parseUrl' 
 ); 
 const 
  
 urlObject 
  
 = 
  
 parseUrl 
 ( 
 'https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar' 
 ); 
 

Syntax

parseUrl(url);

Parameters

Associated permissions

None.

queryPermission

Query the allowed and narrowed permissions. Returns a boolean: true if a permission is granted, false otherwise.

Syntax

queryPermission(permission, functionArgs*)

Parameters

Function Arguments

sendPixel , injectScript , injectHiddenIframe : The second parameter should be a URL string.

writeGlobals , readGlobals : The second parameter should be the key being written or read.

readUrl : No additional arguments are necessary to query whether the whole URL can be read. To query whether a given component can be read, pass the component name as the second argument:

  if 
  
 ( 
 queryPermission 
 ( 
 'readUrl' 
 , 
 'port' 
 )) 
  
 { 
  
 // read the port 
 } 
 

To check whether a specific query key is readable, pass the query key as the third parameter:

  if 
  
 ( 
 queryPermission 
 ( 
 'readUrl' 
 , 
 'query' 
 , 
 'key' 
 )) 
  
 { 
  
 getUrlComponent 
 (...); 
 } 
 

Associated permissions

None.

readAnalyticsStorage

Retrieves the data stored for analytics and returns an object with client_id and sessions .

• client_id : A string representing the client ID used for analytics.
• sessions : An array of objects containing information about current sessions. Each object includes:
  • measurement_id : A string representing the measurement ID of the Analytics Destination.
  • session_id : A string representing the timestamp that identifies the current session.
  • session_number : A number representing the count of sessions that a user has started up to the current session.

Syntax

  const 
  
 readAnalyticsStorage 
  
 = 
  
 require 
 ( 
 'readAnalyticsStorage' 
 ); 
 const 
  
 cookieOptions 
  
 = 
  
 { 
  
 cookie_prefix 
 : 
  
 "xyz" 
 , 
  
 cookie_domain 
 : 
  
 "google.com" 
 , 
  
 cookie_path 
 : 
  
 "/" 
 , 
 }; 
 readAnalyticsStorage 
 ( 
 cookieOptions 
 ); 
 

Parameters

Associated permissions

read_analytics_storage

Example

  const 
  
 readAnalyticsStorage 
  
 = 
  
 require 
 ( 
 'readAnalyticsStorage' 
 ); 
 const 
  
 analyticsStorageData 
  
 = 
  
 readAnalyticsStorage 
 (); 
 sendOfflineEvent 
 ( 
 analyticsStorageData 
 . 
 client_id 
 , 
  
 "tutorial_begin" 
 ); 
 

readCharacterSet

Returns the value of document.characterSet .

Syntax

readCharacterSet()

Parameters

None.

Associated permissions

read_character_set

readTitle

Returns the value of document.title .

Syntax

readTitle()

Parameters

None.

Associated permissions

read_title

require

Imports a built-in function by name. Returns a functionor an objectthat can be called from your program. Returns undefinedwhen the browser does not support the built-in function.

Syntax

require(name)

Parameters

Example

  const 
  
 getUrl 
  
 = 
  
 require 
 ( 
 'getUrl' 
 ); 
 const 
  
 url 
  
 = 
  
 getUrl 
 (); 
 

Associated permissions

None.

sendPixel

Makes a GET request to a specified URL endpoint.

Syntax

sendPixel(url, onSuccess, onFailure)

Parameters

Associated permissions

send_pixel

setCookie

Sets or deletes the cookie with the specified name, value, and options.

Syntax

setCookie(name, value[, options, encode])

Parameters

Options

• Domain:set by options['domain'] property, if present. Set this value to 'auto' to try to write the cookie using the broadest possible domain, based on the document location. If that fails, it will try successively narrower subdomains. If all of those fail, it will try to write the cookie without a domain. If no value is set, this will try to write the cookie without a domain specified. Note: when a cookie without a domain specified is written to document.cookie , the user agent will default the cookie's domain to the host of the current document location.
• Path:set by options['path'] , if present. When a cookie without a path specified is written to document.cookie , the user agent will default the cookie's path to the path of the current document location.
• Max-Age:set by options['max-age'] , if present.
• Expires:set by options['expires'] , if present. If present, this must be a UTC-formatted date string. Date.toUTCString() can be used to format a Date for this parameter.
• Secure:set by options['secure'] , if present.
• SameSite:set by options['samesite'] , if present.

Associated permissions

set_cookies

setDefaultConsentState

Pushes a default consent update to the data layer, to be processed as soon as possible after the current event and any tags it triggered are finished processing (or the tag processing timeout is reached). The update is guaranteed to be processed in this container before any queued items in the data layer. Learn more about consent .

Example:

  const 
  
 setDefaultConsentState 
  
 = 
  
 require 
 ( 
 'setDefaultConsentState' 
 ); 
 setDefaultConsentState 
 ({ 
  
 'ad_storage' 
 : 
  
 'denied' 
 , 
  
 'analytics_storage' 
 : 
  
 'granted' 
 , 
  
 'third_party_storage' 
 : 
  
 'denied' 
 , 
  
 'region' 
 : 
  
 [ 
 'US-CA' 
 ], 
  
 'wait_for_update' 
 : 
  
 500 
 }); 
 

Syntax

setDefaultConsentState(consentSettings)

Parameters

The consentSettings object is a mapping of arbitrary consent type strings to one of 'granted' or 'denied' . It supports the following values:

Associated permissions

access_consent permission with write access for all consent types in the consentSettings object.

setInWindow

Sets the given value in window at the given key. By default this method won't set the value in the window if there is already a value present. Set overrideExisting to true to set the value in the window regardless of the presence of an existing value. Returns a boolean: true if the value was set successfully, and false otherwise.

Syntax

setInWindow(key, value, overrideExisting)

Parameters

Associated permissions

access_globals

sha256

Calculates the SHA-256 digest of the input and invokes a callback with the digest encoded in base64, unless the options object specifies a different output encoding.

Example:

  sha256 
 ( 
 'inputString' 
 , 
  
 ( 
 digest 
 ) 
  
 = 
>  
 { 
  
 sendPixel 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 digest 
 ); 
  
 data 
 . 
 gtmOnSuccess 
 (); 
 }, 
  
 data 
 . 
 gtmOnFailure 
 ); 
 sha256 
 ( 
 'inputString' 
 , 
  
 ( 
 digest 
 ) 
  
 = 
>  
 { 
  
 sendPixel 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 digest 
 ); 
  
 data 
 . 
 gtmOnSuccess 
 (); 
 }, 
  
 data 
 . 
 gtmOnFailure 
 , 
  
 { 
 outputEncoding 
 : 
  
 'hex' 
 }); 
 

Syntax

sha256(input, onSuccess, onFailure = undefined, options = undefined)

Parameters

Associated permissions

None.

templateStorage

Returns an object with methods for accessing template storage. Template storage allows data to be shared across executions of a single template. Data stored in template storage persists for the lifetime of the page.

Syntax

  const 
  
 templateStorage 
  
 = 
  
 require 
 ( 
 'templateStorage' 
 ); 
 templateStorage 
 . 
 getItem 
 ( 
 key 
 ); 
 templateStorage 
 . 
 setItem 
 ( 
 key 
 , 
  
 value 
 ); 
 templateStorage 
 . 
 removeItem 
 ( 
 key 
 ); 
 // Deletes all stored values for the template. 
 templateStorage 
 . 
 clear 
 (); 
 

Associated permissions

access_template_storage

Example

  const 
  
 templateStorage 
  
 = 
  
 require 
 ( 
 'templateStorage' 
 ); 
 const 
  
 sendPixel 
  
 = 
  
 require 
 ( 
 'sendPixel' 
 ); 
 // Ensure sendPixel is called only once per page. 
 if 
  
 ( 
 templateStorage 
 . 
 getItem 
 ( 
 'alreadyRan' 
 )) 
  
 { 
  
 data 
 . 
 gtmOnSuccess 
 (); 
  
 return 
 ; 
 } 
 templateStorage 
 . 
 setItem 
 ( 
 'alreadyRan' 
 , 
  
 true 
 ); 
 sendPixel 
 ( 
  
 data 
 . 
 oncePerPagePixelUrl 
 , 
  
 data 
 . 
 gtmOnSuccess 
 , 
  
 () 
  
 = 
>  
 { 
  
 templateStorage 
 . 
 setItem 
 ( 
 'alreadyRan' 
 , 
  
 false 
 ); 
  
 data 
 . 
 gtmOnFailure 
 (); 
  
 }); 
 

toBase64

The toBase64 API lets you to encode a string into a base64 representation.

Syntax

toBase64(input)

Parameters

Example

  const 
  
 toBase64 
  
 = 
  
 require 
 ( 
 'toBase64' 
 ); 
 const 
  
 base64Hello 
  
 = 
  
 toBase64 
 ( 
 'hello' 
 ); 
 

Associated permissions

None

updateConsentState

Pushes a consent update to the data layer, to be processed as soon as possible after the current event and any tags it triggered are finished processing (or the tag processing timeout is reached). The update is guaranteed to be processed in this container before any queued items in the data layer. Learn more about consent .

Example:

  const 
  
 updateConsentState 
  
 = 
  
 require 
 ( 
 'updateConsentState' 
 ); 
 updateConsentState 
 ({ 
  
 'ad_storage' 
 : 
  
 'granted' 
 , 
  
 'analytics_storage' 
 : 
  
 'denied' 
 , 
  
 'third_party_storage' 
 : 
  
 'granted' 
 , 
 }); 
 

Syntax

updateConsentState(consentSettings)

Parameters

The consentSettings object is a mapping of arbitrary consent type strings to one of 'granted' or 'denied' . It supports the following values:

Associated permissions

access_consent permission with write access for all consent types in the consentSettings object.

Test APIs

These APIs work with sandboxed JavaScript tests to build tests for custom templates in Google Tag Manager. These test APIs do not need a require() statement. Learn more about custom template tests .

assertApi

Returns a matcher object that can be used to fluently make assertions about the given API.

Syntax

assertApi(apiName)

Parameters

Matchers

• Subject.wasCalled()
• Subject.wasNotCalled()
• Subject.wasCalledWith(...expected)
• Subject.wasNotCalledWith(...expected)

Examples

  assertApi 
 ( 
 'sendPixel' 
 ). 
 wasCalled 
 (); 
 assertApi 
 ( 
 'getUrl' 
 ). 
 wasNotCalled 
 (); 
 assertApi 
 ( 
 'makeNumber' 
 ). 
 wasCalledWith 
 ( 
 '8' 
 ); 
 assertApi 
 ( 
 'setInWindow' 
 ). 
 wasNotCalledWith 
 ( 
 'myVar' 
 , 
  
 'theWrongValue' 
 ); 
 

assertThat

The assertThat API is modeled after Google's [Truth] library. It returns an object that can be used to fluently make assertions about a subject's value. An assertion failure will immediately stop the test and mark it as failed. However, a failure in one test will not affect other test cases.

Syntax

assertThat(actual, opt_message)

Parameters

Matchers

Examples

  assertThat 
 ( 
 undefined 
 ). 
 isUndefined 
 (); 
 assertThat 
 ( 
 id 
 , 
  
 'ID must be defined' 
 ). 
 isDefined 
 (); 
 assertThat 
 ( 
 null 
 ). 
 isNull 
 (); 
 assertThat 
 ( 
 undefined 
 ). 
 isNotNull 
 (); 
 assertThat 
 ( 
 true 
 ). 
 isTrue 
 (); 
 assertThat 
 ( 
 false 
 ). 
 isFalse 
 (); 
 assertThat 
 ( 
 1 
 ). 
 isTruthy 
 (); 
 assertThat 
 ( 
 '' 
 ). 
 isFalsy 
 (); 
 assertThat 
 ( 
 1 
 / 
 0 
 ). 
 isInfinity 
 (); 
 assertThat 
 ( 
 0 
 ). 
 isNotInfinity 
 (); 
 assertThat 
 ( 
 - 
 'foo' 
 ). 
 isNaN 
 (); 
 assertThat 
 ( 
 100 
 ). 
 isNotNaN 
 (); 
 assertThat 
 ( 
 sentUrl 
 ). 
 isEqualTo 
 ( 
 'https://endpoint.example.com/?account=12345' 
 ); 
 assertThat 
 ( 
 category 
 ). 
 isNotEqualTo 
 ( 
 'premium' 
 ); 
 assertThat 
 ( 
 5 
 ). 
 isAnyOf 
 ( 
 1 
 , 
  
 2 
 , 
  
 3 
 , 
  
 4 
 , 
  
 5 
 ); 
 assertThat 
 ( 
 42 
 ). 
 isNoneOf 
 ( 
 'the question' 
 , 
  
 undefined 
 , 
  
 41.9 
 ); 
 assertThat 
 ( 
 'value' 
 ). 
 isStrictlyEqualTo 
 ( 
 'value' 
 ); 
 assertThat 
 ( 
 '4' 
 ). 
 isNotStrictlyEqualTo 
 ( 
 4 
 ); 
 assertThat 
 ([ 
 'a' 
 , 
  
 'b' 
 , 
  
 'c' 
 ]). 
 contains 
 ( 
 'a' 
 , 
  
 'c' 
 ); 
 assertThat 
 ([ 
 'x' 
 , 
  
 'y' 
 , 
  
 'z' 
 ]). 
 doesNotContain 
 ( 
 'f' 
 ); 
 assertThat 
 ([ 
 '1' 
 , 
  
 '2' 
 , 
  
 '3' 
 ]). 
 containsExactly 
 ( 
 '3' 
 , 
  
 '2' 
 , 
  
 '1' 
 ); 
 assertThat 
 ([ 
 '4' 
 , 
  
 '5' 
 ]). 
 doesNotContainExactly 
 ( 
 '4' 
 ); 
 assertThat 
 ( 
 'a string' 
 ). 
 hasLength 
 ( 
 8 
 ); 
 assertThat 
 ([]). 
 isEmpty 
 (); 
 assertThat 
 ( 
 'another string' 
 ). 
 isNotEmpty 
 (); 
 

fail

Immediately fails the current test and prints the given message, if supplied.

Syntax

fail(opt_message);

Parameters

Example

  fail 
 ( 
 'This test has failed.' 
 ); 
 

mock

The mock API allows you to override the behavior of Sandboxed APIs. The mock API is safe to use in template code, but it is operational only in test mode. Mocks are reset before each test is run.

Syntax

mock(apiName, returnValue);

Parameters

Examples

  mock 
 ( 
 'encodeUri' 
 , 
  
 "https://endpoint.example.com/?account=12345" 
 ); 
 mock 
 ( 
 'sendPixel' 
 , 
  
 function 
 ( 
 url 
 , 
  
 onSuccess 
 , 
  
 onFailure 
 ) 
  
 { 
  
 onSuccess 
 (); 
 }); 
 

mockObject

The mockObject API lets you override the behavior of Sandboxed APIs that return an object. The API is safe to use in template code, but it is operational only in test mode. Mocks are reset before each test is run.

Syntax

mockObject(apiName, objectMock);

Parameters

Examples

  const 
  
 storage 
  
 = 
  
 {}; 
 mockObject 
 ( 
 'localStorage' 
 , 
  
 { 
  
 setItem 
 : 
  
 ( 
 key 
 , 
  
 value 
 ) 
  
 = 
>  
 { 
 storage 
 [ 
 key 
 ] 
  
 = 
  
 value 
 ;}, 
  
 getItem 
 : 
  
 ( 
 key 
 ) 
  
 = 
>  
 storage 
 [ 
 key 
 ], 
 }); 
 

runCode

Runs the code for the template, i.e. the content of the Codetab, in the current test environment with a given input data object.

Syntax

runCode(data)

Parameters

Return Value

Returns the value of a variable for variable templates; returns undefined for all other template types.

Example

  runCode 
 ({ 
 field1 
 : 
  
 123 
 , 
  
 field2 
 : 
  
 'value' 
 });