API добавления тегов на стороне сервера

В этом документе описываются API для тегирования на стороне сервера.

addEventCallback

Регистрирует функцию обратного вызова, которая будет вызываться в конце события. Обратный вызов будет вызван, когда все теги для события будут выполнены. Обратному вызову передаются два значения: идентификатор контейнера, вызывающего функцию, и объект, содержащий информацию о событии.

Когда этот API используется в теге, он связывается с текущим событием. Когда этот API используется в клиенте, он должен быть привязан к конкретному событию с помощью функции bindToEvent API runContainer . См. пример для более подробной информации.

Синтаксис

const addEventCallback = require('addEventCallback');

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

Параметры

Параметр Тип Описание
callback функция Функция для вызова в конце события.

Объект eventData содержит следующие данные:

Имя ключа Тип Описание
tags Множество Массив объектов данных тегов. Каждый тег, сработавший во время события, будет иметь запись в этом массиве. Объект данных тега содержит идентификатор тега ( id ), его статус выполнения ( status ) и время его выполнения ( executionTime ). Данные тега также будут включать дополнительные метаданные тега, настроенные для тега.

Пример

В клиенте:

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

В теге:

const addEventCallback = require('addEventCallback');

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

Связанные разрешения

read_event_metadata

callLater

Планирует асинхронный вызов функции. Функция будет вызвана после возврата текущего кода. Это эквивалентно setTimeout(<function>, 0) .

Пример

const callLater = require('callLater');
const logToConsole = require('logToConsole');

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

Синтаксис

callLater(function)

Параметры

Параметр Тип Описание
function функция Функция для вызова.

Связанные разрешения

Никто.

claimRequest

Используйте этот API в клиенте, чтобы запросить запрос. После утверждения запроса контейнер не запускает дополнительных клиентов.

Этот API выдает исключение, если вызывается в теге или переменной. Этот API выдает исключение, если вызывается после возврата клиента (например, если вызывается в асинхронном обратном вызове, таком как callLater или функция runContainer onComplete ).

Клиент должен запросить запрос с помощью этого API перед вызовом API runContainer .

Пример

const claimRequest = require('claimRequest');

claimRequest();

Синтаксис

claimRequest();

Связанные разрешения

Никто.

computeEffectiveTldPlusOne

Возвращает действующий домен верхнего уровня + 1 (eTLD+1) данного домена или URL-адреса. eTLD+1 вычисляется путем оценки домена по правилам списка общедоступных суффиксов . eTLD+1 обычно является доменом самого высокого уровня, для которого вы можете установить файл cookie.

Если аргумент имеет значение null или не определен, то значение аргумента возвращается без изменений. В противном случае аргумент преобразуется в строку. Если аргумент не является допустимым доменом или URL-адресом, возвращается пустая строка. Если сервер не может получить список общедоступных суффиксов, значение аргумента возвращается без изменений.

Пример

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

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

Синтаксис

computeEffectiveTldPlusOne(domainOrUrl);

Параметры

Параметр Тип Описание
domainOrUrl нить Домен или URL-адрес, по которому вычисляется eTLD+1.

Связанные разрешения

Никто.

createRegex

Создает новый экземпляр регулярного выражения и возвращает его, завернутый в объект. Вы не можете получить доступ к регулярному выражению напрямую. Однако вы можете передать его в API testRegex , String.replace() , String.match() и String.search() .

Возвращает null если регулярное выражение неверно или Re2 недоступен на сервере.

Этот API использует реализацию Re2 . Образ Docker сервера должен быть 2.0.0 или более поздней версии.

Пример

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Синтаксис

createRegex(pattern, flags);

Параметры

Параметр Тип Описание
pattern нить Текст регулярного выражения.
flags нить Необязательная строка, содержащая флаги для создаваемого регулярного выражения. Поддерживаются `g` (глобальный) и `i` (без учета регистра). Все остальные символы молча игнорируются.

Связанные разрешения

Никто.

decodeUri

Декодирует любые закодированные символы в предоставленном URI. Возвращает строку , представляющую декодированный URI. Возвращает undefined при вводе неверных данных.

Пример

const decodeUri = require('decodeUri');

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

Синтаксис

decodeUri(encoded_uri);

Параметры

Параметр Тип Описание
encoded_uri нить URI, закодированный функцией encodeUri() или другим способом.

Связанные разрешения

Никто.

decodeUriComponent

Декодирует любые закодированные символы в предоставленном компоненте URI. Возвращает строку , представляющую декодированный компонент URI. Возвращает undefined при неверном вводе.

Пример

const decodeUriComponent = require('decodeUriComponent');

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

Синтаксис

