Server-side tagging APIs

This document outlines the APIs for server-side tagging.


addEventCallback

Registers 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. The callback is passed two values: the id of the container that invokes the function and an object that contains information about the event.

When this API is used in a tag, it is associated to the current event. When this API is used in a client, it must be bound to a specific event using the runContainer API's bindToEvent function. See the example for more details.

Syntax

  const 
  
 addEventCallback 
  
 = 
  
 require 
 ( 
 'addEventCallback' 
 ); 
 addEventCallback 
 (( 
 containerId 
 , 
  
 eventData 
 ) 
  
 = 
>  
 { 
  
 // Take some action based on the event data. 
 }); 
 

Parameters

Parameter Type Description
callback
function The function to invoke at the end of the event.

The eventData object contains the following data:

Key Name Type Description
tags
Array An array of tag data objects. Every tag that fired during the event will have an entry in this array. The tag data object contains the tag's ID ( id ), its execution status ( status ), and its execution time ( executionTime ). The tag data will also include additional tag metadata that was configured on the tag.

Example

In a client:

  const 
  
 addEventCallback 
  
 = 
  
 require 
 ( 
 'addEventCallback' 
 ); 
 const 
  
 claimRequest 
  
 = 
  
 require 
 ( 
 'claimRequest' 
 ); 
 const 
  
 extractEventsFromMpv1 
  
 = 
  
 require 
 ( 
 'extractEventsFromMpv1' 
 ); 
 const 
  
 logToConsole 
  
 = 
  
 require 
 ( 
 'logToConsole' 
 ); 
 const 
  
 returnResponse 
  
 = 
  
 require 
 ( 
 'returnResponse' 
 ); 
 const 
  
 runContainer 
  
 = 
  
 require 
 ( 
 'runContainer' 
 ); 
 claimRequest 
 (); 
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv1 
 (); 
 let 
  
 eventsCompleted 
  
 = 
  
 0 
 ; 
 events 
 . 
 forEach 
 (( 
 evt 
 , 
  
 i 
 ) 
  
 = 
>  
 { 
  
 runContainer 
 ( 
 evt 
 , 
  
 /* onComplete= */ 
  
 ( 
 bindToEvent 
 ) 
  
 = 
>  
 { 
  
 bindToEvent 
 ( 
 addEventCallback 
 )(( 
 containerId 
 , 
  
 eventData 
 ) 
  
 = 
>  
 { 
  
 logToConsole 
 ( 
 'Event Number: ' 
  
 + 
  
 i 
 ); 
  
 eventData 
 . 
 tags 
 . 
 forEach 
 (( 
 tag 
 ) 
  
 = 
>  
 { 
  
 logToConsole 
 ( 
 'Tag ID: ' 
  
 + 
  
 tag 
 . 
 id 
 ); 
  
 logToConsole 
 ( 
 'Tag Status: ' 
  
 + 
  
 tag 
 . 
 status 
 ); 
  
 logToConsole 
 ( 
 'Tag Execution Time: ' 
  
 + 
  
 tag 
 . 
 executionTime 
 ); 
  
 }); 
  
 }); 
  
 if 
  
 ( 
 events 
 . 
 length 
  
 === 
  
 ++ 
 eventsCompleted 
 ) 
  
 { 
  
 returnResponse 
 (); 
  
 } 
  
 }); 
 }); 
 

In a tag:

  const 
  
 addEventCallback 
  
 = 
  
 require 
 ( 
 'addEventCallback' 
 ); 
 addEventCallback 
 (( 
 containerId 
 , 
  
 eventData 
 ) 
  
 = 
>  
 { 
  
 // This will be called at the end of the current event. 
 }); 
 

Associated permissions

read_event_metadata


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) .

Example

  const 
  
 callLater 
  
 = 
  
 require 
 ( 
 'callLater' 
 ); 
 const 
  
 logToConsole 
  
 = 
  
 require 
 ( 
 'logToConsole' 
 ); 
 callLater 
 (() 
  
 = 
>  
 { 
  
 logToConsole 
 ( 
 'Logged asynchronously' 
 ); 
 }); 
 

Syntax

callLater(function)

Parameters

Parameter Type Description
function
function The function to call.

Associated permissions

None.


claimRequest

Use this API in a client to claim the request. Once a request is claimed, the container does not run additional clients.

This API throws an exception if called in a tag or variable. This API throws an exception if called after the client returns (e.g. if called in an async callback such as in callLater or the runContainer onComplete function).

A client should claim the request using this API before calling the runContainer API.

Example

  const 
  
 claimRequest 
  
 = 
  
 require 
 ( 
 'claimRequest' 
 ); 
 claimRequest 
 (); 
 

Syntax

  claimRequest 
 (); 
 

Associated permissions

None.


computeEffectiveTldPlusOne

Returns the effective top-level domain + 1 (eTLD+1) of the given domain or URL. The eTLD+1 is computed by evaluating the domain against the Public Suffix List rules. The eTLD+1 is typically the highest-level domain on which you can set a cookie.

If the argument is null or undefined, then the argument value is returned unaltered. Otherwise the argument is coerced to a string. If the argument is not a valid domain or URL, then a blank string is returned. If the server is unable to fetch the public suffix list, then the argument value is returned unaltered.

Example

  const 
  
 computeEffectiveTldPlusOne 
  
 = 
  
 require 
 ( 
 'computeEffectiveTldPlusOne' 
 ); 
 // Returns 'example.co.uk' 
 computeEffectiveTldPlusOne 
 ( 
 'analytics.example.co.uk' 
 ); 
 // Returns 'example.co.uk' 
 computeEffectiveTldPlusOne 
 ( 
 'https://analytics.example.co.uk/path' 
 ); 
 

Syntax

  computeEffectiveTldPlusOne 
 ( 
 domainOrUrl 
 ); 
 

Parameters

Parameter Type Description
domainOrUrl
string A domain or URL on which to compute the eTLD+1.

Associated permissions

None.


createRegex

Creates a new regex instance and returns it wrapped in an object. You cannot access the regex directly. However, you can pass it into the testRegex API, String.replace() , String.match() , and String.search() .

Returns null if the regex is invalid or Re2 is unavailable on the server.

This API uses an Re2 implementation. The server Docker image must be at version 2.0.0 or later.

Example

  const 
  
 createRegex 
  
 = 
  
 require 
 ( 
 'createRegex' 
 ); 
 const 
  
 domainRegex 
  
 = 
  
 createRegex 
 ( 
 '\\w+\\.com' 
 , 
  
 'i' 
 ); 
 // Returns '/foobar' 
 'example.com/foobar' 
 . 
 replace 
 ( 
 domainRegex 
 , 
  
 '' 
 ); 
 

Syntax

  createRegex 
 ( 
 pattern 
 , 
  
 flags 
 ); 
 

Parameters

Parameter Type Description
pattern
string Text of the regular expression.
flags
string An optional string containing the flags for the regex being created. `g` (global) and `i` (ignore case) are supported. All other characters are silently ignored.

Associated permissions

None.

Minimum image version

2.0.0


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 
  
 decodeUri 
  
 = 
  
 require 
 ( 
 'decodeUri' 
 ); 
 const 
  
 decodedUrl 
  
 = 
  
 decodeUri 
 ( 
 data 
 . 
 encodedUrl 
 ); 
 if 
  
 ( 
 decodedUrl 
 ) 
  
 { 
  
 // ... 
 } 
 

Syntax

  decodeUri 
 ( 
 encoded_uri 
 ); 
 

Parameters

Parameter Type Description
encoded_uri
string A URI that has been encoded by encodeUri() or by other means.

Associated permissions

None.


decodeUriComponent

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

Example

  const 
  
 decodeUriComponent 
  
 = 
  
 require 
 ( 
 'decodeUriComponent' 
 ); 
 const 
  
 decodedQuery 
  
 = 
  
 decodeUriComponent 
 ( 
 data 
 . 
 query 
 ); 
 if 
  
 ( 
 decodedQuery 
 ) 
  
 { 
  
 // ... 
 } 
 

Syntax

  decodeUriComponent 
 ( 
 encoded_uri_component 
 ); 
 

Parameters

Parameter Type Description
encoded_uri_component
string A URI component that has been encoded by encodeUriComponent() or by other means.

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.

