Примечание. Этот сайт для разработчиков будет перенесен на новый адрес developers.google.com/tag-platform к 30 сентября 2021 г.

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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В этой статье описаны API добавления тегов на стороне сервера.

addEventCallback

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

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

Синтаксис

const addEventCallback = require('addEventCallback');

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

Параметры

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

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

Название ключа Тип Описание
tags Array Массив объектов с данными о тегах. Содержит записи о каждом теге, активированном во время события. Объект с данными о теге имеет такую структуру: идентификатор тега (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 function Вызываемая функция.

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

Нет.

claimRequest

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

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

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

Пример

const claimRequest = require('claimRequest');

claimRequest();

Синтаксис

claimRequest();

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

Нет.

computeEffectiveTldPlusOne

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

Если аргументом является null или undefined, его значение возвращается без изменений. В противном случае аргумент преобразуется в строку. Если аргументом не является действительный домен или 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 string Домен или URL, по которым определяется eTLD+1.

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

Нет.

decodeUri

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

Пример

const decodeUri = require('decodeUri');

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

Синтаксис

decodeUri(encoded_uri);

Параметры

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

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

Нет.

decodeUriComponent

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

Пример

const decodeUriComponent = require('decodeUriComponent');

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

Синтаксис

decodeUriComponent(encoded_uri_component);

Параметры

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

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

Нет.

encodeUri

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

Пример

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

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

Синтаксис

encodeUri(uri);

Параметры

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

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

Нет.

encodeUriComponent

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

Пример

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

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

Синтаксис

encodeUriComponent(str);

Параметры

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

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

Нет.

extractEventsFromMpv1

Преобразует входящий запрос Measurement Protocol версии 1 в список событий в формате 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 версии 2 в список событий в формате 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 string Строка в кодировке 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 number Минимальное возможное возвращаемое значение (включительно).
max number Максимальное возможное возвращаемое значение (включительно).

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

Нет.

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 string Имя файла cookie.
noDecode boolean При значении 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 и инициирует указанный обратный вызов с помощью этого скрипта и соответствующих метаданных кеширования.

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

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

Пример

const getGoogleScript = require('getGoogleScript');

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

Синтаксис

getGoogleScript(script, callback[, options]);

Параметры

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

Вариант 'ANALYTICS' вызывает скрипт Google Аналитики по адресу https://www.google-analytics.com/analytics.js.

Вариант 'GTAG' вызывает скрипт глобального тега (gtag.js) по адресу https://www.googletagmanager.com/gtag/js.

Вариант 'GTM' вызывает скрипт Google Менеджера тегов по адресу https://www.googletagmanager.com/gtm.js.
callback function Выполняет обратный вызов с помощью скрипта и его метаданных или возвращает пустой объект метаданных с типом undefined, если запрос не выполнен или превышено время ожидания.
options object Необязательные параметры запроса. Поддерживаемые параметры указаны ниже.

Дополнительные параметры

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

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

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

Требует разрешения send_http с доступом как минимум к следующим данным:

  • Настройка "Разрешить домены Google".

getRemoteAddress

Возвращает строку с исходным IP-адресом запроса (например, 12.345.67.890 для IPv4 или 2001:0db8:85a3:0:0:8a2e:0370:7334 для IPv6) путем чтения таких заголовков запросов, как Forwarded и X-Forwarded-For. Примечание. Этот 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 string Название заголовка. Регистр не учитывается.

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

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 string Название параметра запроса.

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

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

Поддержка прекращена. Предпочитаемый API – getTimestampMillis.

Выводит число с текущим Unix-временем в миллисекундах, возвращенным функцией Date.now().

Синтаксис

getTimestamp();

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

Нет.

getTimestampMillis

Выводит число с текущим Unix-временем в миллисекундах, возвращенным функцией Date.now().

Синтаксис

getTimestampMillis();

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

Нет.

getType

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

Тип входных данных Возвращаемое значение
string 'string'
number 'number'
boolean 'boolean'
null 'null'
undefined 'undefined'
Array 'array'
Object 'object'
Function '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

Если входящий запрос создан с помощью Measurement Protocol версии 1, возвращает значение true, а если нет, то false.

Пример

const isRequestMpv1 = require('isRequestMpv1');

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

Синтаксис

isRequestMpv1();

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

Нет.

isRequestMpv2

Если входящий запрос создан с помощью Measurement Protocol версии 2, возвращает значение true, а если нет, то false.

Пример

const isRequestMpv2 = require('isRequestMpv2');

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

Синтаксис

isRequestMpv2();

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

Нет.

logToConsole

Вносит аргументы в журнал консоли.

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

Пример

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

Возвращаемый объект: ассоциативный массив Map (если в него при преобразовании были добавлены пары "ключ-значение") или значение null.

Синтаксис

makeTableMap(tableObj, keyColumnName, valueColumnName);

Параметры

Параметр Тип Описание
tableObj List Таблица, которую нужно преобразовать. Представляет собой список массивов, в котором каждому объекту Map соответствует одна строка в таблице. Имена свойств в строках являются названиями столбцов, а значения этих свойств – значениями столбцов в строке.
keyColumnName string Название столбца, значения из которого станут ключами в полученном массиве Map.
valueColumnName string Название столбца, значения из которого станут значениями в полученном массиве Map.

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

Нет.

parseUrl

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

Если формат URL неверный, этот API будет возвращать код undefined. При правильном формате 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 string Полный 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 object Параметры события.
onComplete function Обратный вызов, выполняемый после активации всех тегов.
onStart function Обратный вызов, выполняемый немедленно, ещё до активации тегов.

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

run_container

sendEventToGoogleAnalytics

Отправляет в Google Аналитику событие в формате Unified Schema.

Пример

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, (response) => {
  if (!response.success) {
    setResponseStatus(500);
    data.gtmOnFailure();
    return;
  }

  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
});