decodeUriComponent(encoded_uri_component);

Параметры

Параметр Тип Описание
encoded_uri_component нить Компонент URI, закодированный функцией encodeUriComponent() или другим способом.

Связанные разрешения

Никто.

encodeUri

Возвращает закодированный универсальный идентификатор ресурса (URI) путем экранирования специальных символов. Возвращает строку , представляющую предоставленную строку, закодированную как URI.

Пример

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

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

Синтаксис

encodeUri(uri);

Параметры

Параметр Тип Описание
uri нить Полный URI.

Связанные разрешения

Никто.

encodeUriComponent

Возвращает закодированный универсальный идентификатор ресурса (URI) путем экранирования специальных символов. Возвращает строку , представляющую предоставленную строку, закодированную как URI.

Пример

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

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

Синтаксис

encodeUriComponent(str);

Параметры

Параметр Тип Описание
str нить Компонент URI.

Связанные разрешения

Никто.

extractEventsFromMpv1

Преобразует входящий запрос Measurement Protocol V1 в список событий в формате Unified Schema. Возвращает список извлеченных событий. Выдает ошибку, если запрос имеет неправильный формат.

Пример

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

Синтаксис

extractEventsFromMpv1();

Связанные разрешения

Требуется разрешение read_request . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • body
  • query parameters

extractEventsFromMpv2

Преобразует входящий запрос Measurement Protocol V2 в список событий в формате Unified Schema. Возвращает список извлеченных событий. Выдает ошибку, если запрос имеет неправильный формат.

Пример

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

Синтаксис

extractEventsFromMpv2();

Связанные разрешения

Требуется разрешение read_request . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • body
  • query parameters

fromBase64

Декодирует строку в кодировке base64. Возвращает undefined если ввод недействителен.

Синтаксис

fromBase64(base64EncodedString);

Параметры

Параметр Тип Описание
base64EncodedString нить Строка в кодировке Base64.

Пример

const fromBase64 = require('fromBase64');

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

Связанные разрешения

Никто.

generateRandom

Возвращает случайное число (целое число) в заданном диапазоне.

Пример

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Синтаксис

generateRandom(min, max);

Параметры

Параметр Тип Описание
min число Минимальное потенциальное значение возвращаемого целого числа (включительно).
max число Максимальное потенциальное значение возвращаемого целого числа (включительно).

Связанные разрешения

Никто.

getAllEventData

Возвращает копию данных события.

Синтаксис

getAllEventData();

Связанные разрешения

read_event_data

getClientName

Возвращает строку , содержащую имя текущего клиента.

Синтаксис

getClientName();

Связанные разрешения

read_container_data

getContainerVersion

Возвращает объект , содержащий данные о текущем контейнере. Возвращаемый объект будет иметь следующие поля:

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

Пример

const getContainerVersion = require('getContainerVersion');

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

Синтаксис

getContainerVersion();

Связанные разрешения

read_container_data

getCookieValues

Возвращает массив, содержащий значения всех файлов cookie с заданным именем.

Пример

const getCookieValues = require('getCookieValues');

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

Синтаксис

getCookieValues(name[, noDecode]);

Параметры

Параметр Тип Описание
name нить Имя куки.
noDecode логический Если true , значения cookie не будут декодированы перед возвратом. По умолчанию false .

Связанные разрешения

get_cookies

getEventData

Возвращает копию значения по заданному пути в данных события. Возвращает undefined если нет данных о событии или если по заданному пути нет значения.

Пример

const getEventData = require('getEventData');

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

Параметры

Параметр Тип Описание
keyPath любой Путь ключа, где компоненты пути разделены точками. Компоненты пути могут быть ключами в объекте или индексами в массиве. Если keyPath не является строкой, он преобразуется в строку.

Синтаксис

getEventData(keyPath);

Связанные разрешения

read_event_data

getGoogleScript

Извлекает ресурс из заданного набора сценариев Google и возвращает обещание со сценарием и соответствующими метаданными кэширования.

Промис будет преобразован в объект, содержащий два ключа: script и metadata . Если запрос не выполнен, обещание будет отклонено с указанием reason .

Объект metadata будет содержать следующие метаданные кэширования на основе заголовков ответа ресурса; каждое поле будет присутствовать только в том случае, если соответствующий заголовок присутствует в ответе ресурса.

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

Пример

const getGoogleScript = require('getGoogleScript');

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

Синтаксис

getGoogleScript(script[, options]);

Параметры

Параметр Тип Описание
script нить Название скрипта. Поддерживаемые скрипты: 'ANALYTICS' , 'GTAG' и 'GTM' .

