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.

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

Нет.

createRegex

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

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

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 string Текст регулярного выражения.
flags string Необязательная строка, которая содержит флаги для создаваемого регулярного выражения. Поддерживаются флаги "g" (глобальное) и "i" (без учета регистра). Все остальные символы игнорируются без уведомления.

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

Нет.

Минимальная версия образа

2.0.0

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

getAnonymizedIpAddress

Возвращает анонимизированную строку с исходным IP-адресом запроса.

Для адресов IPv4 последний октет маскируется как 0 (например, 198.51.100.42 становится 198.51.100.0). Для адресов IPv6 последние 80 бит маскируются нулями, а первые 48 бит сохраняются (например, 2001:db8:cafe:1234:5678:90ab:cdef:1234 становится 2001:db8:cafe::).

Если IP-адрес недействителен или не может быть разрешен, возвращается "::", поэтому результат всегда можно безопасно использовать как ip_override.

Пример

const getAnonymizedIpAddress = require('getAnonymizedIpAddress');

const anonymizedIp = getAnonymizedIpAddress();

Синтаксис

getAnonymizedIpAddress();

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

user_ip

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

getGoogleAuth

Возвращает объект авторизации, который при использовании с sendHttpGet или sendHttpRequest будет включать заголовок авторизации для Google Cloud API. Этот API использует Application Default Credentials для автоматического поиска учетных данных в среде сервера.

Пример

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

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

Синтаксис

getGoogleAuth(scopes);

Параметры

Параметр Тип Описание
scopes Array Массив областей действия API Google OAuth 2.0, для которых запрашивается доступ.

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

Требует разрешения use_google_credentials Разрешение должно быть настроено с одной или несколькими разрешенными областями действия.

getGoogleScript

Получает ресурс из предопределенного набора скриптов Google и возвращает объект Promise, содержащий скрипт и связанные метаданные кеширования.

Объект Promise распознается как объект, содержащий два ключа: 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 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.
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'

Пример

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 любой Заданное значение.

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

Нет.

hmacSha256

Вычисляет закодированную подпись с помощью кода аутентификации сообщений на основе хеша (HMAC) с SHA-256. По умолчанию используется кодировка base64url.

Чтобы использовать этот API, задайте для переменной среды SGTM_CREDENTIALS на сервере путь к файлу ключа JSON в кодировке UTF-8 в следующем формате:

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

Значения представляют собой ключи HMAC в кодировке Base64. Текст JSON не должен начинаться с маркера последовательности байтов.

Пример

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

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

const jwt = header + "." + claim + '.' + signature;

Синтаксис

hmacSha256(data, keyId, options)

Параметры

Параметр Тип Описание
data string Данные для вычисления значения HMAC.
keyId string Идентификатор ключа из файла ключа JSON, который ссылается на ключ, который нужно использовать.
options object Необязательная конфигурация API. (см. раздел Дополнительные параметры ниже).

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

Параметр Тип Описание
outputEncoding string Задает формат кодировки для возвращаемого значения. Поддерживаемые форматы: hex, base64 и base64url. Если не указано другое, по умолчанию используется base64url.

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

use_custom_private_keys

Минимальная версия образа

1.0.0

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 Аналитику с использованием формата Общие данные о событии и возвращает объект Promise, который распознается как объект, содержащий ключ location, или, в случае отклонения, ключ reason. Целевая система (Google Аналитика) выбирается с учетом идентификатора потока данных в данных о событии.

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

Пример

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

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

Синтаксис

sendEventToGoogleAnalytics(event);

Параметры

Параметр Тип Описание
event object Событие в формате Unified Schema.

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

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

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

sendHttpGet

Выполняет запрос HTTP GET по указанному URL и возвращает объект Promise, который распознается и выдает результат после того, как запрос выполняется или истекает срок действия запроса.