Синтаксис

sendEventToGoogleAnalytics(event, callback);

Параметры

Параметр Тип Описание
event object Событие в формате Unified Schema.
callback function Необязательный обратный вызов, выполняемый по окончании обращения к Google Аналитике. Он выполняется с помощью объекта, содержащего поля success и location.

Поле success принимает значение true при получении кода ответа 200 или 302. В противном случае возвращается значение false. Если в ответе присутствует заголовок location, его значение указывается в поле location.

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

Требует разрешения send_http с доступом как минимум к следующим данным:

  • Настройка "Разрешить домены Google".

sendHttpGet

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

Пример

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends a GET request and nominates response
// based on the response from the GET request.
sendHttpGet('https://example.com/collect', (statusCode, headers, body) => {
  setResponseBody(body);
  setResponseHeader('cache-control', headers['cache-control']);
  setResponseStatus(statusCode);
}, {headers: {key: 'value'}, timeout: 500});

Синтаксис

sendHttpGet(url[, callback[, options]]);

Параметры

Параметр Тип Описание
url string URL запроса.
callback function Необязательный обратный вызов, выполняемый по завершении запроса, при возникновении ошибки или превышении времени ожидания.

Он выполняется с помощью таких параметров, как код статуса ответа, заголовки ответа и тело ответа (или значения undefined при отсутствии тела ответа).
Если запрос не выполняется (например, из-за неправильного URL, отсутствия маршрута к хосту, сбоя SSL-обмена и т. д.), обратный вызов инициируется нулевым кодом статуса ответа, отсутствием заголовков и значением undefined для тела ответа.
Если задан параметр 'timeout' и время ожидания запроса превышено, обратный вызов выполняется с помощью таких параметров, как код статуса ответа -1, отсутствие заголовков и значение undefined для тела ответа.
options object Необязательные параметры запроса. Поддерживаемые параметры: headers и timeout. Неизвестные ключи параметров игнорируются (см. раздел Дополнительные параметры ниже).

Дополнительные параметры

  • headers: дополнительные заголовки запроса, представленные в виде объекта.
  • timeout: время ожидания в миллисекундах до прерывания запроса.

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

send_http

sendHttpRequest

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

Пример

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', (statusCode, headers, body) => {
  setResponseStatus(statusCode);
  setResponseBody(body);
  setResponseHeader('cache-control', headers['cache-control']);
}, {headers: {key: 'value'}, method: 'POST', timeout: 500}, postBody);

Синтаксис

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

Параметры

Параметр Тип Описание
url string URL запроса.
callback function Необязательный обратный вызов, выполняемый по завершении запроса, при возникновении ошибки или превышении времени ожидания.

Он выполняется с помощью таких параметров, как код статуса ответа, заголовки ответа и тело ответа (или значения undefined при отсутствии тела ответа).
Если запрос не выполняется (например, из-за неправильного URL, отсутствия маршрута к хосту, сбоя SSL-обмена и т. д.), обратный вызов инициируется нулевым кодом статуса ответа, отсутствием заголовков и значением undefined для тела ответа.
Если задан параметр timeout и время ожидания запроса превышено, обратный вызов выполняется с помощью таких параметров, как код статуса ответа -1, отсутствие заголовков и значение undefined для тела ответа.
options object Необязательные параметры запроса. Поддерживаемые параметры: headers, method и timeout. Неизвестные ключи параметров игнорируются (см. раздел Дополнительные параметры ниже).
body string Необязательное тело запроса.