Параметр 'ANALYTICS' загружает скрипт Google Analytics с https://www.google-analytics.com/analytics.js .

Параметр 'GTAG' загружает скрипт глобального тега сайта (gtag.js) с https://www.googletagmanager.com/gtag/js .

Параметр 'GTM' загружает скрипт Диспетчера тегов Google со страницы https://www.googletagmanager.com/gtm.js .
options объект Необязательные параметры запроса. См. ниже поддерживаемые параметры.

Параметры

Вариант Тип Описание
id нить Применимо к 'GTAG' с идентификатором измерения gtag и 'GTM' с идентификатором веб-контейнера (например, GTM-XXXX).
debug любой Если верно, запрашивает и возвращает отладочную версию сценария измерения.
timeout число Время ожидания запроса в миллисекундах; неположительные значения игнорируются. Если время запроса истекло, обратный вызов будет вызван с undefined для значения скрипта и {} для объекта метаданных.

Нераспознанные клавиши опций игнорируются.

Связанные разрешения

Требуется разрешение send_http . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • Разрешить домены Google

getRemoteAddress

Возвращает строковое представление IP-адреса, с которого был отправлен запрос, например 12.345.67.890 для IPv4 или 2001:0db8:85a3:0:0:8a2e:0370:7334 для IPv6, путем чтения заголовков запроса, таких как Forwarded и X-Forwarded- Для. Примечание. Этот API делает все возможное для обнаружения исходного IP-адреса, но не может гарантировать точность результата.

Синтаксис

getRemoteAddress();

Связанные разрешения

Требуется разрешение read_request . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • Заголовки Forwarded и X-Forwarded-For
  • Удаленный IP-адрес

getRequestBody

Возвращает тело запроса в виде строки , если она присутствует, или undefined в противном случае.

Синтаксис

getRequestBody();

Связанные разрешения

read_request

getRequestHeader

Возвращает значение именованного заголовка запроса в виде строки , если он присутствует, или undefined в противном случае. Если заголовок повторяется, возвращаемые значения объединяются с помощью ', ' .

Пример

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Синтаксис

getRequestHeader(headerName);

Параметры

Параметр Тип Описание
headerName нить Имя заголовка. Это значение нечувствительно к регистру.

Связанные разрешения

read_request

getRequestMethod

Возвращает метод запроса, например 'GET' или 'POST' , в виде строки .

Пример

const getRequestMethod = require('getRequestMethod');

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

Синтаксис

getRequestMethod();

Связанные разрешения

Никто.

getRequestPath

Возвращает путь запроса без строки запроса. Например, если URL-адрес '/foo?id=123' , возвращается '/foo' . Автоматически удаляет префикс URL-адреса контейнера сервера из пути. Например, если URL-адрес контейнера сервера — https://example.com/analytics , а путь запроса — '/analytics/foo' , возвращается '/foo' .

Пример

const getRequestPath = require('getRequestPath');

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

Синтаксис

getRequestPath();

Связанные разрешения

read_request

getRequestQueryParameter

Возвращает декодированное значение именованного параметра строки запроса в виде строки или undefined , если параметр отсутствует. Если параметр повторяется в строке запроса, будет возвращено первое значение, появившееся в строке запроса.

Пример

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Синтаксис

getRequestQueryParameter(name);

Параметры

Параметр Тип Описание
name нить Имя параметра запроса.

Связанные разрешения

read_request

getRequestQueryParameters

Возвращает параметры запроса входящего HTTP-запроса в виде объекта, который сопоставляет имена параметров запроса с соответствующим значением или значениями. Имена и значения параметров декодируются.

Пример

const getRequestQueryParameters = require('getRequestQueryParameters');

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

Синтаксис

getRequestQueryParameters();

Связанные разрешения

read_request

getRequestQueryString

Возвращает запрос запроса в виде строки без ведущего вопросительного знака или пустой строки, если URL-адрес запроса не содержит строку запроса.

Пример

const getRequestQueryString = require('getRequestQueryString');

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

Синтаксис

getRequestQueryString();

Связанные разрешения

read_request

getTimestamp

Устарело. Предпочитайте getTimestampMillis .

Возвращает число , представляющее текущее время в миллисекундах с эпохи Unix, возвращаемое Date.now() .

Синтаксис

getTimestamp();

Связанные разрешения

Никто.

getTimestampMillis

Возвращает число , представляющее текущее время в миллисекундах с эпохи Unix, возвращаемое Date.now() .

Синтаксис

getTimestampMillis();

Связанные разрешения

Никто.

getType

Возвращает строку, описывающую тип данного значения.