Example

  const 
  
 encodeUri 
  
 = 
  
 require 
 ( 
 'encodeUri' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 sendHttpGet 
 ( 
 'https://www.example.com/' 
  
 + 
  
 encodeUri 
 ( 
 pathInput 
 )); 
 

Syntax

  encodeUri 
 ( 
 uri 
 ); 
 

Parameters

Parameter Type Description
uri
string A complete URI.

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.

Example

  const 
  
 encodeUriComponent 
  
 = 
  
 require 
 ( 
 'encodeUriComponent' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 sendHttpGet 
 ( 
 'https://www.example.com/?' 
  
 + 
  
 encodeUriComponent 
 ( 
 queryInput 
 )); 
 

Syntax

  encodeUriComponent 
 ( 
 str 
 ); 
 

Parameters

Parameter Type Description
str
string A component of a URI.

Associated permissions

None.


extractEventsFromMpv1

Translates an incoming Measurement Protocol V1 request into a list of events in Unified Schema format. Returns the list of extracted events. Throws an error if the request is not in the correct format.

Example

  const 
  
 extractEventsFromMpv1 
  
 = 
  
 require 
 ( 
 'extractEventsFromMpv1' 
 ); 
 const 
  
 isRequestMpv1 
  
 = 
  
 require 
 ( 
 'isRequestMpv1' 
 ); 
 if 
  
 ( 
 isRequestMpv1 
 ()) 
  
 { 
  
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv1 
 (); 
  
 for 
  
 ( 
 let 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 events 
 . 
 length 
 ; 
  
 ++ 
 i 
 ) 
  
 { 
  
 const 
  
 event 
  
 = 
  
 events 
 [ 
 i 
 ]; 
  
 // Process event. 
  
 } 
 } 
 

Syntax

  extractEventsFromMpv1 
 (); 
 

Associated permissions

Requires read_request permission. The permission must be configured to permit access to at least:

  • body
  • query parameters

extractEventsFromMpv2

Translates an incoming Measurement Protocol V2 request into a list of events in Unified Schema format. Returns the list of extracted events. Throws an error if the request is not in the correct format.

Example

  const 
  
 extractEventsFromMpv2 
  
 = 
  
 require 
 ( 
 'extractEventsFromMpv2' 
 ); 
 const 
  
 isRequestMpv2 
  
 = 
  
 require 
 ( 
 'isRequestMpv2' 
 ); 
 if 
  
 ( 
 isRequestMpv2 
 ()) 
  
 { 
  
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv2 
 (); 
  
 for 
  
 ( 
 let 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 events 
 . 
 length 
 ; 
  
 ++ 
 i 
 ) 
  
 { 
  
 const 
  
 event 
  
 = 
  
 events 
 [ 
 i 
 ]; 
  
 // Process event. 
  
 } 
 } 
 

Syntax

  extractEventsFromMpv2 
 (); 
 

Associated permissions

Requires read_request permission. The permission must be configured to permit access to at least:

  • body
  • query parameters

fromBase64

Decodes a base64-encoded string. Returns undefined if the input is invalid.

Syntax

 fromBase64(base64EncodedString); 

Parameters

Parameter Type Description
base64EncodedString
string Base64 encoded string.

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.

Example

  const 
  
 generateRandom 
  
 = 
  
 require 
 ( 
 'generateRandom' 
 ); 
 const 
  
 randomValue 
  
 = 
  
 generateRandom 
 ( 
 0 
 , 
  
 10000000 
 ); 
 

Syntax

  generateRandom 
 ( 
 min 
 , 
  
 max 
 ); 
 

Parameters

Parameter Type Description
min
number Minimum potential value of the returned integer (inclusive).
max
number Maximum potential value of the returned integer (inclusive).

Associated permissions

None.


getAllEventData

Returns a copy of the event data.

Syntax

  getAllEventData 
 (); 
 

Associated permissions

read_event_data


getClientName

Returns a stringthat contains the name of the current client.

Syntax

  getClientName 
 (); 
 

Associated permissions

read_container_data


getContainerVersion

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

  { 
  
 containerId 
 : 
  
 string 
 , 
  
 debugMode 
 : 
  
 boolean 
 , 
  
 environmentName 
 : 
  
 string 
 , 
  
 environmentMode 
 : 
  
 boolean 
 , 
  
 previewMode 
 : 
  
 boolean 
 , 
  
 version 
 : 
  
 string 
 , 
 } 
 

Example

  const 
  
 getContainerVersion 
  
 = 
  
 require 
 ( 
 'getContainerVersion' 
 ); 
 const 
  
 containerVersion 
  
 = 
  
 getContainerVersion 
 (); 
 const 
  
 containerId 
  
 = 
  
 containerVersion 
 [ 
 'containerId' 
 ]; 
 const 
  
 isDebug 
  
 = 
  
 containerVersion 
 [ 
 'debugMode' 
 ]; 
 

Syntax

  getContainerVersion 
 (); 
 

Associated permissions

read_container_data


getCookieValues

Returns an array containing the values of all cookies with the given name.

Example

  const 
  
 getCookieValues 
  
 = 
  
 require 
 ( 
 'getCookieValues' 
 ); 
 const 
  
 lastVisit 
  
 = 
  
 getCookieValues 
 ( 
 'lastVisit' 
 )[ 
 0 
 ]; 
 if 
  
 ( 
 lastVisit 
 ) 
  
 { 
  
 // ... 
 } 
 

Syntax

  getCookieValues 
 ( 
 name 
 [, 
  
 noDecode 
 ]); 
 

Parameters

Parameter Type Description
name
string Name of the cookie.
noDecode
boolean If true , the cookie values will not be decoded before being returned. Defaults to false .

Associated permissions

get_cookies


getEventData

Returns a copy of the value at the given path in the event data. Returns undefined if there is no event data or if there is no value at the given path.

Example

  const 
  
 getEventData 
  
 = 
  
 require 
 ( 
 'getEventData' 
 ); 
 const 
  
 campaignId 
  
 = 
  
 getEventData 
 ( 
 'campaign.id' 
 ); 
 const 
  
 itemId 
  
 = 
  
 getEventData 
 ( 
 'items.0.id' 
 ); 
 const 
  
 referrer 
  
 = 
  
 getEventData 
 ( 
 'page_referrer' 
 ); 
 

Parameters

Parameter Type Description
keyPath
any The path of the key, where path components are separated by dots. The path components can be keys in an object or indices in an array. If keyPath is not a string, it is coerced into a string.

Syntax

  getEventData 
 ( 
 keyPath 
 ); 
 

Associated permissions

read_event_data


getGoogleAuth

Returns an authorization object that when used with sendHttpGet or sendHttpRequest , will include an authorization header for Google Cloud APIs. This API uses Application Default Credentials to automatically find credentials from the server environment.

Example

  const 
  
 getGoogleAuth 
  
 = 
  
 require 
 ( 
 'getGoogleAuth' 
 ); 
 const 
  
 logToConsole 
  
 = 
  
 require 
 ( 
 'logToConsole' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 const 
  
 auth 
  
 = 
  
 getGoogleAuth 
 ({ 
  
 scopes 
 : 
  
 [ 
 'https://www.googleapis.com/auth/datastore' 
 ] 
 }); 
 sendHttpGet 
 ( 
  
 'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document' 
 , 
  
 { 
 authorization 
 : 
  
 auth 
 } 
 ). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 result 
 . 
 statusCode 
  
> = 
  
 200 
 && 
 result 
 . 
 statusCode 
 < 
 300 
 ) 
  
 { 
  
 logToConsole 
 ( 
 'Result: ' 
  
 + 
  
 result 
 . 
 body 
 ); 
  
 data 
 . 
 gtmOnSuccess 
 (); 
  
 } 
  
 else 
  
 { 
  
 data 
 . 
 gtmOnFailure 
 (); 
  
 } 
 }); 
 

Syntax

  getGoogleAuth 
 ( 
 scopes 
 ); 
 

Parameters

Parameter Type Description
scopes
Array An array of OAuth 2.0 Google API scopes to request access for.

Associated permissions

Requires use_google_credentials permission. The permission must be configured with one or more allowed scopes.


getGoogleScript

Retrieves a resource from a predetermined set of Google scripts, and returns a promise with the script and associated caching metadata.

The promise will resolve to an object containing two keys: script and metadata . If the request fails, the promise will reject with a reason key.

The metadata object will contain the following caching metadata based on the resource response headers; each field will only be present if the corresponding header is present in the resource response.

  { 
  
 'cache-control' 
 : 
  
 string 
 , 
  
 'expires' 
 : 
  
 string 
 , 
  
 'last-modified' 
 : 
  
 string 
 , 
 } 
 

Example

  const 
  
 getGoogleScript 
  
 = 
  
 require 
 ( 
 'getGoogleScript' 
 ); 
 getGoogleScript 
 ( 
 'ANALYTICS' 
 ). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 { 
  
 // Operate on result.script and result.metadata here. 
 }); 
 