Дополнительные параметры

  • headers: дополнительные заголовки запроса.
  • method: методом запроса по умолчанию является GET.
  • timeout: время ожидания в миллисекундах до прерывания запроса.

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

send_http

sendPixelFromBrowser

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

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

Пример

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Синтаксис

sendPixelFromBrowser(url)

Параметры

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

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

send_pixel_from_browser

setCookie

Создает или удаляет файл 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 string Название файла cookie без учета регистра.
value string Значение файла cookie.
options object Необязательные атрибуты файлов cookie: domain, expires, fallbackDomain, httpOnly, max-age, path, secure, sameSite (см. раздел Дополнительные параметры ниже).
noEncode boolean Если параметр – true, значение файла cookie не кодируется. Значение по умолчанию – false.

Дополнительные параметры

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

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

  • expires: срок действия файла cookie. Параметр должен быть задан в формате UTC (например, "Sat, 26 Oct 1985 08:21:00 GMT"). Если заданы параметры expires и max-age, то max-age является приоритетным.

  • httpOnly: если задано значение true, то доступ к файлу cookie с помощью JavaScript будет запрещен.

  • 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 размером 1 x 1, указывает в заголовке Content-Type "image/gif", настраивает заголовки кеширования так, чтобы агенты пользователя не могли кешировать ответ, и задает для ответа код статуса 200.

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

Синтаксис

setPixelResponse();

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

Требует разрешения access_response с доступом как минимум к следующим данным:

  • headers – необходимы следующие ключи:
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

Задает аргумент как тело ответа.

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

Синтаксис

setResponseBody(body[, encoding]);

Параметры

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

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

Требует разрешения access_response с доступом как минимум к следующим данным:

  • body

setResponseHeader

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

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

Синтаксис

setResponseHeader(name, value);

Параметры

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

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

Требует разрешения access_response с доступом как минимум к следующим данным:

  • headers

setResponseStatus

Задает код статуса HTTP для возвращаемого ответа.

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

Синтаксис

setResponseStatus(statusCode);

Параметры

Параметр Тип Описание
statusCode number Возвращаемый код статуса 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 string Строка, которую необходимо хешировать.
onSuccess function Вызывается с полученным дайджестом, закодированным в base64, если только в объекте options не указана другая кодировка выходных данных.
options object Необязательный объект настроек, в котором можно задать кодировку выходных данных. Если объект используется, он должен содержать ключ 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 string Строка, которую необходимо хешировать.
options object Необязательный объект настроек, в котором можно задать кодировку выходных данных. Если объект используется, он должен содержать ключ outputEncoding со значением base64 или hex.

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

Нет.

templateDataStorage

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

Слово "data" (данные) в названии "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, (statusCode, headers, body) => {
  if (status >= 200 && status < 300) {
    setResponseBody(body);
    templateDataStorage.setItemCopy(data.key, body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(statusCode);
});

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

access_template_storage

toBase64

Кодирует строку в формате Base64.

Синтаксис

toBase64(input);

Параметры

Параметр Тип Описание
input string Кодируемая строка.

Пример

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

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

Нет.

BigQuery

Возвращает объект с функциями BigQuery.

Функция BigQuery.insert позволяет записывать данные в таблицу BigQuery.

Синтаксис

BigQuery.insert(connectionInfo, rows, options, onSuccess, onFailure);

Параметры

Параметр Тип Описание
connectionInfo object Определяет информацию, необходимую для подключения к таблице 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 Array Строки, которые нужно вставить в таблицу.
options object Необязательные параметры запроса. Поддерживаемые параметры: ignoreUnknownValues и skipInvalidRows. Неизвестные ключи параметров игнорируются (см. раздел Дополнительные параметры ниже).
onSuccess function Необязательный обратный вызов, выполняемый после успешной вставки данных. Обратный вызов выполняется без аргументов.
onFailure function Необязательный обратный вызов, выполняемый в случае ошибки. Вызывается со списком объектов, содержащих причину ошибки, и, возможно, объектом row. Часть запроса может быть выполнена успешно, а остальные части нет. В таком случае вызывается параметр onFailure со списком ошибок для каждой строки и объектом row, который помогает понять, какие строки были вставлены (см. раздел Примеры ошибок ниже). Более подробная информация по сообщениям об ошибках приведена в документации BigQuery.