Тип ввода Возвращаемое значение
нить 'string'
число 'number'
логический 'boolean'
нулевой 'null'
неопределенный 'undefined'
Множество 'array'
Объект 'object'
Функция 'function'

Пример

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

Синтаксис

getType(value);

Параметры

Параметр Тип Описание
value любой Введите значение.

Связанные разрешения

Никто.

isRequestMpv1

Возвращает true , если входящий запрос является запросом Measurement Protocol V1, или false в противном случае.

Пример

const isRequestMpv1 = require('isRequestMpv1');

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

Синтаксис

isRequestMpv1();

Связанные разрешения

Никто.

isRequestMpv2

Возвращает true , если входящий запрос является запросом Measurement Protocol V2, или false в противном случае.

Пример

const isRequestMpv2 = require('isRequestMpv2');

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

Синтаксис

isRequestMpv2();

Связанные разрешения

Никто.

logToConsole

Записывает свои аргументы в консоль.

Эти журналы видны в Logs Explorer в Google Cloud Console. В обозревателе журналов запустите запрос logName =~ "stdout" , чтобы просмотреть записи журнала, созданные этим API.

Пример

const logToConsole = require('logToConsole');

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

Синтаксис

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

Параметры

API принимает один или несколько аргументов, каждый из которых при необходимости преобразуется в строку и выводится на консоль.

Связанные разрешения

logging

makeInteger

Преобразует заданное значение в число (целое).

Синтаксис

makeInteger(value);

Параметры

Параметр Тип Описание
value любой тип Значение для преобразования.

Связанные разрешения

Никто.

makeNumber

Преобразует заданное значение в число .

Синтаксис

makeNumber(value);

Параметры

Параметр Тип Описание
value любой тип Значение для преобразования.

Связанные разрешения

Никто.

makeString

Возвращает заданное значение в виде строки .

Синтаксис

makeString(value);

Параметры

Параметр Тип Описание
value любой тип Значение для преобразования.

Связанные разрешения

Никто.

makeTableMap

Преобразует простой табличный объект с двумя столбцами в Map . Это используется для преобразования поля шаблона SIMPLE_TABLE с двумя столбцами в более удобный формат.

Например, эта функция может преобразовать объект таблицы:

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

в карту:

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

Возвращает Object : преобразованная Map пар ключ-значение была добавлена ​​к нему или null в противном случае.

Синтаксис

makeTableMap(tableObj, keyColumnName, valueColumnName);

Параметры

Параметр Тип Описание
tableObj Список Объект таблицы для преобразования. Это список карт, где каждая Map представляет строку в таблице. Каждое имя свойства в объекте строки является именем столбца, а значение свойства является значением столбца в строке.
keyColumnName нить Имя столбца, значения которого станут ключами в преобразованном Map .
valueColumnName нить Имя столбца, значения которого станут значениями в преобразованном Map .

Связанные разрешения

Никто.

parseUrl

Возвращает объект, содержащий все составные части заданного URL-адреса, аналогично объекту URL .

Этот API будет возвращать undefined для любого неправильно сформированного URL-адреса. Для правильно отформатированных URL-адресов поля, отсутствующие в строке URL-адреса, будут иметь значение пустой строки или, в случае searchParams , пустой объект.

Возвращаемый объект будет иметь следующие поля:

{
  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,
}

Пример

const parseUrl = require('parseUrl');

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

Синтаксис

parseUrl(url);

Параметры

Параметр Тип Описание
url нить Полный URL-адрес, который будет проанализирован.

Связанные разрешения

Никто.

returnResponse

Сбрасывает ответ, который ранее был установлен другими шаблонами, используя API-интерфейсы, которые изменяют ответ, включая setCookie , setPixelResponse , setResponseBody , setResponseHeader и setResponseStatus . По умолчанию используется код состояния HTTP 200, пустое тело и отсутствие заголовков.

Рекомендуется использовать этот API из клиентского шаблона.

Синтаксис

returnResponse();

Пример

См. пример runContainer .

Связанные разрешения

return_response

runContainer

Запускает логику контейнера (переменные, триггеры, теги) в рамках события. Если этот API вызывается во время выполнения контейнера, контейнер запускается снова.

Обратные вызовы onComplete и onStart получают функцию с именем bindToEvent . Используйте bindToEvent для запуска API в контексте события. Дополнительные сведения см. в примере addEventCallback .

Рекомендуется использовать этот API из клиентского шаблона.

Пример

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

Синтаксис

runContainer(event, onComplete, onStart);

Параметры

Параметр Тип Описание
event объект Параметры события.
onComplete функция Обратный вызов, который вызывается после завершения срабатывания всех тегов.
onStart функция Обратный вызов, который вызывается немедленно, до того, как теги начнут активироваться.