Распознанный результат представляет собой объект, содержащий три ключа: statusCode, headers и body. Если при выполнении запроса произошла ошибка (например, недопустимый URL, отсутствие маршрута к хосту, сбой инициализации SSL и т. п.), то объект Promise распознается как {reason: 'failed'}. Если был задан параметр timeout и для запроса было превышено время ожидания, то объект Promise распознается как {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 string Запрошенный URL.
options object Необязательные параметры запроса. (см. раздел Дополнительные параметры ниже).

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

Параметр Тип Описание
headers string Дополнительные заголовки запроса.
timeout number Время ожидания в миллисекундах до прерывания запроса. Значение по умолчанию – 15000.
authorization object Необязательный объект авторизации из вызова getGoogleAuth для включения заголовков авторизации при отправке запросов к googleapis.com.

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

send_http

sendHttpRequest

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

Распознанный результат представляет собой объект, содержащий три ключа: statusCode, headers и body. Если при выполнении запроса произошла ошибка (например, недопустимый URL, отсутствие маршрута к хосту, сбой инициализации SSL и т. п.), то объект Promise распознается как {reason: 'failed'}. Если был задан параметр timeout и для запроса было превышено время ожидания, то объект Promise распознается как {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 string Запрошенный URL.
options object Необязательные параметры запроса. (см. раздел Дополнительные параметры ниже).
body string Необязательное тело запроса.

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

Параметр Тип Описание
headers string Дополнительные заголовки запроса.
method object Метод запроса. Значение по умолчанию – GET.
timeout number Время ожидания в миллисекундах до прерывания запроса. Значение по умолчанию – 15000.
authorization object Необязательный объект авторизации из вызова getGoogleAuth для включения заголовков авторизации при отправке запросов к googleapis.com.

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

send_http

sendPixelFromBrowser

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

Этот 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 setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

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

access_template_storage

testRegex

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

Если регулярное выражение создавалось с флагом "g" (глобальное), оно используется с отслеживанием состояния. Подробная информация приведена в справочной документации по регулярным выражениям.

Пример

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 Object Регулярное выражение, созданное через API createRegex, по которому выполняется проверка.
string string Строка для проверки.

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

Нет.

toBase64

Кодирует строку в формате Base64 или Base64url. По умолчанию используется кодировка Base64.

Синтаксис

toBase64(input, options);

Параметры

Параметр Тип Описание
input string Кодируемая строка.
options object Необязательная конфигурация API. (см. раздел Дополнительные параметры ниже).

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

Параметр Тип Описание Минимальная версия
urlEncoding boolean Если параметр – true, результат кодируется в формате base64url. 1.0.0

Пример

const toBase64 = require('toBase64');

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

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

Нет.

BigQuery

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

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

Если вставка выполнена успешно, объект Promise распознается без аргументов.

Если вставка завершается с ошибкой, объект Promise отклоняется и выдается список объектов, содержащих причину ошибки, и (по возможности) объект строки (row), в котором произошла ошибка. Возможны ситуации, где часть запроса выполняется успешно, а остальные части – нет. В таком случае объект Promise отклоняется и выдается список ошибок для каждой строки с объектом row, позволяющим определить, какие строки были вставлены (см. примеры ошибок). Более подробная информация по сообщениям об ошибках приведена в документации BigQuery.

Синтаксис

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

Параметры

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

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

Параметр Тип Описание
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)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

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

access_bigquery

Firestore

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

Этот API поддерживает только Firestore в стандартном режиме и не поддерживает Firestore в режиме Datastore. Кроме того, API поддерживает только базу данных по умолчанию.

Firestore.read

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

Синтаксис

Firestore.read(path[, options]);

Параметры

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

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

Параметр Тип Описание
projectId string Это необязательный параметр. Идентификатор проекта Google Cloud Platform. Если он не указан, то projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT при условии, что для идентификатора проекта задано следующее значение разрешения access_firestore: * или GOOGLE_CLOUD_PROJECT. Если серверный контейнер работает на платформе Google Cloud, для параметра GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта в этом сервисе.
disableCache boolean Это необязательный параметр. Определяет, будет ли отключен кеш. По умолчанию кеширование включено и результаты кешируются на время действия запроса.
transaction string Это необязательный параметр. Значение, извлеченное из 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 возвращает объект Promise, который распознается как идентификатор добавленного или извлеченного документа. Если используется параметр транзакции, API также возвращает объект Promise, но не содержащий идентификатора, поскольку записи объединены в пакет.

Синтаксис

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

Параметры

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

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

Параметр Тип Описание
projectId string Это необязательный параметр. Идентификатор проекта Google Cloud Platform. Если он не указан, то projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT при условии, что для идентификатора проекта задано следующее значение разрешения access_firestore: * или GOOGLE_CLOUD_PROJECT. Если серверный контейнер работает на платформе Google Cloud, для параметра GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта в этом сервисе.
merge boolean Это необязательный параметр. Если указано значение true, введенные ключи будут объединены в документе. В противном случае метод перезапишет документ целиком. Значение по умолчанию – false.
transaction string Это необязательный параметр. Значение, извлеченное из 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 запрашивает указанную коллекцию и возвращает объект Promise, который преобразуется в массив документов Firestore, соответствующих условиям запроса. Объект документов Firestore является таким же, как и в описании функции Firestore.read выше. Если нет ни одного документа, соответствующего условиям запроса, то возвращаемый объект Promise преобразуется в пустой массив.

Синтаксис

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

Параметры

Параметр Тип Описание
collection string Путь к коллекции. Не может начинаться или заканчиваться символом "/".
queryConditions Array Массив, содержащий условия запроса. Каждый запрос представляет собой массив с тремя значениями: key, operator и expectedValue. Пример: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

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

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

Параметр Тип Описание
projectId string Это необязательный параметр. Идентификатор проекта Google Cloud Platform. Если он не указан, то projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT при условии, что для идентификатора проекта задано следующее значение разрешения access_firestore: * или GOOGLE_CLOUD_PROJECT. Если серверный контейнер работает на платформе Google Cloud, для параметра GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта в этом сервисе.
disableCache boolean Это необязательный параметр. Определяет, будет ли отключен кеш. По умолчанию кеширование включено и результаты кешируются на время действия запроса.
limit number Это необязательный параметр. Изменяет максимальное количество результатов, возвращаемых запросом. Значение по умолчанию – 5.
transaction string Это необязательный параметр. Значение, извлеченное из 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

Функция Firestore.runTransaction позволяет атомарно читать и записывать данные, полученные из Firestore. Если во время транзакции произойдет конфликт (например, связанный с параллельной записью), будет выполнено до двух повторных попыток. Если после трех попыток операция выполнена не будет, API отклонит ее с ошибкой. Если транзакция выполнена успешно, этот API возвращает объект Promise, который распознается как массив идентификаторов документов для каждой операции записи. В противном случае транзакция будет отклонена с ошибкой.

Синтаксис

Firestore.runTransaction(callback[, options]);

Параметры

Параметр Тип Описание
callback function Обратный вызов, который инициируется строкой идентификатора транзакции. Идентификатор транзакции может быть передан в вызовы API (чтение/запись/запрос). Эта функция обратного вызова должна возвращать объект Promise. Вызов может быть повторен трижды; после этого регистрируется ошибка.
options object Необязательные параметры запроса. Поддерживается только параметр projectId. Неизвестные ключи параметров игнорируются (см. раздел Дополнительные параметры ниже).

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

Параметр Тип Описание
projectId string Это необязательный параметр. Идентификатор проекта Google Cloud Platform. Если он не указан, то projectId извлекается из переменной среды GOOGLE_CLOUD_PROJECT при условии, что для идентификатора проекта задано следующее значение разрешения access_firestore: * или GOOGLE_CLOUD_PROJECT. Если серверный контейнер работает на платформе Google Cloud, для параметра GOOGLE_CLOUD_PROJECT уже будет задан идентификатор проекта в этом сервисе.

Пример

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

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

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

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

Этот ключ может содержать коды ошибок Firestore REST API и другие значения.

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

access_firestore

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.

Object

Возвращает объект с методами Object.

Метод keys() реализует поведение стандартной библиотеки Object.keys(). Он возвращает массив имен перечислимых свойств данного объекта в том же порядке, что и цикл for...in.... Если введенное значение не является объектом, оно будет приведено к объекту.

Метод values() реализует поведение стандартной библиотеки Object.values(). Он возвращает массив значений перечислимых свойств данного объекта в том же порядке, что и цикл for...in.... Если введенное значение не является объектом, оно будет приведено к объекту.

Метод entries() реализует поведение стандартной библиотеки Object.entries(). Он возвращает массив пар [key, value] для перечислимых свойств данного объекта в том же порядке, что и цикл for...in.... Если введенное значение не является объектом, оно будет приведено к объекту.

Метод freeze() реализует поведение стандартной библиотеки Object.freeze(). Замороженный объект нельзя будет редактировать: добавлять новые свойства, удалять существующие или изменять значения для них. freeze() возвращает тот же объект, который был передан. Примитивный или нулевой аргумент будет воспринят как замороженный объект и возвращен.

Метод delete() реализует в стандартной библиотеке функцию оператора delete. Этот метод позволяет удалить заданный ключ из объекта, если только объект не является замороженным. Как и оператор delete в стандартной библиотеке, он возвращает значение true, если первое введенное значение (objectInput) – это объект, который не является замороженным, если даже второе введенное значение (keyToDelete) указывает на несуществующий ключ. В остальных случаях возвращается значение false. Однако у этого метода есть отличия:

  • Параметр keyToDelete не может быть разделенной точками строкой, указывающей на вложенный ключ.
  • Параметр delete() нельзя использовать, чтобы удалить элемент из массива.
  • Параметр delete() нельзя использовать, чтобы удалить ресурс из глобальной области действия.

Синтаксис

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

Параметры

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

Параметр Тип Описание
objectInput любой Объект, ключ которого нужно удалить.
keyToDelete string Ключ верхнего уровня, который нужно удалить.

Пример

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

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

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

  • .then() обрабатывает оба типа случаев (успех и отклонение). В качестве параметров принимает два обратных вызова: один для успешных распознаваний, второй для отклонений.
  • .catch() обрабатывает только отклонения. В качестве параметра принимает один обратный вызов.
  • .finally() позволяет выполнять код независимо от того, успешно ли распознан объект Promise. В качестве параметра принимает один обратный вызов без аргумента.

Переменная, которая возвращает объект Promise, равна распознанному значению этого объекта, а если объект Promise отклоняется, то переменная приобретает значение false.

Пример

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

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

  • распознается, если все входные данные распознаются;
  • отклоняется, если хотя бы один из входных аргументов отклоняется.

Синтаксис

Promise.all(inputs);

Параметры

Параметр Тип Описание
inputs Array Массив значений или объектов Promise. Если входной аргумент не является объектом Promise, этот аргумент передается далее, как если бы он был распознанным значением объекта Promise. Если входной аргумент не является массивом, выдается ошибка.

Пример

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

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

Нет.

Promise.create

Создает объект Promise, функционально эквивалентный объекту Promise из JavaScript.

Синтаксис

Promise.create(resolver);

Параметры

Параметр Тип Описание
resolver function Функция, вызываемая с использованием двух функций – resolve и reject. Возвращаемый объект Promise распознается или отклоняется, когда вызывается соответствующий параметр. Если resolver не является функцией, выдается ошибка.

Пример

const Promise = require('Promise');

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

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

Нет.

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

mockObject

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

Синтаксис

mockObject(apiName, objectMock);

Параметры

Параметр Тип Описание
apiName string Название имитируемого API (та же строка, которая передается в метод require()).
objectMock object Значение, возвращаемое для API или функции, которая вызывается вместо этого API. Это должен быть объект.

Примеры

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

runCode

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

Синтаксис

runCode(data)

Параметры

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

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

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

Пример

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