Дополнительные параметры

Параметр Тип Описание
ignoreUnknownValues boolean Если установлено значение true, принимает строки, которые содержат значения, не соответствующие схеме. Неизвестные значения игнорируются. Значение по умолчанию – false.
skipInvalidRows boolean Если установлено значение 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, data.gtmOnSuccess, data.gtmOnFailure);

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

access_bigquery

JSON

Возвращает объект с функциями JSON.

Функция parse() анализирует строку JSON и создает описанный в ней объект или значение. Если строка JSON не поддается анализу (например, из-за неверного формата), возвращается значение undefined. А если тип входных данных – не string, они автоматически преобразуются в строку.

Функция stringify() преобразует входные данные в строку JSON. Если она не поддается анализу (например, потому что содержит цикл), возвращается значение undefined.

Пример

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

Синтаксис

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

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

Нет.

Math

Объект, предоставляющий математические функции Math.

Синтаксис

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

Параметры

Параметры математических функций преобразуются в числа.

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

Нет.

Messages

Эти API совместно обеспечивают передачу сообщений между разными частями контейнера.

addMessageListener

Добавляет функцию, прослушивающую сообщения заданного типа. Когда с помощью API sendMessage передается сообщение этого типа (обычно тегом), то синхронно выполняется обратный вызов с двумя параметрами:

  1. messageType:string
  2. message:Object

Если добавить обратный вызов в клиенте, вы будете получать сообщения обо всех событиях, генерируемых клиентом. Поэтому если вас интересуют сообщения только об определенном событии, привяжите API к этому событию с помощью команды bindToEvent в функции onStart API runContainer (см. пример).

Синтаксис

const addMessageListener = require('addMessageListener');

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

Параметры

Параметр Тип Описание
messageType string Тип прослушиваемых сообщений. Если тип этого значения – не string, оно автоматически преобразуется в строку.
callback function Обратный вызов, который выполняется при отправке сообщения заданного типа. Если тип этого значения – не function, API не сработает.

Пример

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

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

Требует разрешения use_message с доступом как минимум к следующим данным:

  • Тип сообщений с параметром Usage, имеющим значение listen или listen_and_send.

hasMessageListener

Возвращает значение true, если для заданного типа сообщений добавлен прослушиватель, и false, если нет.

Синтаксис

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

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

Нет.

sendMessage

Отправляет в зарегистрированный прослушиватель сообщение заданного типа. Может использоваться для пересылки сообщений из тега обратно в клиент, запустивший контейнер.

Синтаксис

const sendMessage = require('sendMessage');

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

Параметры

Параметр Тип Описание
messageType string Тип отправляемых сообщений. Если значение параметра – не string, оно автоматически преобразуется в строку.
message object Отправляемое сообщение. Если тип этого значения – не object, API не сработает.

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

Требует разрешения use_message с доступом как минимум к следующим данным:

  • Тип сообщений с параметром Usage, имеющим значение listen_and_send или send.

API тестирования

Используются для создания тестов, проверяющих работу изолированного JavaScript в пользовательских шаблонах Google Менеджера тегов. Для этих API не требуется оператор require(). Подробнее о тестировании пользовательских шаблонов…

assertApi

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

Синтаксис

assertApi(apiName)

Параметры

Параметр Тип Описание
apiName string Название тестируемого API (та же строка, которая передается require()).

Методы сопоставления

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

Примеры

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

assertThat

API assertThat смоделирован на основе библиотеки Google Truth. Он возвращает объект, с помощью которого можно проверять утверждения о значении исследуемого объекта. Если проверка утверждения дает неудачный результат, она сразу завершается и отмечается как неудачная. Впрочем, неудачный результат одной проверки не влияет на остальные.

Синтаксис

assertThat(actual, opt_message)

Параметры

Параметр Тип Описание
actual любой Значение, которое будет использоваться для быстрой проверки.
opt_message string Необязательное сообщение, которое будет показано, если утверждение окажется неверным.

Методы сопоставления