Связанные разрешения

run_container

sendEventToGoogleAnalytics

Отправляет одно событие с использованием общих данных о событиях в Google Analytics и возвращает обещание , которое разрешается в объект с ключом location или отклоняется в объект с ключом reason . Назначение, Universal Analytics или Google Analytics 4, основано на идентификаторе измерения в данных события.

В поле location устанавливается заголовок location , если он присутствует.

Пример

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();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

Синтаксис

sendEventToGoogleAnalytics(event);

Параметры

Параметр Тип Описание
event объект Мероприятие в формате Unified Schema.

Связанные разрешения

Требуется разрешение send_http . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • Разрешить домены Google

sendHttpGet

Отправляет HTTP-запрос GET к указанному URL-адресу и возвращает обещание , которое разрешается с результатом после завершения запроса или истечения времени ожидания.

Разрешенный результат — это объект, содержащий три ключа: statusCode , headers и body . Если запрос не удался (например, неверный URL-адрес, нет маршрута к хосту, сбой согласования SSL и т. д.), обещание будет отклонено с: {reason: 'failed'} . Если была установлена ​​опция timeout и время запроса истекло, обещание будет отклонено с: {reason: 'timed_out'}

Пример

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

Синтаксис

sendHttpGet(url[, options]);

Параметры

Параметр Тип Описание
url нить URL-адрес запроса.
options объект Необязательные параметры запроса. Поддерживаемые параметры: заголовки и тайм-аут . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)

Параметры

  • headers : дополнительные заголовки запроса, представленные в виде объекта.
  • timeout : Тайм-аут в миллисекундах, прежде чем запрос будет прерван. По умолчанию 15000 .

Связанные разрешения

send_http

sendHttpRequest

Делает HTTP-запрос к указанному URL-адресу и возвращает обещание , которое разрешается с ответом после завершения запроса или истечения времени ожидания.

Разрешенный результат — это объект, содержащий три ключа: statusCode , headers и body . Если запрос не удался (например, неверный URL-адрес, нет маршрута к хосту, сбой согласования SSL и т. д.), обещание будет отклонено с: {reason: 'failed'} . Если была установлена ​​опция timeout и время запроса истекло, обещание будет отклонено с: {reason: 'timed_out'}

Пример

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

Синтаксис

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

Параметры

Параметр Тип Описание
url нить URL-адрес запроса.
options объект Необязательные параметры запроса. Поддерживаемые параметры: заголовки , метод и время ожидания . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)
body нить Необязательное тело запроса.

Параметры

  • headers : Дополнительные заголовки запроса.
  • method : метод запроса, по умолчанию «GET».
  • timeout : Тайм-аут в миллисекундах, прежде чем запрос будет прерван. По умолчанию 15000 .

Связанные разрешения

send_http

sendPixelFromBrowser

Отправляет команду браузеру для загрузки предоставленного URL-адреса в виде тега <img> . Этот командный протокол поддерживается веб-тегами Google Analytics: Конфигурация GA4 и Google Analytics: Событие GA . Вы должны включить опцию Отправить в серверный контейнер в теге конфигурации. См. инструкции для более подробной информации.

Этот API возвращает false , если входящий запрос не поддерживает командный протокол или если ответ уже был сброшен. В противном случае этот API возвращает true .

Пример:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Синтаксис

sendPixelFromBrowser(url)

Параметры

Параметр Тип Описание
url нить URL для отправки в браузер.

Связанные разрешения

send_pixel_from_browser

setCookie

Устанавливает или удаляет файл cookie с указанными параметрами.

Чтобы удалить файл cookie, необходимо установить файл cookie с тем же путем и доменом, с которым файл cookie был создан, и присвоить ему значение срока действия, которое находится в прошлом, например "Thu, 01 Jan 1970 00:00:00 GMT" .

Обратите внимание, что для отправки ответа клиенту необходимо вызвать функцию returnResponse .

Пример

const setCookie = require('setCookie');

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

Синтаксис

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

Параметры

Параметр Тип Описание
name нить Имя файла cookie. Имя нечувствительно к регистру.
value нить Значение файла cookie.
options объект Необязательные атрибуты файлов cookie: domain , expires , fallbackDomain , httpOnly , maxage , path , secure и sameSite . (См. Параметры ниже.)
noEncode логический Если true, значение cookie не будет закодировано. По умолчанию false .