Syntax

  getGoogleScript 
 ( 
 script 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
script
string The name of the script. Supported scripts are 'ANALYTICS' , 'GTAG' , and 'GTM' .

The 'ANALYTICS' option fetches the Google Analytics script from https://www.google-analytics.com/analytics.js .

The 'GTAG' option fetches the global site tag (gtag.js) script from https://www.googletagmanager.com/gtag/js .

The 'GTM' option fetches the Google Tag Manager script from https://www.googletagmanager.com/gtm.js .
options
object Optional request options. See below for supported options.

Options

Option Type Description
id
string Applicable to 'GTAG' with the gtag measurement ID and 'GTM' with the web container ID (ex. GTM-XXXX).
debug
any If truthy, requests and returns the debug version of the measurement script.
timeout
number The request timeout in milliseconds; non-positive values are ignored. If the request times out, the callback will be invoked with undefined for the script value and {} for the metadata object.

Unrecognized option keys are ignored.

Associated permissions

Requires send_http permission. The permission must be configured to permit access to at least:

  • Allow Google Domains

getRemoteAddress

Returns a stringrepresentation of the IP address where the request originated, e.g. 12.345.67.890 for IPv4 or 2001:0db8:85a3:0:0:8a2e:0370:7334 for IPv6, by reading request headers such as Forwarded and X-Forwarded-For. Note: this API makes a best-effort attempt to discover the originating IP, but it cannot guarantee that the result is accurate.

Syntax

  getRemoteAddress 
 (); 
 

Associated permissions

Requires read_request permission. The permission must be configured to permit access to at least:

  • Headers Forwarded and X-Forwarded-For
  • Remote IP Address

getRequestBody

Returns the request body as a string, if present, or undefined otherwise.

Syntax

  getRequestBody 
 (); 
 

Associated permissions

read_request


getRequestHeader

Returns the value of the named request header as a string, if present, or undefined otherwise. If the header is repeated, the returned values are joined together with ', ' .

Example

  const 
  
 getRequestHeader 
  
 = 
  
 require 
 ( 
 'getRequestHeader' 
 ); 
 const 
  
 host 
  
 = 
  
 getRequestHeader 
 ( 
 'host' 
 ); 
 

Syntax

  getRequestHeader 
 ( 
 headerName 
 ); 
 

Parameters

Parameter Type Description
headerName
string The header name. This value is case-insensitive.

Associated permissions

read_request


getRequestMethod

Returns the request method, e.g. 'GET' or 'POST' , as a string.

Example

  const 
  
 getRequestMethod 
  
 = 
  
 require 
 ( 
 'getRequestMethod' 
 ); 
 if 
  
 ( 
 getRequestMethod 
 () 
  
 === 
  
 'POST' 
 ) 
  
 { 
  
 // Handle the POST request here. 
 } 
 

Syntax

  getRequestMethod 
 (); 
 

Associated permissions

None.


getRequestPath

Returns the request path without the query string. For example, if the URL is '/foo?id=123' , this returns '/foo' . Automatically strips the Server container URL prefix from the path. For example, if Server container URL is https://example.com/analytics and the request path is '/analytics/foo' , this returns '/foo' .

Example

  const 
  
 getRequestPath 
  
 = 
  
 require 
 ( 
 'getRequestPath' 
 ); 
 const 
  
 requestPath 
  
 = 
  
 getRequestPath 
 (); 
 if 
  
 ( 
 requestPath 
  
 === 
  
 '/' 
 ) 
  
 { 
  
 // Handle a request for the root path. 
 } 
 

Syntax

  getRequestPath 
 (); 
 

Associated permissions

read_request


getRequestQueryParameter

Returns the decoded value of the named query string parameter as a string, or undefined if the parameter is not present. If the parameter is repeated in the query string, the first value that appears in the query string will be returned.

Example

  const 
  
 getRequestQueryParameter 
  
 = 
  
 require 
 ( 
 'getRequestQueryParameter' 
 ); 
 const 
  
 query 
  
 = 
  
 getRequestQueryParameter 
 ( 
 'query' 
 ); 
 if 
  
 ( 
 query 
 ) 
  
 { 
  
 // Process query here. 
 } 
 

Syntax

  getRequestQueryParameter 
 ( 
 name 
 ); 
 

Parameters

Parameter Type Description
name
string The query parameter name.

Associated permissions

read_request


getRequestQueryParameters

Returns the incoming HTTP request's query parameters as an object that maps query parameter names to the corresponding value or values. The parameter names and values are decoded.

Example

  const 
  
 getRequestQueryParameters 
  
 = 
  
 require 
 ( 
 'getRequestQueryParameters' 
 ); 
 const 
  
 queryParameters 
  
 = 
  
 getRequestQueryParameters 
 (); 
 if 
  
 ( 
 queryParameters 
 [ 
 'search' 
 ]) 
  
 { 
  
 // Handle the search query here. 
  
 const 
  
 maxResults 
  
 = 
  
 queryParameters 
 [ 
 'max_results' 
 ]; 
 } 
 

Syntax

  getRequestQueryParameters 
 (); 
 

Associated permissions

read_request


getRequestQueryString

Returns the request query as a string, without the leading question mark, or an empty string if the request URL does not include a query string.

Example

  const 
  
 getRequestQueryString 
  
 = 
  
 require 
 ( 
 'getRequestQueryString' 
 ); 
 const 
  
 queryString 
  
 = 
  
 getRequestQueryString 
 (); 
 if 
  
 ( 
 queryString 
  
 !== 
  
 '' 
 ) 
  
 { 
  
 // Handle the query string. 
 } 
 

Syntax

  getRequestQueryString 
 (); 
 

Associated permissions

read_request


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 string describing the given value's type.

Input Type Returned Value
string 'string'
number 'number'
boolean 'boolean'
null 'null'
undefined 'undefined'
Array 'array'
Object 'object'
Function 'function'

Example

  const 
  
 getType 
  
 = 
  
 require 
 ( 
 'getType' 
 ); 
 const 
  
 type 
  
 = 
  
 getType 
 ( 
 value 
 ); 
 if 
  
 ( 
 type 
  
 === 
  
 'string' 
 ) 
  
 { 
  
 // Handle string input. 
 } 
  
 else 
  
 if 
  
 ( 
 type 
  
 === 
  
 'number' 
 ) 
  
 { 
  
 // Handle numeric input. 
 } 
  
 else 
  
 { 
  
 logToConsole 
 ( 
 'Unsupported input type: ' 
 , 
  
 type 
 ); 
 } 
 

Syntax

  getType 
 ( 
 value 
 ); 
 

Parameters

Parameter Type Description
value
any Input value.

Associated permissions

None.


hmacSha256

Calculates an encoded signature using Hash-based Message Authentication Code (HMAC) with SHA-256. Defaults to base64url encoding.

To use this API, set the SGTM_CREDENTIALS environment variable on the server to the path of a UTF-8 encoded JSON key file with the following format:

  { 
  
 "keys" 
 : 
  
 { 
  
 "key1" 
 : 
  
 "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5" 
 , 
  
 "key2" 
 : 
  
 "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh" 
 , 
  
 ... 
  
 } 
 } 
 

The values are base64-encoded HMAC keys. The JSON text must not start with a byte order marker.

Example

  const 
  
 hmacSha256 
  
 = 
  
 require 
 ( 
 'hmacSha256' 
 ); 
 const 
  
 toBase64 
  
 = 
  
 require 
 ( 
 'toBase64' 
 ); 
 const 
  
 header 
  
 = 
  
 toBase64 
 ( 
 '{"alg":"HS256","typ":"JWT"}' 
 , 
  
 { 
 urlEncoding 
 : 
  
 true 
 }); 
 const 
  
 claim 
  
 = 
  
 toBase64 
 ( 
 '{"sub":"1234567890","iat":1698164946}' 
 , 
  
 { 
 urlEncoding 
 : 
  
 true 
 }); 
 const 
  
 signature 
  
 = 
  
 hmacSha256 
 ( 
 header 
  
 + 
  
 '.' 
  
 + 
  
 claim 
 , 
  
 'key1' 
 ); 
 const 
  
 jwt 
  
 = 
  
 header 
  
 + 
  
 "." 
  
 + 
  
 claim 
  
 + 
  
 '.' 
  
 + 
  
 signature 
 ; 
 

Syntax

  hmacSha256 
 ( 
 data 
 , 
  
 keyId 
 , 
  
 options 
 ) 
 

Parameters

Parameter Type Description
data
string The data to compute the HMAC value.
keyId
string A key id from the JSON key file referring to the key to use.
options
object Optional API configuration. (See Options below.)

Options

Option Type Description
outputEncoding
string Specifies the encoding format for the return value. Supported formats are hex , base64 , or base64url . Defaults to base64url if not specified.

Associated permissions

use_custom_private_keys

Minimum image version

1.0.0


isRequestMpv1

Returns true if the incoming request is a Measurement Protocol V1 request, or false otherwise.

Example

  const 
  
 isRequestMpv1 
  
 = 
  
 require 
 ( 
 'isRequestMpv1' 
 ); 
 if 
  
 ( 
 isRequestMpv1 
 ()) 
  
 { 
  
 // Handle Measurement Protocol V1 request. 
  
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv1 
 (); 
 } 
 

Syntax

  isRequestMpv1 
 (); 
 

Associated permissions

None.


isRequestMpv2

Returns true if the incoming request is a Measurement Protocol V2 request, or false otherwise.

Example

  const 
  
 isRequestMpv2 
  
 = 
  
 require 
 ( 
 'isRequestMpv2' 
 ); 
 if 
  
 ( 
 isRequestMpv2 
 ()) 
  
 { 
  
 // Handle Measurement Protocol V2 request. 
  
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv2 
 (); 
 } 
 

Syntax

  isRequestMpv2 
 (); 
 

Associated permissions

None.


logToConsole

Logs its argument(s) to the console.

These logs are visible within Logs Explorer in the Google Cloud Console. From Logs Explorer run the query logName =~ "stdout" to see log entries created by this API.

Example

  const 
  
 logToConsole 
  
 = 
  
 require 
 ( 
 'logToConsole' 
 ); 
 const 
  
 that 
  
 = 
  
 123 
 ; 
 const 
  
 those 
  
 = 
  
 { 
  
 ... 
  
 }; 
 logToConsole 
 ( 
 'that is: ' 
 , 
  
 that 
 , 
  
 ' and those is: ' 
 , 
  
 those 
 ); 
 

Syntax

  logToConsole 
 ( 
 argument1 
 [, 
  
 argument2 
 , 
  
 ...]); 
 

Parameters

The API takes one or more arguments, each of which is converted to a string, if necessary, and logged to the console.

Associated permissions

logging


makeInteger

Converts the given value to a number(integer).

Syntax

  makeInteger 
 ( 
 value 
 ); 
 

Parameters

Parameter Type Description
value
any type The value to convert.

Associated permissions

None.


makeNumber

Converts the given value to a number.

Syntax

  makeNumber 
 ( 
 value 
 ); 
 

Parameters

Parameter Type Description
value
any type The value to convert.

Associated permissions

None.


makeString

Returns the given value as a string.

Syntax

  makeString 
 ( 
 value 
 ); 
 

Parameters

Parameter Type Description
value
any type The value to convert.

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 of key-value pairs have been added to it, or null otherwise.

Syntax

  makeTableMap 
 ( 
 tableObj 
 , 
  
 keyColumnName 
 , 
  
 valueColumnName 
 ); 
 

Parameters

Parameter Type Description
tableObj
List The table object to convert. It's a list of maps where each Map represents a row in the table. Each property name in a row object is the column name, and the property value is the column value in the row.
keyColumnName
string Name of the column whose values will become keys in the converted Map .
valueColumnName
string Name of the column whose values will become values in the converted Map .

Associated permissions

None.


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:

  { 
  
 href 
 : 
  
 string 
 , 
  
 origin 
 : 
  
 string 
 , 
  
 protocol 
 : 
  
 string 
 , 
  
 username 
 : 
  
 string 
 , 
  
 password 
 : 
  
 string 
 , 
  
 host 
 : 
  
 string 
 , 
  
 hostname 
 : 
  
 string 
 , 
  
 port 
 : 
  
 string 
 , 
  
 pathname 
 : 
  
 string 
 , 
  
 search 
 : 
  
 string 
 , 
  
 searchParams 
 : 
  
 Object<string 
 , 
  
 ( 
 string 
 | 
 Array 
 )>, 
  
 hash 
 : 
  
 string 
 , 
 } 
 

Example

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

Syntax

  parseUrl 
 ( 
 url 
 ); 
 

Parameters

Parameter Type Description
url
string The full url that will be parsed.

Associated permissions

None.


returnResponse

Flushes the response that was previously set by other templates using the APIs that modify the response, including setCookie , setPixelResponse , setResponseBody , setResponseHeader , and setResponseStatus . Defaults to an HTTP status code 200, empty body, and no headers.

It is recommended that this API be used from a client template.

Syntax

  returnResponse 
 (); 
 

Example

See the runContainer example .

Associated permissions

return_response


runContainer

Runs the container logic (variables, triggers, tags) in the scope of an event. If this API is called during container execution, the container is run again.

The onComplete and onStart callbacks receive a function called bindToEvent . Use bindToEvent to run an API in the context of the event. See the addEventCallback example for more details.

It is recommended that this API be used from a client template.

Example

  const 
  
 returnResponse 
  
 = 
  
 require 
 ( 
 'returnResponse' 
 ); 
 const 
  
 runContainer 
  
 = 
  
 require 
 ( 
 'runContainer' 
 ); 
 // Runs the container with a simple pageview event and then returns a response. 
 runContainer 
 ({ 
 'event_name' 
 : 
  
 'pageview' 
 }, 
  
 () 
  
 = 
>  
 returnResponse 
 ()); 
 

Syntax

  runContainer 
 ( 
 event 
 , 
  
 onComplete 
 , 
  
 onStart 
 ); 
 

Parameters

Parameter Type Description
event
object The event parameters.
onComplete
function A callback that is invoked after all the tags finish firing.
onStart
function A callback that is invoked immediately, before the tags start firing.

Associated permissions

run_container


sendEventToGoogleAnalytics

Sends a single event using Common Event Data to Google Analytics and returns a promise that resolves to an object with a location key or rejects to an object with a reason key. The destination, Google Analytics 4, is based on the measurement ID in the event data.

The location field is set to the location header, if present.

Example

  const 
  
 logToConsole 
  
 = 
  
 require 
 ( 
 'logToConsole' 
 ); 
 const 
  
 sendEventToGoogleAnalytics 
  
 = 
  
 require 
 ( 
 'sendEventToGoogleAnalytics' 
 ); 
 const 
  
 setResponseHeader 
  
 = 
  
 require 
 ( 
 'setResponseHeader' 
 ); 
 const 
  
 setResponseStatus 
  
 = 
  
 require 
 ( 
 'setResponseStatus' 
 ); 
 // Sends an event to Google Analytics and returns failure if the request did not 
 // succeed. Additionally, if the request resulted in a redirect request, the 
 // code nominates a redirect response to be returned. 
 sendEventToGoogleAnalytics 
 ( 
 event 
 ). 
 then 
 (( 
 response 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 response 
 . 
 location 
 ) 
  
 { 
  
 setResponseHeader 
 ( 
 'location' 
 , 
  
 response 
 . 
 location 
 ); 
  
 setResponseStatus 
 ( 
 302 
 ); 
  
 } 
  
 else 
  
 { 
  
 setResponseStatus 
 ( 
 200 
 ); 
  
 } 
  
 data 
 . 
 gtmOnSuccess 
 (); 
 }). 
 catch 
 (( 
 error 
 ) 
  
 = 
>  
 { 
  
 logToConsole 
 ( 
 error 
 . 
 reason 
 ); 
  
 setResponseStatus 
 ( 
 500 
 ); 
  
 data 
 . 
 gtmOnFailure 
 (); 
 }); 
 

