Интерфейсы (API)

Основной программный интерфейс (core APIs) шаблонов

API работают с изолированным JavaScript для создания пользовательских шаблонов в Yandex Tag Manager. Каждый API добавляется через require(), например:

const myAPI = require('myAPI');

callInWindow

Позволяет вызывать функции по пути от объекта window способом, контролируемым политикой.

Вызывает функцию по заданному пути в window с заданными аргументами и возвращает значение. Если возвращаемый тип не может быть напрямую сопоставлен с типом, поддерживаемым в изолированном JavaScript, будет возвращен undefined. Типы, которые поддерживаются в изолированном JavaScript:

• null
• undefined
• boolean
• number
• string
• Array
• Object

Если указанный путь не существует или не ссылается на функцию, будет возвращено значение undefined.

Синтаксис

callInWindow(pathToFunction, argument [, argument2,... argumentN])

Параметры

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

Должно быть выдано разрешение access_globals с ключом execute.

callLater

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

Синтаксис

callLater(function)

Параметры

checkInWindow

Позволяет проверить содержит ли свойство глобальный объект window. Функция возвращает значение true, если объект window содержит указанное свойство. Если был передан второй параметр, то функция также проверяет, имеет ли свойство указанный тип. В противном случае функция возвращает значение false.

Можно использовать точечную нотацию для доступа к вложенным объектам.

Синтаксис

checkInWindow(methodName, methodTypeName)

Параметры

Пример

const checkInWindow = require('checkInWindow');
const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');

// Можно проверять не только наличие свойства в window, но и наличие
// свойства во вложенных объектах с помощью точечной нотации.

const hasPermission = queryPermission('access_globals', 'read', 'myObject.someSendMethod');
if (hasPermission) {
  const hasSendMethod = checkInWindow('myObject.someSendMethod', 'function');
  if (hasSendMethod) {
    logToConsole('Метод someSendMethod обнаружен в window.myObject');
  } else {
    logToConsole('Метод someSendMethod не обнаружен в window.myObject');
  }
} else {
  logToConsole('Отсутствует разрешение на чтение window.myObject.someSendMethod');
}

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

Должно быть выдано разрешение access_globals с ключом read.

copyFromDataLayer

Возвращает значение, присвоенное в данный момент указанному ключу в dataLayer. Значение будет возвращено, если это примитивный тип или объектный литерал. Иначе будет возвращено undefined. Речь идет о внутреннем dataLayer YTM. copyFromDataLayer может получить доступ только к текущему событию, которое генерируется триггером.

Можно использовать совместно с триггером Специальное событие со значением eventName, который вызывается при dataLayer.push({event = 'eventName'}). Добавив в этот объект свои ключи, можно получить доступ к ним с помощью copyFromDataLayer.

Синтаксис

copyFromDataLayer(key)

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

read_data_layer

copyFromWindow

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

• null
• undefined
• boolean
• number
• string
• Array
• Object

Возвращает выбранное (и принудительно приведенное) значение.

Синтаксис

copyFromWindow(key)

Параметры

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

access_globals

createArgumentsQueue

Создает функцию window, используя аргумент fnKey (аналогично createQueue). После создания функции API создает массив в window (если он еще не существует), используя аргумент arrayKey .

Когда вызывается функция, созданная в fnKey, она помещает объект своих аргументов в массив, созданный в arrayKey. Возвращаемое значение API — это функция, созданная в fnKey.

Для функции требуется опции чтения и записи для fnKey и arrayKey в разрешении access_globals.

Синтаксис

createArgumentsQueue(fnKey, arrayKey)

Параметры

Пример

const someQueue = createArgumentsQueue('someQueue', 'dataLayer');
someQueue('set', {'currency': 'USD'});

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

access_globals

createQueue

Создает массив в window (если он еще не существует) и возвращает функцию, которая будет помещать значения в этот массив.

Для функции требуется настройка чтения и записи для arrayKey в разрешении access_globals.

Синтаксис

createQueue(arrayKey)

Параметры

Пример

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

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

access_globals

decodeUri

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

Синтаксис

decodeUri(encoded_uri)

Параметры

Пример

const decode = require('decodeUri');

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

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

Отсутствуют.

decodeUriComponent

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

Синтаксис

decodeUriComponent(encoded_uri_component)

Параметры

Пример

const decode = require('decodeUriComponent');

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

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

Отсутствуют.

encodeUri

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

Синтаксис

encodeUri(uri)

Параметры

Пример

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

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

Отсутствуют.

encodeUriComponent

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

Синтаксис

encodeUriComponent(str)

Параметры

Пример

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

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

Отсутствуют.

getCookieValues

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

Синтаксис

getCookieValues(name[, decode])

Параметры

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

get_cookies

getTimestamp

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

Синтаксис

getTimestamp();

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

Отсутствуют.

getType

Возвращает строку, которая описывает тип переданного значения. В отличие от typeof, getType проводит различие между array и object.

Синтаксис

getType(data.someField)

Таблица соответствия входного значения и результата:

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

Отсутствуют.

getUrl

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

Синтаксис

getUrl(component, variableName)

Параметры

Пример

const getUrl = require('getUrl');
const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');

const hasPermission = queryPermission('get_url', 'queryVar', 'var1');
if (hasPermission) {
  const var1 = getUrl('queryVar', 'var1');
  if (var1) {
    logToConsole('Параметр var1 из query равен ' + var1);
  } else {
    logToConsole('Параметр var1 не обнаружен в query');
  }
} else {
  logToConsole('Отсутствует разрешение на доступ к параметру var1 из query');
}

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

get_url.

injectHiddenIframe

Добавляет невидимый iframe на страницу.

Синтаксис