Метод сопоставления Описание
isUndefined() Проверяет утверждение о том, что субъект является undefined.
isDefined() Проверяет утверждение о том, что субъект не является undefined.
isNull() Проверяет утверждение о том, что субъект является null.
isNotNull() Проверяет утверждение о том, что субъект не является null.
isFalse() Проверяет утверждение о том, что субъект является false.
isTrue() Проверяет утверждение о том, что субъект является true.
isFalsy() Проверяет утверждение о том, что субъект имеет ложное значение. Ложными значениями считаются undefined, null, false, NaN, 0 и '' (пустая строка).
isTruthy() Проверяет утверждение о том, что субъект имеет истинное значение. Ложными значениями считаются undefined, null, false, NaN, 0 и '' (пустая строка).
isNaN() Проверяет утверждение о том, что значение не является числовым.
isNotNaN() Проверяет утверждение о том, что значение является любым, кроме нечислового.
isInfinity() Проверяет утверждение о том, что значение является положительной или отрицательной бесконечностью.
isNotInfinity() Проверяет утверждение о том, что значение является любым, кроме положительной или отрицательной бесконечности.
isEqualTo(expected) Проверяет утверждение о том, что значение равно указанному. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
isNotEqualTo(expected) Проверяет утверждение о том, что значение субъекта не равно указанному значению. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
isAnyOf(...expected) Проверяет утверждение о том, что значение равно одному из указанных. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
isNoneOf(...expected) Проверяет утверждение о том, что значение не равно указанным. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
isStrictlyEqualTo(expected) Проверяет утверждение о том, что значение субъекта строго равно (===) указанному значению.
isNotStrictlyEqualTo(expected) Проверяет утверждение о том, что значение не строго равно (!==) указанному.
isGreaterThan(expected) Проверяет утверждение о том, что значение больше (>) указанного, согласно сравнению с учетом порядка.
isGreaterThanOrEqualTo(expected) Проверяет утверждение о том, что значение больше или равно (>=) указанному, согласно сравнению с учетом порядка.
isLessThan(expected) Проверяет утверждение о том, что значение меньше (<) указанного, согласно сравнению с учетом порядка.
isLessThanOrEqualTo(expected) Проверяет утверждение о том, что значение меньше или равно (<=) указанному, согласно сравнению с учетом порядка.
contains(...expected) Проверяет утверждение о том, что значение является массивом или строкой, которые содержат все указанные значения в любом порядке. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
doesNotContain(...expected) Проверяет утверждение о том, что значение является массивом или строкой, которые не содержат указанные значения. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
containsExactly(...expected) Проверяет утверждение о том, что значение является массивом, который содержит только все указанные значения в любом порядке. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
doesNotContainExactly(...expected) Проверяет утверждение о том, что значение является массивом, который содержит другой набор из указанных значений в любом порядке. Сравниваются значения, а не ссылки. Содержимое объектов и массивов сравнивается рекурсивно.
hasLength(expected) Проверяет утверждение о том, что значение является массивом или строкой указанной длины. Утверждение всегда будет неверным, если значение не является массивом или строкой.
isEmpty() Проверяет утверждение о том, что значение является пустым массивом или строкой (длина = 0). Утверждение всегда будет неверным, если значение не является массивом или строкой.
isNotEmpty() Проверяет утверждение о том, что значение является не пустым массивом или строкой (длина > 0). Утверждение всегда будет неверным, если значение не является массивом или строкой.
isArray() Проверяет утверждение о том, что тип значения – массив.
isBoolean() Проверяет утверждение о том, что значение является логическим.
isFunction() Проверяет утверждение о том, что тип значения – функция.
isNumber() Проверяет утверждение о том, что тип значения – число.
isObject() Проверяет утверждение о том, что тип значения – объект.
isString() Проверяет утверждение о том, что тип значения – строка.

Примеры

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

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

Синтаксис

fail(opt_message);

Параметры

Параметр Тип Описание
opt_message string Вариант сообщения об ошибке.

Пример

fail('This test has failed.');

mock

API mock позволяет изменить работу изолированных API. API имитации можно без опасений использовать в коде шаблона, однако вне режима тестирования этот API не функционирует. Черновики сбрасываются перед запуском каждого теста.

Синтаксис

mock(apiName, returnValue);

Параметры

Параметр Тип Описание
apiName string Название имитируемого API (та же строка, которая передается require()).
returnValue любой Значение, возвращаемое для API или функции, которая вызывается вместо этого API. Если returnValue представляет собой функцию, то она вызывается вместо изолированного API; если же returnValue не является функцией, то вместо изолированного API возвращается это значение.

Примеры

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

runCode

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

Синтаксис

runCode(data)

Параметры

Параметр Тип Описание
data object Объект данных, который будет использоваться в тесте.

Возвращаемое значение

Возвращает значение переменной для шаблонов переменных; для всех остальных типов шаблонов возвращает undefined.

Пример

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