Syntax

  sendEventToGoogleAnalytics 
 ( 
 event 
 ); 
 

Parameters

Parameter Type Description
event
object The event in Unified Schema format.

Associated permissions

Requires send_http permission. The permission must be configured to permit access to at least:

  • Allow Google Domains

sendHttpGet

Makes an HTTP GET request to the specified URL, and returns a promise that resolves with the result once the request completes or times out.

The resolved result is an object containing three keys: statusCode , headers , and body . If the request failed (e.g. invalid URL, no route to host, SSL negotiation failure, etc.), the promise will reject with: {reason: 'failed'} . If the timeout option was set and the request timed out, the promise will reject with: {reason: 'timed_out'}

Example

  const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 // Returns the response body as the value for a variable. 
 return 
  
 sendHttpGet 
 ( 
 'https://example.com/item/' 
  
 + 
  
 data 
 . 
 itemId 
 , 
  
 { 
  
 headers 
 : 
  
 { 
 key 
 : 
  
 'value' 
 }, 
  
 timeout 
 : 
  
 500 
 , 
 }). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 result 
 . 
 body 
 , 
  
 () 
  
 = 
>  
 undefined 
 ); 
 

Syntax

  sendHttpGet 
 ( 
 url 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
url
string The requested URL.
options
object Optional request options. (See Options below.)

Options

Option Type Description
headers
string Additional request headers.
timeout
number The timeout, in milliseconds, before the request is aborted. Defaults to 15000 .
authorization
object Optional authorization object from the call to getGoogleAuth for including authorization headers when making requests to googleapis.com .

Associated permissions

send_http


sendHttpRequest

Makes an HTTP request to the specified URL, and returns a promise that resolves with the response once the request completes or times out.

The resolved result is an object containing three keys: statusCode , headers , and body . If the request failed (e.g. invalid URL, no route to host, SSL negotiation failure, etc.), the promise will reject with: {reason: 'failed'} . If the timeout option was set and the request timed out, the promise will reject with: {reason: 'timed_out'}

Example

  const 
  
 sendHttpRequest 
  
 = 
  
 require 
 ( 
 'sendHttpRequest' 
 ); 
 const 
  
 setResponseBody 
  
 = 
  
 require 
 ( 
 'setResponseBody' 
 ); 
 const 
  
 setResponseHeader 
  
 = 
  
 require 
 ( 
 'setResponseHeader' 
 ); 
 const 
  
 setResponseStatus 
  
 = 
  
 require 
 ( 
 'setResponseStatus' 
 ); 
 const 
  
 postBody 
  
 = 
  
 'interaction=click&campaign=promotion&medium=email' 
 ; 
 // Sends a POST request and nominates response based on the response to the POST 
 // request. 
 sendHttpRequest 
 ( 
 'https://example.com/collect' 
 , 
  
 { 
  
 headers 
 : 
  
 { 
 key 
 : 
  
 'value' 
 }, 
  
 method 
 : 
  
 'POST' 
 , 
  
 timeout 
 : 
  
 500 
 , 
 }, 
  
 postBody 
 ). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 { 
  
 setResponseStatus 
 ( 
 result 
 . 
 statusCode 
 ); 
  
 setResponseBody 
 ( 
 result 
 . 
 body 
 ); 
  
 setResponseHeader 
 ( 
 'cache-control' 
 , 
  
 result 
 . 
 headers 
 [ 
 'cache-control' 
 ]); 
 }); 
 

Syntax

  sendHttpRequest 
 ( 
 url 
 [, 
  
 options 
 [, 
  
 body 
 ]]); 
 