Параметры

  • домен: Хост, на который будет отправлен файл cookie. Если установлено специальное значение «auto», то хост будет автоматически вычисляться с использованием следующей стратегии:

    • eTLD+1 заголовка Forwarded , если он присутствует.
    • eTLD+1 заголовка X-Forwarded-Host , если он присутствует.
    • eTLD+1 заголовка Host .

  • expires : максимальное время жизни файла cookie. Это должна быть строка даты в формате UTC, например «Сб, 26 октября 1985 г., 08:21:00 по Гринвичу». Если установлены оба expires и max-age , max-age имеет приоритет.

  • httpOnly : запрещает JavaScript доступ к куки, если true .

  • max-age : количество секунд до истечения срока действия файла cookie. Нулевое или отрицательное число немедленно истечет срок действия файла cookie. Если установлены оба expires и max-age , max-age имеет приоритет.

  • path : путь, который должен существовать в запрошенном URL-адресе, иначе браузер не отправит заголовок Cookie.

  • secure : если установлено значение true , файл cookie отправляется на сервер только при выполнении запроса с конечной точки https:

  • sameSite : утверждает, что файл cookie не должен отправляться с запросами из разных источников. Должно быть 'strict' , 'lax' или 'none' .

Связанные разрешения

set_cookie

setPixelResponse

Устанавливает тело ответа в GIF 1x1, устанавливает заголовок Content-Type в «image/gif», устанавливает заголовки кэширования, чтобы пользовательские агенты не кэшировали ответ, и устанавливает статус ответа на 200.

Обратите внимание, что для отправки ответа клиенту необходимо вызвать функцию returnResponse .

Синтаксис

setPixelResponse();

Связанные разрешения

Требуется разрешение access_response . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • headers - должны разрешать следующие ключи
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

Устанавливает тело ответа в аргумент.

Обратите внимание, что для отправки ответа клиенту необходимо вызвать функцию returnResponse .

Синтаксис

setResponseBody(body[, encoding]);

Параметры

Параметр Тип Описание
body нить Значение для установки в качестве тела ответа.
encoding нить Кодировка символов тела ответа (по умолчанию 'utf8' ). Поддерживаемые значения включают 'ascii' , 'utf8' , 'utf16le' , 'ucs2' , 'base64' , 'latin1' , 'binary' и 'hex' .

Связанные разрешения

Требуется разрешение access_response . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • body

setResponseHeader

Устанавливает заголовок в ответе, который будет возвращен. Если заголовок с этим именем (без учета регистра) ранее был установлен этим API, последний вызов перезапишет или очистит значение, установленное предыдущим вызывающим.

Обратите внимание, что для отправки ответа клиенту необходимо вызвать функцию returnResponse .

Синтаксис

setResponseHeader(name, value);

Параметры

Параметр Тип Описание
name нить Имя заголовка. Имена заголовков HTTP нечувствительны к регистру, поэтому имя заголовка будет в нижнем регистре.
value строка не определена Значение заголовка. Если значение null или undefined, это очищает именованный заголовок из ответа, который будет возвращен.

Связанные разрешения

Требуется разрешение access_response . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • headers

setResponseStatus

Устанавливает код состояния HTTP ответа, который будет возвращен.

Обратите внимание, что для отправки ответа клиенту необходимо вызвать функцию returnResponse .

Синтаксис

setResponseStatus(statusCode);

Параметры

Параметр Тип Описание
statusCode число Возвращаемый код состояния HTTP.

Связанные разрешения

Требуется разрешение access_response . Разрешение должно быть настроено так, чтобы разрешать доступ как минимум к:

  • status

sha256

Вычисляет дайджест SHA-256 ввода и вызывает обратный вызов с дайджестом, закодированным в base64, если только объект options не указывает другую кодировку вывода.

Эта сигнатура и поведение API соответствуют API sha256 для веб-контейнеров; однако пользовательские шаблоны в серверных контейнерах должны использовать API sha256Sync для более простого кода.

Пример

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

Синтаксис

sha256(input, onSuccess, options = undefined);

Параметры

Параметр Тип Описание
input нить Строка для хеширования.
onSuccess функция Вызывается с результирующим дайджестом, закодированным в base64, если только объект options не указывает другую кодировку вывода.
options объект Необязательный объект опций для указания выходной кодировки. Если указано, объект должен содержать ключ outputEncoding со значением base64 или hex .

Связанные разрешения

Никто.

sha256Sync

Вычисляет и возвращает дайджест SHA-256 ввода, закодированного в base64, если только объект options не указывает другую кодировку вывода.

Пример

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

Синтаксис

sha256Sync(input, options = undefined);

Параметры

Параметр Тип Описание
input нить Строка для хеширования.
options объект Необязательный объект опций для указания выходной кодировки. Если указано, объект должен содержать ключ outputEncoding со значением base64 или hex .

