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

The eventData object contains the following data:

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

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

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

Associated permissions

None.

Minimum image version

2.0.0

decodeUri

Decodes any encoded characters in the provided URI. Returns a string that 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

Associated permissions

None.

decodeUriComponent

Decodes any encoded characters in the provided URI component. Returns a string that 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

Associated permissions

None.

encodeUri

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a string that 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

Associated permissions

None.

encodeUriComponent

Returns an encoded Uniform Resource Identifier (URI) by escaping special characters. Returns a string that 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

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

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

Associated permissions

None.

getAllEventData

Returns a copy of the event data.

Syntax

getAllEventData();

Associated permissions

read_event_data

getClientName

Returns a string that contains the name of the current client.

Syntax

getClientName();

Associated permissions

read_container_data

getContainerVersion

Returns an object containing 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

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

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

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

Options

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 string representation 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

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

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 number that represents the current time in milliseconds since Unix epoch, as returned by Date.now().

Syntax

getTimestamp();

Associated permissions

None.

getTimestampMillis

Returns a number that 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.

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

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

Options

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

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

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parameters

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

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

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

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

Options

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

Options

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 Tag for GA4 and Google Analytics: GA Event web 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

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

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

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

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

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

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

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

Associated permissions

None.

toBase64

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

Syntax

toBase64(input, options);

Parameters

Options

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

Options

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

Options

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

Options

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

Options

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

Options

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

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

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

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.

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

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

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

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 = {};
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]})
});