Parameters

Parameter Type Description
url
string The requested URL.
options
object Optional request options. (See Options below.)
body
string Optional request body.

Options

Option Type Description
headers
string Additional request headers.
method
object The request method. Defaults to GET .
timeout
number The timeout, in milliseconds, before the request is aborted. Defaults to 15000 .
authorization
object Optional authorization object from the call to getGoogleAuth for including authorization headers when making requests to googleapis.com .

Associated permissions

send_http


sendPixelFromBrowser

Sends a command to the browser to load the provided URL as an <img> tag. This command protocol is supported in the Google Tagfor GA4 and Google Analytics: GA Eventweb tags. You must configure the server container URL. See the instructions for more details.

This API returns false if the incoming request does not support the command protocol, or if the response has already been flushed. Otherwise this API returns true .

Example:

  const 
  
 sendPixelFromBrowser 
  
 = 
  
 require 
 ( 
 'sendPixelFromBrowser' 
 ); 
 sendPixelFromBrowser 
 ( 
 'https://example.com/?id=123' 
 ); 
 

Syntax

sendPixelFromBrowser(url)

Parameters

Parameter Type Description
url
string The url to send to the browser.

Associated permissions

send_pixel_from_browser


setCookie

Sets or deletes a cookie with the specified options.

To delete a cookie, one must set a cookie with the same path and domain that the cookie was created with, and assign it an expires value that is in the past, e.g. "Thu, 01 Jan 1970 00:00:00 GMT" .

Note that returnResponse must be called for the response to be sent back to the client.

Example

  const 
  
 setCookie 
  
 = 
  
 require 
 ( 
 'setCookie' 
 ); 
 // Sets an httpOnly cookie with a max-age of 3600. 
 setCookie 
 ( 
 'cookieName' 
 , 
  
 'cookieValue' 
 , 
  
 { 
 'max-age' 
 : 
  
 3600 
 , 
  
 httpOnly 
 : 
  
 true 
 }); 
 

Syntax

  setCookie 
 ( 
 name 
 , 
  
 value 
 [, 
  
 options 
 [, 
  
 noEncode 
 ]]); 
 

Parameters

Parameter Type Description
name
string The cookie name. The name is case-insensitive.
value
string The cookie value.
options
object Optional cookie attributes: domain, expires, fallbackDomain, httpOnly, max- age, path, secure, and sameSite. (See Options , below.)
noEncode
boolean If true, the cookie value will not be encoded. Defaults to false .

Options

  • domain:The host to which the cookie will be sent. If set to the special value 'auto', then the host will be automatically computed using the following strategy:

    • eTLD+1 of Forwarded header, if present.
    • eTLD+1 of X-Forwarded-Host header, if present.
    • eTLD+1 of Host header.
  • expires: The maximum lifetime of the cookie. This must a UTC-formatted date string, e.g. "Sat, 26 Oct 1985 08:21:00 GMT". If both expires and max-age are set, max-age has precedence.

  • httpOnly: Forbids JavaScript from accessing the cookie if true .

  • max-age: Number of seconds until the cookie expires. A zero or negative number will expire the cookie immediately. If both expires and max-age are set, max-age has precedence.

  • path: A path that must exist in the requested URL, or the browser won't send the Cookie header.

  • secure: If set to true , the cookie is only sent to the server when a request is made from an https: endpoint.

  • sameSite: Asserts that a cookie must not be sent with cross-origin requests. Must be 'strict' , 'lax' , or 'none' .

Associated permissions

set_cookie


setPixelResponse

Sets response body to a 1x1 GIF, sets the Content-Type header to 'image/gif', sets caching headers such that user agents will not cache the response, and sets the response status to 200.

Note that returnResponse must be called for the response to be sent back to the client.

Syntax

  setPixelResponse 
 (); 
 

Associated permissions

Requires access_response permission. The permission must be configured to permit access to at least:

  • headers - Must permit the following keys
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

Sets the response body to the argument.

Note that returnResponse must be called for the response to be sent back to the client.

Syntax

  setResponseBody 
 ( 
 body 
 [, 
  
 encoding 
 ]); 
 

Parameters

Parameter Type Description
body
string The value to set as the response body.
encoding
string The character encoding of the response body (defaults to 'utf8' ). Supported values include 'ascii' , 'utf8' , 'utf16le' , 'ucs2' , 'base64' , 'latin1' , 'binary' , and 'hex' .

Associated permissions

Requires access_response permission. The permission must be configured to permit access to at least:

  • body

setResponseHeader

Sets a header in the response that will be returned. If a header with this name (case-insensitive) was previously set by this API, the latter call will overwrite or clear the value set by the prior caller.

Note that returnResponse must be called for the response to be sent back to the client.

Syntax

  setResponseHeader 
 ( 
 name 
 , 
  
 value 
 ); 
 

Parameters

Parameter Type Description
name
string The header name. HTTP header names are case-insensitive, so the header name will be lowercased.
value
string undefined The header value. If null or undefined, this clears the named header from the response that will be returned.

Associated permissions

Requires access_response permission. The permission must be configured to permit access to at least:

  • headers

setResponseStatus

Sets the HTTP status code of the response that will be returned.

Note that returnResponse must be called for the response to be sent back to the client.

Syntax

  setResponseStatus 
 ( 
 statusCode 
 ); 
 

Parameters

Parameter Type Description
statusCode
number The HTTP status code to be returned.

Associated permissions

Requires access_response permission. The permission must be configured to permit access to at least:

  • status

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.

This API signature and behavior matches the sha256 API for web containers; however, Custom Templates in server containers should use the sha256Sync API for simpler code.

Example

  const 
  
 encodeUriComponent 
  
 = 
  
 require 
 ( 
 'encodeUriComponent' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 const 
  
 sha256 
  
 = 
  
 require 
 ( 
 'sha256' 
 ); 
 sha256 
 ( 
 'inputString' 
 , 
  
 ( 
 digest 
 ) 
  
 = 
>  
 { 
  
 sendHttpGet 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 encodeUriComponent 
 ( 
 digest 
 )); 
 }); 
 sha256 
 ( 
 'inputString' 
 , 
  
 ( 
 digest 
 ) 
  
 = 
>  
 { 
  
 sendHttpGet 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 encodeUriComponent 
 ( 
 digest 
 )); 
 }, 
  
 { 
 outputEncoding 
 : 
  
 'hex' 
 }); 
 

Syntax

  sha256 
 ( 
 input 
 , 
  
 onSuccess 
 , 
  
 options 
  
 = 
  
 undefined 
 ); 
 

Parameters

Parameter Type Description
input
string The string to hash.
onSuccess
function Called with the resulting digest, encoded in base64, unless the options object specifies a different output encoding.
options
object Optional options object to specify the output encoding. If specified, the object should contain the key outputEncoding with value as one of base64 or hex .

Associated permissions

None.


sha256Sync

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

Example

  const 
  
 encodeUriComponent 
  
 = 
  
 require 
 ( 
 'encodeUriComponent' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 const 
  
 sha256Sync 
  
 = 
  
 require 
 ( 
 'sha256Sync' 
 ); 
 const 
  
 digestBase64 
  
 = 
  
 sha256Sync 
 ( 
 'inputString' 
 ); 
 const 
  
 digestHex 
  
 = 
  
 sha256Sync 
 ( 
 'inputString' 
 , 
  
 { 
 outputEncoding 
 : 
  
 'hex' 
 }); 
 sendHttpGet 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 encodeUriComponent 
 ( 
 digestBase64 
 )); 
 sendHttpGet 
 ( 
 'https://example.com/collect?id=' 
  
 + 
  
 encodeUriComponent 
 ( 
 digestHex 
 )); 
 

Syntax

  sha256Sync 
 ( 
 input 
 , 
  
 options 
  
 = 
  
 undefined 
 ); 
 

Parameters

Parameter Type Description
input
string The string to hash.
options
object Optional options object to specify the output encoding. If specified, the object should contain the key outputEncoding with value as one of base64 or hex .

Associated permissions

None.


templateDataStorage

Returns an object with methods for accessing template data storage. Template data storage allows data to be shared across executions of a single template. Data stored in template data storage persists on the server running the container. In most cases there are multiple servers running the container, so storing data in template data storage does not guarantee that every subsequent request will have access to the data.

The "data" in the name "templateDataStorage" refers to the fact that only plain, non-function data types may be stored using this API. Any functions or references to functions passed to the API will be stored as null instead.

Syntax

  const 
  
 templateDataStorage 
  
 = 
  
 require 
 ( 
 'templateDataStorage' 
 ); 
 // Returns a copy of the value stored for the given key, or null if nothing 
 // is stored with that key. 
 templateDataStorage 
 . 
 getItemCopy 
 ( 
 key 
 ); 
 // Stores a copy of the value for the given key (or removes the data stored 
 // for the given key if the input value is null). 
 templateDataStorage 
 . 
 setItemCopy 
 ( 
 key 
 , 
  
 value 
 ); 
 // Removes the value stored for the given key, if present. 
 templateDataStorage 
 . 
 removeItem 
 ( 
 key 
 ); 
 // Deletes all values stored for the current template. 
 templateDataStorage 
 . 
 clear 
 (); 
 