Связанные разрешения

Никто.

templateDataStorage

Возвращает объект с методами доступа к хранилищу данных шаблона. Хранилище данных шаблона позволяет совместно использовать данные при выполнении одного шаблона. Данные, хранящиеся в хранилище данных шаблона, сохраняются на сервере, на котором запущен контейнер. В большинстве случаев на контейнере работает несколько серверов, поэтому хранение данных в хранилище данных шаблона не гарантирует, что каждый последующий запрос будет иметь доступ к данным.

«Данные» в названии «templateDataStorage» относятся к тому факту, что с помощью этого API могут храниться только простые, нефункциональные типы данных. Вместо этого любые функции или ссылки на функции, переданные в API, будут храниться как null .

Синтаксис

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

Пример

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
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);
});

Связанные разрешения

access_template_storage

testRegex

Проверяет строку на соответствие регулярному выражению, созданному с помощью API createRegex . Возвращает true , если регулярное выражение совпадает. В противном случае возвращает false .

Регулярное выражение, созданное с глобальным флагом, сохраняет состояние. Подробности смотрите в документации RegExp .

Пример

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

Синтаксис

testRegex(regex, string);

Параметры

Параметр Тип Описание
regex Объект Регулярное выражение для проверки, возвращенное API createRegex.
string нить Тестовая строка для проверки.

Связанные разрешения

Никто.

toBase64

Кодирует строку как base64.

Синтаксис

toBase64(input);

Параметры

Параметр Тип Описание
input нить Строка для кодирования.

Пример

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Связанные разрешения

Никто.

BigQuery

Возвращает объект, предоставляющий функции BigQuery.

Функция BigQuery.insert позволяет записывать данные в таблицу BigQuery. Он возвращает обещание , которое разрешается при успешной вставке или отклоняется при ошибке.

Когда вставка завершается успешно, обещание разрешается без аргументов.

Если вставка не удалась, обещание отклоняется со списком объектов, содержащих причину ошибки и, возможно, объект строки, если возникает ошибка. Часть запроса может быть выполнена успешно, а другая часть — нет. В этом случае обещание отклоняется со списком ошибок для каждой строки с объектом строки, чтобы помочь определить, какие строки были вставлены (см. примеры ошибок ниже). Дополнительные сведения см. в документации BigQuery по сообщениям об ошибках .

Синтаксис

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

Параметры

Параметр Тип Описание
connectionInfo объект Определяет информацию, необходимую для подключения к таблице BigQuery. Есть один необязательный параметр и два обязательных параметра:
  • projectId — необязательный идентификатор проекта Google Cloud Platform. Если этот параметр не указан, projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT , если для параметра разрешения access_bigquery для идентификатора проекта задано значение * или GOOGLE_CLOUD_PROJECT . Если контейнер сервера работает в Google Cloud, GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта Google Cloud.
  • datasetId — идентификатор набора данных BigQuery.
  • tableId — идентификатор таблицы BigQuery.
rows Множество Строки для вставки в таблицу.
options объект Необязательные параметры запроса. Поддерживаемые параметры: ignoreUnknownValues ​​и skipInvalidRows . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)

Параметры

Параметр Тип Описание
ignoreUnknownValues логический Если установлено значение true , то принимаются строки, содержащие значения, не соответствующие схеме. Неизвестные значения игнорируются. По умолчанию false .
skipInvalidRows логический Если установлено значение true , вставьте все допустимые строки запроса, даже если существуют недопустимые строки. По умолчанию false .

Примеры ошибок

Ошибка «Модуль не найден» означает, что на вашем серверном контейнере, вероятно, работает более старая версия нашего образа, которая еще не включала модуль BigQuery. Повторно разверните контейнер сервера с теми же настройками, используя наш сценарий развертывания . Модуль будет автоматически включен после завершения операции.

Ошибка, не связанная с вставкой, обычно имеет один объект ошибки с ключом reason :

[{reason: 'invalid'}]

Ошибка вставки может содержать несколько объектов ошибок с массивом errors и объектом row . Ниже приведен пример ответа об ошибке при вставке двух строк, где только одна строка содержит ошибку:

[
  {
    "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
    }
  }
]

Пример

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

Связанные разрешения

access_bigquery

Firestore

Возвращает объект, предоставляющий функции Firestore.

Этот API поддерживает только Firestore в собственном режиме , а не Firestore в режиме хранилища данных .

Firestore.read

Функция Firestore.read считывает данные из документа Firestore и возвращает обещание , которое преобразуется в объект, содержащий два ключа: id и data . Если документ не существует, обещание отклоняется с объектом, содержащим ключ reason , равный not_found .

