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

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() или другими методами.

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

Нет.

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

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

Пример

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

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 с помощью обратного вызова.

Подпись и поведение этого 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(input, onSuccess)

Параметры

Параметр Тип Описание
input string Строка, которую необходимо хешировать.
onSuccess function Вызывается вместе с дайджестом, закодированным в формате Base64.

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

Нет.

sha256Sync

Вычисляет для входных данных дайджест SHA-256, закодированный в формате Base64.

Пример

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

const digest = sha256Sync('inputString');
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));

Синтаксис

sha256Sync(input)

Параметры

Параметр Тип Описание
input string Строка, которую необходимо хешировать.

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

Нет.

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

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

Нет.

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.