Example

  const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 const 
  
 setResponseBody 
  
 = 
  
 require 
 ( 
 'setResponseBody' 
 ); 
 const 
  
 setResponseStatus 
  
 = 
  
 require 
 ( 
 'setResponseStatus' 
 ); 
 const 
  
 templateDataStorage 
  
 = 
  
 require 
 ( 
 'templateDataStorage' 
 ); 
 // Check to see if the item is in the cache. 
 const 
  
 cachedBody 
  
 = 
  
 templateDataStorage 
 . 
 getItemCopy 
 ( 
 data 
 . 
 key 
 ); 
 if 
  
 ( 
 cachedBody 
 ) 
  
 { 
  
 setResponseBody 
 ( 
 cachedBody 
 ); 
  
 data 
 . 
 gtmOnSuccess 
 (); 
  
 return 
 ; 
 } 
 sendHttpGet 
 ( 
 data 
 . 
 url 
 ). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 result 
 . 
 statusCode 
  
> = 
  
 200 
 && 
 result 
 . 
 statusCode 
 < 
 300 
 ) 
  
 { 
  
 setResponseBody 
 ( 
 result 
 . 
 body 
 ); 
  
 templateDataStorage 
 . 
 setItemCopy 
 ( 
 data 
 . 
 key 
 , 
  
 result 
 . 
 body 
 ); 
  
 data 
 . 
 gtmOnSuccess 
 (); 
  
 } 
  
 else 
  
 { 
  
 data 
 . 
 gtmOnFailure 
 (); 
  
 } 
  
 setResponseStatus 
 ( 
 result 
 . 
 statusCode 
 ); 
 }); 
 

Associated permissions

access_template_storage


testRegex

Tests a string against an regex created via createRegex API. Returns true if the regex matches. Returns false otherwise.

A regex created with the global flag is stateful. See the RegExp documentation for details.

Example

  const 
  
 createRegex 
  
 = 
  
 require 
 ( 
 'createRegex' 
 ); 
 const 
  
 testRegex 
  
 = 
  
 require 
 ( 
 'testRegex' 
 ); 
 const 
  
 domainRegex 
  
 = 
  
 createRegex 
 ( 
 '\\w+\\.com' 
 , 
  
 'i' 
 ); 
 // createRegex returns null if the regex is invalid or Re2 is not available. 
 if 
  
 ( 
 domainRegex 
  
 === 
  
 null 
 ) 
  
 return 
 ; 
 // Returns true 
 testRegex 
 ( 
 domainRegex 
 , 
  
 'example.com/foobar' 
 ); 
 

Syntax

  testRegex 
 ( 
 regex 
 , 
  
 string 
 ); 
 

Parameters

Parameter Type Description
regex
Object The regex to test against, returned from createRegex API.
string
string Test string to test.

Associated permissions

None.


toBase64

Encodes a string as base64 or base64url. Defaults to base64 encoding.

Syntax

  toBase64 
 ( 
 input 
 , 
  
 options 
 ); 
 

Parameters

Parameter Type Description
input
string String to encode.
options
object Optional API configuration. (See Options below.)

Options

Option Type Description Minimum version
urlEncoding
boolean If true, the result will be encoded using base64url format. 1.0.0

Example

  const 
  
 toBase64 
  
 = 
  
 require 
 ( 
 'toBase64' 
 ); 
 const 
  
 base64Hello 
  
 = 
  
 toBase64 
 ( 
 'hello' 
 ); 
 const 
  
 base64UrlHello 
  
 = 
  
 toBase64 
 ( 
 'hello' 
 , 
  
 { 
 urlEncoding 
 : 
  
 true 
 }); 
 

Associated permissions

None.


BigQuery

Returns an object that provides BigQuery functions.

The BigQuery.insert function allows writing data into a BigQuery table. It returns a promise that resolves upon a successful insertion or rejects upon an error.

When the insertion succeeds, the promise resolves with no arguments.

When the insertion fails, the promise rejects with a list of objects containing the error reason and possibly a row object if an error occurs. It's possible for a part of the request to be completed successfully, while other parts are not. The promise is rejected in this case with a list of errors for each row with a row object to help distinguish which rows were inserted (See Error Examples below). See BigQuery's documentation on error messages for more information.