Синтаксис

Firestore.read(path[, options]);

Параметры

Параметр Тип Описание
path нить Путь к документу или коллекции. Не должен начинаться или заканчиваться символом «/».
options объект Необязательные параметры запроса. Поддерживаемые параметры: projectId , disableCache и transaction . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)

Параметры

Параметр Тип Описание
projectId нить Опционально . Идентификатор проекта Google Cloud Platform. Если этот параметр не указан, projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT , если для параметра доступа access_firestore для идентификатора проекта задано значение * или GOOGLE_CLOUD_PROJECT . Если контейнер сервера работает в Google Cloud, GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта Google Cloud.
disableCache логический Опционально . Определяет, следует ли отключать кеш. Кэширование включено по умолчанию, что позволяет кэшировать результаты на время выполнения запроса.
transaction нить Опционально . Значение, полученное из Firestore.runTransaction(). Помечает операцию, которая будет использоваться в транзакции.

Пример

const Firestore = require('Firestore');

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

Firestore.write

Функция Firestore.write записывает данные в документ или коллекцию Firestore. Если путь указан к коллекции, документ будет создан со случайно сгенерированным идентификатором. Если путь указан к документу, а он не существует, он будет создан. Этот API возвращает обещание, которое преобразуется в идентификатор добавленного или измененного документа. Если используется опция транзакции, API по-прежнему возвращает обещание, но не будет содержать идентификатор, поскольку записи выполняются пакетно.

Синтаксис

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

Параметры

Параметр Тип Описание
path нить Путь к документу или коллекции. Не должен начинаться или заканчиваться символом «/».
input объект Значение для записи в документ. Если параметр слияния установлен, API объединит ключи из ввода в документ.
options объект Необязательные параметры запроса. Поддерживаемые параметры: projectId , merge и transaction . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)

Параметры

Параметр Тип Описание
projectId нить Опционально . Идентификатор проекта Google Cloud Platform. Если этот параметр не указан, projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT , если для параметра доступа access_firestore для идентификатора проекта задано значение * или GOOGLE_CLOUD_PROJECT . Если контейнер сервера работает в Google Cloud, GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта Google Cloud.
merge логический Опционально . Если установлено значение true , то ключи из ввода объединяются в документ, иначе метод переопределит весь документ. По умолчанию false .
transaction нить Опционально . Значение, полученное из Firestore.runTransaction(). Помечает операцию, которая будет использоваться в транзакции.

Пример

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

Функция Firestore.query запрашивает данную коллекцию и возвращает обещание, которое разрешается в массив документов Firestore, соответствующих условиям запроса. Объект документа Firestore такой же, как указано выше в Firestore.read . Если нет документов, соответствующих условиям запроса, возвращенное обещание будет преобразовано в пустой массив.

Синтаксис

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

Параметры

Параметр Тип Описание
collection нить Путь к коллекции. Не должен начинаться или заканчиваться символом «/».
queryConditions Множество Массив условий запроса. Каждый запрос приходит в виде массива с тремя значениями: ключ , оператор и ожидаемое значение . Например: [['id', '<', '5'], ['state', '==', 'CA']].

Условия объединяются по И для создания результата запроса. Пожалуйста, обратитесь к операторам запросов Firestore для получения списка совместимых операторов запросов.
options объект Необязательные параметры запроса. Поддерживаемые параметры: projectId , disableCache , limit и transaction . Неизвестные ключи опций игнорируются. (См. Параметры ниже.)

Параметры

Параметр Тип Описание
projectId нить Опционально . Идентификатор проекта Google Cloud Platform. Если этот параметр не указан, projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT , если для параметра доступа access_firestore для идентификатора проекта задано значение * или GOOGLE_CLOUD_PROJECT . Если контейнер сервера работает в Google Cloud, GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта Google Cloud.
disableCache логический Опционально . Определяет, следует ли отключать кеш. Кэширование включено по умолчанию, что позволяет кэшировать результаты на время выполнения запроса.
limit число Опционально . Изменяет максимальное количество результатов, возвращаемых запросом, по умолчанию 5 .
transaction нить Опционально . Значение, полученное из Firestore.runTransaction(). Помечает операцию, которая будет использоваться в транзакции.

Пример

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 Тип 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 must return 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 Тип 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 (eg 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 (eg 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 Тип 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 non-operational when not in test mode. Mocks are reset before each test is run.

Syntax

mock(apiName, returnValue);

Parameters

Parameter Тип 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();
});

runCode

Runs the code for the template, ie the content of the Code tab, in the current test environment with a given input data object.

Syntax

runCode(data)

Parameters

Parameter Тип 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'});