injectHiddenIframe(url, onSuccess)

Параметры

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

inject_hidden_iframe.

loadScript

Добавляет на страницу тег script для асинхронной загрузки этого URL-адреса.

Синтаксис

loadScript(url, onSuccess, onFailure)

Параметры

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

load_script

JSON

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

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

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

Синтаксис

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

Параметры

JSON.parse

JSON.stringify

Пример

const JSON = require('JSON');

// Входная строка JSON преобразуется в объект.
const object = JSON.parse('{"foo":"bar"}');

// Входной объект преобразуется в строку JSON.
const str = JSON.stringify({foo: 'bar'});

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

Отсутствуют.

localStorage

Возвращает объект с методами для доступа к локальному хранилищу.

Синтаксис

const localStorage = require('localStorage');

// Требуется доступ на чтение для ключа. Возвращает null, если ключ не существует.
localStorage.getItem(key);

// Требуется доступ на запись для ключа. Возвращает true в случае успеха.
localStorage.setItem(key, value);

// Требуется доступ на запись для ключа.
localStorage.removeItem(key);

Пример

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

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

access_local_storage

logToConsole

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

Синтаксис

logToConsole(obj1 [, obj2,... objN])

Параметры

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

Logging.

Math

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

Синтаксис

const Math = require('Math');

// Извлекает абсолютное значение.
const absolute = Math.abs(-3);

// Округляет входные данные в меньшую сторону до ближайшего целого числа.
const roundedDown = Math.floor(3.6);

// Округляет входные данные в большую сторону до ближайшего целого числа.
const roundedUp = Math.ceil(2.2);

// Округляет входные данные до ближайшего целого числа.
const rounded = Math.round(3.1);

// Возвращает самый большой аргумент.
const biggest = Math.max(1, 3);

// Возвращает наименьший аргумент.
const smallest = Math.min(3, 5);

// Возвращает первый аргумент, возведенный в степень второго аргумента.
const powerful = Math.pow(3, 1);

// Возвращает квадратный корень из аргумента.
const unsquared = Math.sqrt(9);

Параметры

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

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

Отсутствуют.

Object

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

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

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

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

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

Метод delete() обеспечивает поведение стандартной библиотеки delete operator. Он удаляет указанный ключ из объекта, если только объект не заморожен. Подобно оператору удаления стандартной библиотеки, он возвращает 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

Object.values

Object.entries

Object.freeze

Object.delete

Пример

const Object = require('Object');

// Ключи объекта перечисляются в массиве.
const keys = Object.keys({foo: 'bar'});

// Значения объекта перечисляются в массиве.
const values = Object.values({foo: 'bar'});

// Пары ключ/значение объекта перечисляются в массиве.
const entries = Object.entries({foo: 'bar'});

// Входной объект заморожен.
const frozen = Object.freeze({foo: 'bar'});

// Ключ удаляется из объекта ввода.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// В качестве ключа для удаления можно указать только ключ верхнего уровня.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // Это не имеет никакого эффекта.
Object.delete(obj2.nested, 'key'); // При этом будет удален вложенный ключ.

queryPermission

Запрашивает разрешенные и ограниченные разрешения. Возвращает логическое значение: true, если разрешение предоставлено, false в противном случае.

Синтаксис

queryPermission(permission, functionArgs*)

Параметры

Аргументы функции

if (queryPermission('get_url','port')) {
  // read the port
}

if (queryPermission('get_url','query')) {
  // read the whole query
}

if (queryPermission('get_url','queryVar', 'param1')) {
  // read the specific query param
}

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

Отсутствуют.

readTitle

Возвращает значение document.title.

Синтаксис

readTitle()

Параметры

Отсутствуют.

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

read_title.

require

Импортирует встроенную функцию по имени. Возвращает функцию или объект, которые могут быть вызваны из вашей программы. Возвращает undefined, если браузер не поддерживает встроенную функцию.

Синтаксис

require(name)

Параметры

Пример

const getUrl = require('getUrl');
const url = getUrl();

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

Отсутствуют.

sendPixel

Выполняет запрос GET к указанной конечной точке URL.

Синтаксис

sendPixel(url, onSuccess, onFailure)

Параметры

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

send_pixel.

setCookie

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

Синтаксис

setCookie(name, value[, options, encode])

Параметры

Значения параметра options

• Domain: устанавливается с помощью options['domain']. Установите значение 'auto', чтобы записать файл cookie, используя максимально широкий возможный домен., в зависимости от местоположения документа. Если это не удается, система последовательно пробует более узкие поддомены. При неудаче всех попыток, будет предпринята попытка записи файла cookie без домена. Если значение не задано, файл cookie записывается без указания домена.

• Path: устанавливается с помощью options['path']. Когда файл cookie без указанного пути записывается в document.cookie, пользовательский агент по умолчанию использует путь файла cookie к пути текущего расположения документа.

• Max-Age: устанавливается с помощью options['max-age'], если имеется.

• Expires: устанавливается с помощью options['expires'], если имеется. Если имеется, это должна быть строка даты в формате UTC. Date.toUTCString() можно использовать для форматирования даты для этого параметра.

• Secure: устанавливается с помощью options['secure'], если имеется.

• SameSite: устанавливается с помощью options['samesite'], если имеется.

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

set_cookies.

setInWindow

Устанавливает значение в window по заданному ключу. По умолчанию этот метод не устанавливает значение в window, если оно уже присутствует. Установите значение overrideExisting равным true, чтобы установить значение в window независимо от наличия существующего значения. Возвращает логическое значение: true если значение было установлено успешно, и false в противном случае.

Синтаксис

setInWindow(key, value, overrideExisting)

Параметры

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

access_globals.

Написать в чат