В этой статье описаны 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.
});
Связанные разрешения
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();
Связанные разрешения
getClientName
Возвращает строку с названием текущего клиента.
Синтаксис
getClientName();
Связанные разрешения
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();
Связанные разрешения
getCookieValues
Возвращает массив значений всех файлов cookie с указанным названием.
Пример
const getCookieValues = require('getCookieValues');
const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
// ...
}
Синтаксис
getCookieValues(name[, noDecode])
Параметры
Параметр | Тип | Описание |
---|---|---|
name |
string | Имя файла cookie. |
noDecode |
boolean | При значении true значения файла cookie не декодируются. Значение по умолчанию – false . |
Связанные разрешения
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)
Связанные разрешения
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();
Связанные разрешения
getRequestHeader
Возвращает строку с заголовком запроса (а если его нет, то значение undefined
). Если заголовок повторяется, возвращаемые значения указываются через запятую (', '
).
Пример
const getRequestHeader = require('getRequestHeader');
const host = getRequestHeader('host');
Синтаксис
getRequestHeader(headerName);
Параметры
Параметр | Тип | Описание |
---|---|---|
headerName |
string | Название заголовка. Регистр не учитывается. |
Связанные разрешения
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();
Связанные разрешения
getRequestQueryParameter
Возвращает строку с декодированной строкой запроса. Если этот параметр отсутствует, выводится значение undefined
. Если параметр повторяется в строке запроса, возвращается первое указанное в ней значение.
Пример
const getRequestQueryParameter = require('getRequestQueryParameter');
const query = getRequestQueryParameter('query');
if (query) {
// Process query here.
}
Синтаксис
getRequestQueryParameter(name);
Параметры
Параметр | Тип | Описание |
---|---|---|
name |
string | Название параметра запроса. |
Связанные разрешения
getRequestQueryParameters
Возвращает параметры входящего HTTP-запроса в виде объекта, который сопоставляет названия параметров с соответствующими значениями. Названия и значения параметров предоставляются в декодированном виде.
Пример
const getRequestQueryParameters = require('getRequestQueryParameters');
const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
// Handle the search query here.
const maxResults = queryParameters['max_results'];
}
Синтаксис
getRequestQueryParameters();
Связанные разрешения
getRequestQueryString
Возвращает запрос без вопросительного знака в начале или пустую строку, если URL запроса не содержит строку.
Пример
const getRequestQueryString = require('getRequestQueryString');
const queryString = getRequestQueryString();
if (queryString !== '') {
// Handle the query string.
}
Синтаксис
getRequestQueryString();
Связанные разрешения
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 преобразует заданные аргументы в строки и вносит в журнал консоли.
Связанные разрешения
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
.
Связанные разрешения
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 | Обратный вызов, выполняемый немедленно, ещё до активации тегов. |
Связанные разрешения
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: время ожидания в миллисекундах до прерывания запроса.
Связанные разрешения
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: время ожидания в миллисекундах до прерывания запроса.
Связанные разрешения
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
.
- eTLD+1 заголовка
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'
.
Связанные разрешения
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);
});
Связанные разрешения
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
передается сообщение этого типа (обычно тегом), то синхронно выполняется обратный вызов с двумя параметрами:
messageType:string
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
.