Syntax

  BigQuery 
 . 
 insert 
 ( 
 connectionInfo 
 , 
  
 rows 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter
Type
Description
connectionInfo
object
Defines information required to connect to a BigQuery table. There is one optional parameter and two required parameters:
  • projectId - Optional Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_bigquery permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT . If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.
  • datasetId - BigQuery Dataset ID.
  • tableId - BigQuery Table ID.
rows
Array
The rows to insert into the table.
options
object
Optional request options. The supported options are: ignoreUnknownValuesand skipInvalidRows. Unknown option keys are ignored. (See Options , below.)

Options

Parameter Type Description
ignoreUnknownValues
boolean If set to true , then accept rows that contain values that do not match the schema. The unknown values are ignored. Defaults to false .
skipInvalidRows
boolean If set to true , then insert all valid rows of a request, even if invalid rows exist. Defaults to false .

Error Examples

A module not found error means that your server container is likely running an older version of our image that had not included the BigQuery module yet. Please redeploy your server container with the same settings using our deployment script . The module will be automatically included once the operation finishes.

A non-insertion error typically has one error object with a reason key:

  [{ 
 reason 
 : 
  
 'invalid' 
 }] 
 

An insertion error can contain multiple error objects with an errors array and a row object. The following is an example of an error response from inserting two rows where only one row has an error:

  [ 
  
 { 
  
 "errors" 
 : 
  
 [ 
  
 { 
  
 "reason" 
 : 
 "invalid" 
  
 } 
  
 ], 
  
 "row" 
 : 
  
 { 
  
 "string_col" 
 : 
 "otherString" 
 , 
  
 "number_col" 
 :- 
 3 
 , 
  
 "bool_col" 
 : 
 3 
  
 } 
  
 }, 
  
 { 
  
 "errors" 
 : 
  
 [ 
  
 { 
  
 "reason" 
 : 
 "stopped" 
  
 } 
  
 ], 
  
 "row" 
 : 
  
 { 
  
 "string_col" 
 : 
 "stringValue" 
 , 
  
 "number_col" 
 : 
 5 
 , 
  
 " 
 bool_col 
 : 
 false 
  
 } 
  
 } 
 ] 
 

Example

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

Associated permissions

access_bigquery


Firestore

Returns an object that provides Firestore functions.

This API supports only Firestore in Native mode, not Firestore in Datastore mode. Also, the API only supports using the default database .

Firestore.read

The Firestore.read function reads data from a Firestore document and returns a promise that resolves to an object containing two keys: id and data . If the document does not exist, the promise rejects with an object containing a reason key equal to not_found .

Syntax

  Firestore 
 . 
 read 
 ( 
 path 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
path
string The path to the document or collection. Must not start or end with a '/'.
options
object Optional request options. The supported options are: projectId, disableCache, and transaction. Unknown option keys are ignored. (See Options , below.)

Options

Parameter Type Description
projectId
string Optional . Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_firestore permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT . If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.
disableCache
boolean Optional . Determines whether or not to disable the cache. Caching is enabled by default, which will cache the results for the duration of the request.
transaction
string Optional . The value retrieved from Firestore.runTransaction(). Marks the operation to be used within a transaction.

Example

  const 
  
 Firestore 
  
 = 
  
 require 
 ( 
 'Firestore' 
 ); 
 return 
  
 Firestore 
 . 
 read 
 ( 
 'collection/document' 
 , 
  
 { 
  
 projectId 
 : 
  
 'gcp-cloud-project-id' 
 , 
 }). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 result 
 . 
 data 
 . 
 key 
 , 
  
 () 
  
 = 
>  
 undefined 
 ); 
 

Firestore.write

The Firestore.write function writes data to a Firestore document or collection. If the path is to a collection, a document will be created with a randomly generated ID. If the path is to a document and it does not exist, it will be created. This API returns a promise that resolves to the ID of the document added or modified. If the transaction option is used, the API still returns a promise, but will not contain the ID since the writes are batched.

Syntax

  Firestore 
 . 
 write 
 ( 
 path 
 , 
  
 input 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
path
string The path to the document or collection. Must not start or end with a '/'.
input
object The value to write into the document. If the merge option is set, the API will merge the keys from the input into the document.
options
object Optional request options. The supported options are: projectId, merge, and transaction. Unknown option keys are ignored. (See Options , below.)

Options

Parameter Type Description
projectId
string Optional . Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_firestore permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT . If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.
merge
boolean Optional . If set to true , then merge the keys from the input into the document, otherwise the method will override the whole document. Defaults to false .
transaction
string Optional . The value retrieved from Firestore.runTransaction(). Marks the operation to be used within a transaction.

Example

  const 
  
 Firestore 
  
 = 
  
 require 
 ( 
 'Firestore' 
 ); 
 const 
  
 input 
  
 = 
  
 { 
 key1 
 : 
  
 'value1' 
 , 
  
 key2 
 : 
  
 12345 
 }; 
 Firestore 
 . 
 write 
 ( 
 'collection/document' 
 , 
  
 input 
 , 
  
 { 
  
 projectId 
 : 
  
 'gcp-cloud-project-id' 
 , 
  
 merge 
 : 
  
 true 
 , 
 }). 
 then 
 (( 
 id 
 ) 
  
 = 
>  
 { 
  
 data 
 . 
 gtmOnSuccess 
 (); 
 }, 
  
 data 
 . 
 gtmOnFailure 
 ); 
 

Firestore.query

The Firestore.query function queries the given collection and returns a promise that resolves to an array of Firestore documents that match the query conditions. The Firestore document object is the same as listed above in Firestore.read . If there are no documents that match the query conditions, the returned promise will resolve to an empty array.

Syntax

  Firestore 
 . 
 query 
 ( 
 collection 
 , 
  
 queryConditions 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
collection
string The path to the collection. Must not start or end with a '/'.
queryConditions
Array An array of query conditions. Each query comes in the form of an array with three values: key, operator, and expectedValue. E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

The conditions are ANDed together to create the query result. Please refer to Firestore's query operators for a list of compatible query operators.
options
object Optional request options. The supported options are: projectId, disableCache, limit, and transaction. Unknown option keys are ignored. (See Options , below.)

Options

Parameter Type Description
projectId
string Optional . Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_firestore permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT . If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.
disableCache
boolean Optional . Determines whether or not to disable the cache. Caching is enabled by default, which will cache the results for the duration of the request.
limit
number Optional . Changes the maximum number of results returned by the query, defaults to 5.
transaction
string Optional . The value retrieved from Firestore.runTransaction(). Marks the operation to be used within a transaction.

Example

  const 
  
 Firestore 
  
 = 
  
 require 
 ( 
 'Firestore' 
 ); 
 const 
  
 queries 
  
 = 
  
 const 
  
 queries 
  
 = 
  
 [[ 
 'id' 
 , 
  
 '==' 
 , 
  
 '5' 
 ]]; 
 return 
  
 Firestore 
 . 
 query 
 ( 
 'collection' 
 , 
  
 queries 
 , 
  
 { 
  
 projectId 
 : 
  
 'gcp-cloud-project-id' 
 , 
  
 limit 
 : 
  
 1 
 , 
 }). 
 then 
 (( 
 documents 
 ) 
  
 = 
>  
 documents 
 [ 
 0 
 ]. 
 data 
 . 
 key 
 , 
  
 () 
  
 = 
>  
 undefined 
 ); 
 

Firestore.runTransaction

The Firestore.runTransaction function allows the user to atomically read and write from Firestore. If a concurrent write or another transaction conflict happens, the transaction will be retried up to two times. If it fails after three total attempts, the API will reject with an error. This API returns a promise that resolves to an array of document IDs, for each write operation, if the transaction is successful, and will reject with the error if it fails.

Syntax

  Firestore 
 . 
 runTransaction 
 ( 
 callback 
 [, 
  
 options 
 ]); 
 

Parameters

Parameter Type Description
callback
function A callback that’s invoked with a string transaction ID. The transaction ID can be passed into read/write/query API calls. This callback function mustreturn a promise. The callback may run up to three times before failing.
options
object Optional request options. The supported only supported option is projectId. Unknown option keys are ignored. (See Options , below.)

Options

Parameter Type Description
projectId
string Optional . Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_firestore permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT . If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.

Example

  const 
  
 Firestore 
  
 = 
  
 require 
 ( 
 'Firestore' 
 ); 
 const 
  
 path 
  
 = 
  
 'collection/document' 
 ; 
 const 
  
 projectId 
  
 = 
  
 'gcp-cloud-project-id' 
 ; 
 Firestore 
 . 
 runTransaction 
 (( 
 transaction 
 ) 
  
 = 
>  
 { 
  
 const 
  
 transactionOptions 
  
 = 
  
 { 
  
 projectId 
 : 
  
 projectId 
 , 
  
 transaction 
 : 
  
 transaction 
 , 
  
 }; 
  
 // Must return a promise. 
  
 return 
  
 Firestore 
 . 
 read 
 ( 
 path 
 , 
  
 transactionOptions 
 ). 
 then 
 (( 
 result 
 ) 
  
 = 
>  
 { 
  
 const 
  
 newInputCount 
  
 = 
  
 result 
 . 
 data 
 . 
 inputCount 
  
 + 
  
 1 
 ; 
  
 const 
  
 input 
  
 = 
  
 { 
 key1 
 : 
  
 'value1' 
 , 
  
 inputCount 
 : 
  
 newInputCount 
 }; 
  
 return 
  
 Firestore 
 . 
 write 
 ( 
 path 
 , 
  
 input 
 , 
  
 transactionOptions 
 ); 
  
 }); 
 }, 
  
 { 
  
 projectId 
 : 
  
 projectId 
 }). 
 then 
 (( 
 ids 
 ) 
  
 = 
>  
 { 
  
 data 
 . 
 gtmOnSuccess 
 (); 
 }, 
  
 data 
 . 
 gtmOnFailure 
 ); 
 

Error Example

Errors are available in each Firestore function will be rejected with an object containing a reason key:

  Firestore 
 . 
 read 
 (...). 
 then 
 ( 
 onSuccess 
 , 
  
 ( 
 error 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 error 
 . 
 reason 
  
 === 
  
 'unknown' 
 ) 
  
 { 
  
 // Handle the unknown error here. 
  
 } 
 }); 
 

The error reasons can contain but are not limited to Firestore REST API Error Codes .

Associated permissions

access_firestore


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 .

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

Syntax

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

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 function parameters are converted to numbers.

Associated permissions

None.


Messages

The following APIs work together to allow passing messages between different parts of a container.


addMessageListener

Adds a function that listens for a message of a particular type. When a message of that type is sent using the sendMessage API (typically by a tag), the callback will be run synchronously. The callback is run with two parameters:

  1. messageType:string
  2. message:Object

If the callback is added in a client, the callback will receive messages across all of the events that client creates. If the callback should receive messages from only a certain event, then bind this API to the event using bindToEvent in the runContainer API's onStart function. See the example.

Syntax

  const 
  
 addMessageListener 
  
 = 
  
 require 
 ( 
 'addMessageListener' 
 ); 
 addMessageListener 
 ( 
 'send_pixel' 
 , 
  
 ( 
 messageType 
 , 
  
 message 
 ) 
  
 = 
>  
 { 
  
 // This will be run whenever something sends a 'send_pixel' message. 
 }); 
 

Parameters

Parameter Type Description
messageType
string The message type to listen for. If the value is not a string, it will be coerced to a string.
callback
function The callback to run when a message of the applicable message type is sent. If the callback is not a function, the API will do nothing.

Example

  const 
  
 addMessageListener 
  
 = 
  
 require 
 ( 
 'addMessageListener' 
 ); 
 const 
  
 claimRequest 
  
 = 
  
 require 
 ( 
 'claimRequest' 
 ); 
 const 
  
 extractEventsFromMpv1 
  
 = 
  
 require 
 ( 
 'extractEventsFromMpv1' 
 ); 
 const 
  
 returnResponse 
  
 = 
  
 require 
 ( 
 'returnResponse' 
 ); 
 const 
  
 runContainer 
  
 = 
  
 require 
 ( 
 'runContainer' 
 ); 
 claimRequest 
 (); 
 addMessageListener 
 ( 
 'send_pixel' 
 , 
  
 ( 
 messageType 
 , 
  
 message 
 ) 
  
 = 
>  
 { 
  
 // This will be run whenever a tag sends a 'send_pixel' message. 
 }); 
 const 
  
 events 
  
 = 
  
 extractEventsFromMpv1 
 (); 
 let 
  
 eventsCompleted 
  
 = 
  
 0 
 ; 
 events 
 . 
 forEach 
 (( 
 event 
 , 
  
 i 
 ) 
  
 = 
>  
 { 
  
 runContainer 
 ( 
 events 
 [ 
 i 
 ], 
  
 /* onComplete= */ 
  
 () 
  
 = 
>  
 { 
  
 if 
  
 ( 
 events 
 . 
 length 
  
 === 
  
 ++ 
 eventsCompleted 
 ) 
  
 { 
  
 returnResponse 
 (); 
  
 } 
  
 }, 
  
 /* onStart= */ 
  
 ( 
 bindToEvent 
 ) 
  
 = 
>  
 { 
  
 if 
  
 ( 
 i 
  
 === 
  
 0 
 ) 
  
 { 
  
 bindToEvent 
 ( 
 addMessageListener 
 )( 
 'send_pixel' 
 , 
  
 ( 
 messageType 
 , 
  
 message 
 ) 
  
 = 
>  
 { 
  
 // This will be called whenever a tag for the first event sends a 
  
 // 'send_pixel' message. 
  
 }); 
  
 } 
  
 }); 
 }); 
 

Associated permissions

Requires use_message permission. The permission must be configured to permit at least:

  • A message type with Usage of listen or listen_and_send .

hasMessageListener

Returns true if a message listener has been added for the given message type. Returns false otherwise.

Syntax

  const 
  
 hasMessageListener 
  
 = 
  
 require 
 ( 
 'hasMessageListener' 
 ); 
 hasMessageListener 
 ( 
 'send_pixel' 
 ); 
 

Associated permissions

None.


sendMessage

Sends a message of the specified type to a registered listener. This can be used to send messages from a tag back to the client that ran the container.

Syntax

  const 
  
 sendMessage 
  
 = 
  
 require 
 ( 
 'sendMessage' 
 ); 
 sendMessage 
 ( 
 'send_pixel' 
 , 
  
 { 
 url 
 : 
  
 'https://analytics.example.com/collect' 
 }); 
 

Parameters

Parameter Type Description
messageType
string The message type to send. If the value is not a string, it will be coerced to a string.
message
object The message to send. If the message is not an object, the API will do nothing.

Associated permissions

Requires use_message permission. The permission must be configured to permit at least:

  • A message type with Usage of listen_and_send or send .

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

Parameter Type Description
objectInput
any The object whose keys to enumerate. If the input is not an object, it will be coerced to an object.

Object.values

Parameter Type Description
objectInput
any The object whose values to enumerate. If the input is not an object, it will be coerced to an object.

Object.entries

Parameter Type Description
objectInput
any The object whose key/value pairs to enumerate. If the input is not an object, it will be coerced to an object.

Object.freeze

Parameter Type Description
objectInput
any The object to freeze. If the input is not an object, it will be treated as a frozen object.

Object.delete

Parameter Type Description
objectInput
any The object whose key to delete.
keyToDelete
string The top-level key to 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. 
 

Promise

Returns an object that provides methods for interacting with promises.

Promises are functionally equivalent to JavaScript promises. Each instance has three methods that return a Promise which allows further action when a promise settles:

  • .then() - Handles both the resolved and rejected cases. It takes two callbacks as parameters: one for the success case and one for the failure case.
  • .catch() - Handles the rejected cases only. Takes one callback as a parameter.
  • .finally() - Provides a way for code to be run whether the promise was resolved or rejected. Takes one callback as a parameter that is invoked with no argument.

A variable that returns a promise equals the resolved value of the promise, or false if the promise rejects.

Example

  promise 
 . 
 then 
 (( 
 resolvedValue 
 ) 
  
 = 
>  
 { 
  
 // Handles when promise resolves. 
  
 }, 
  
 ( 
 rejectedValue 
 ) 
  
 = 
>  
 { 
  
 // Handles when promise rejects. 
  
 }); 
 promise 
 . 
 catch 
 (( 
 rejectedValue 
 ) 
  
 = 
>  
 { 
  
 // Handles when promise rejects. 
  
 }); 
 promise 
 . 
 finally 
 (() 
  
 = 
>  
 { 
  
 // Runs regardless of whether or not the previous promise resolves or 
  
 // rejects. 
  
 }); 
 

Promise.all

Returns a promise that either:

  • resolves when all the inputs have resolved, or
  • rejects when any of the inputs reject

Syntax

  Promise 
 . 
 all 
 ( 
 inputs 
 ); 
 

Parameters

Parameter Type Description
inputs
Array An array of values or promises. If an input is not a promise, the input is passed through as if it's the resolved value of a promise. Throws an error if the input is not an array.

Example

  const 
  
 Promise 
  
 = 
  
 require 
 ( 
 'Promise' 
 ); 
 const 
  
 sendHttpGet 
  
 = 
  
 require 
 ( 
 'sendHttpGet' 
 ); 
 return 
  
 Promise 
 . 
 all 
 ([ 
 'a' 
 , 
  
 sendHttpGet 
 ( 
 'https://example.com' 
 )]) 
  
 . 
 then 
 (( 
 results 
 ) 
  
 = 
>  
 { 
  
 // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}] 
  
 }); 
 

Associated permissions

None.

Promise.create

Creates a promise that is functionally equivalent to a JavaScript promise.

Syntax

  Promise 
 . 
 create 
 ( 
 resolver 
 ); 
 

Parameters

Parameter Type Description
resolver
function A function that is invoked with two functions -- resolve and reject. The returned promise will resolve or reject when the corresponding parameter is invoked. Throws an error if resolver is not a function.

Example

  const 
  
 Promise 
  
 = 
  
 require 
 ( 
 'Promise' 
 ); 
 return 
  
 Promise 
 . 
 create 
 (( 
 resolve 
 , 
  
 reject 
 ) 
  
 = 
>  
 { 
  
 // Do asynchronous work that eventually calls resolve() or reject() 
 }); 
 

Associated permissions

None.

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

Parameter Type Description
apiName
string The name of the api to check; same string as passed to require() .

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

Parameter Type Description
actual
any The value to use in the fluent checks.
opt_message
string Optional message to print if the assertion fails.

Matchers

Matcher Description
isUndefined() Asserts that the subject is undefined .
isDefined() Asserts that the subject is not undefined .
isNull() Asserts that the subject is null .
isNotNull() Asserts that the subject is not null .
isFalse() Asserts that the subject is false .
isTrue() Asserts that the subject is true .
isFalsy() Asserts that the subject is falsy. Falsy values are undefined , null , false , NaN , 0, and '' (empty string).
isTruthy() Asserts that the subject is truthy. Falsy values are undefined , null , false , NaN , 0, and '' (empty string).
isNaN() Asserts that the subject is the value NaN.
isNotNaN() Asserts that the subject is any value besides NaN.
isInfinity() Asserts that the subject is positive or negative Infinity.
isNotInfinity() Asserts that the subject is any value besides positive or negative Infinity.
isEqualTo(expected) Asserts that the subject is equal to the given value. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
isNotEqualTo(expected) Asserts that the subject is not equal to the given value. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
isAnyOf(...expected) Asserts that the subject is equal to one of the given value. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
isNoneOf(...expected) Asserts that the subject is not equal to any of the given values. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
isStrictlyEqualTo(expected) Asserts that the subject is strictly equal ( === ) to the given value.
isNotStrictlyEqualTo(expected) Asserts that the subject is not strictly equal ( !== ) to the given value.
isGreaterThan(expected) Asserts that the subject is greater than ( > ) the given value in an ordered comparison.
isGreaterThanOrEqualTo(expected) Asserts that the subject is greater than or equal to ( >= ) the given value in an ordered comparison.
isLessThan(expected) Asserts that the subject is less than ( < ) the given value in an ordered comparison.
isLessThanOrEqualTo(expected) Asserts that the subject is less than or equal to ( <= ) the given value in an ordered comparison.
contains(...expected) Asserts that the subject is an array or string that contains all of the given values in any order. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
doesNotContain(...expected) Asserts that the subject is an array or string that contains none of the given values. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
containsExactly(...expected) Asserts that the subject is an array that contains all of the given values in any order and no other values. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
doesNotContainExactly(...expected) Asserts that the subject is an array that has contains a different set of values from the given values in any order. This is a value comparison, not a reference comparison. The contents of objects and arrays are compared recursively.
hasLength(expected) Asserts that the subject is an array or string with the given length. The assertion always fails if the value is not an array or string.
isEmpty() Asserts that the subject is an array or string that is empty (length = 0). The assertion always fails if the value is not an array or string.
isNotEmpty() Asserts that the subject is an array or string that is not empty (length > 0). The assertion always fails if the value is not an array or string.
isArray() Asserts that the type of the subject is an array.
isBoolean() Asserts that the type of the subject is a boolean.
isFunction() Asserts that the type of the subject is a function.
isNumber() Asserts that the type of the subject is a number.
isObject() Asserts that the type of the subject is an object.
isString() Asserts that the type of the subject is a string.

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

Parameter Type Description
opt_message
string Optional error message text.

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

Parameter Type Description
apiName
string The name of the API to mock; same string as passed to require()
returnValue
any The value to return for the API or a function called in place of the API. If returnValue is a function, that function is called in place of the Sandboxed API; if returnValue is anything other than a function, that value is returned in place of the Sandboxed API.

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

Parameter Type Description
apiName
string The name of the API to mock; same string as passed to require()
objectMock
object The value to return for the API or a function called in place of the API. Must be an object.

Examples

  const 
  
 storage 
  
 = 
  
 {}; 
 let 
  
 firestoreId 
  
 = 
  
 1 
 ; 
 function 
  
 asTestPromise 
 ( 
 result 
 ) 
  
 { 
  
 return 
  
 { 
  
 then 
 : 
  
 ( 
 callback 
 ) 
  
 = 
>  
 callback 
 ( 
 result 
 ) 
  
 }; 
 } 
 mockObject 
 ( 
 'Firestore' 
 , 
  
 { 
  
 write 
 : 
  
 ( 
 collection 
 , 
  
 input 
 ) 
  
 = 
>  
 { 
  
 storage 
 [ 
 collection 
  
 + 
  
 '/' 
  
 + 
  
 ( 
 ++ 
 firestoreId 
 )] 
  
 = 
  
 input 
 ; 
  
 return 
  
 asTestPromise 
 ( 
 firestoreId 
 ); 
  
 }, 
  
 read 
 : 
  
 ( 
 document 
 ) 
  
 = 
>  
 asTestPromise 
 ({ 
 data 
 : 
  
 storage 
 [ 
 document 
 ]}) 
 }); 
 

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

Parameter Type Description
data
object Data object to be used in the test.

Return Value

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

Example

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

Design a Mobile Site
View Site in Mobile | Classic
Share by: