Пользовательские API шаблонов

Основные API

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

const myAPI = require('myAPI');

addConsentListener

Регистрирует функцию прослушивателя, которая будет выполняться при изменении состояния указанного типа согласия.

Данный прослушиватель будет вызываться каждый раз, когда состояние указанного типа согласия меняется с «отказано» на «предоставлено» или с «предоставлено» на «отказано». Тип согласия без состояния считается предоставленным, поэтому прослушиватель не будет вызываться, если неустановленный тип согласия будет обновлен до предоставленного. Функции прослушивателя будут отвечать за то, чтобы их код запускался необходимое количество раз.

Пример:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Синтаксис

addConsentListener(consentType, listener)

Параметры

Параметр Тип Описание
consentType нить Тип согласия для отслеживания изменений состояния.
listener функция Функция, запускаемая при изменении состояния указанного типа согласия.

При вызове прослушивателя ему будет передан тип согласия, который изменяется, и новое значение этого типа согласия:

Параметр Тип Описание
consentType нить Тип согласия, который изменяется.
granted логическое значение Логическое значение, имеющее значение true, если указанный тип согласия меняется на предоставленный.

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

Разрешение access_consent с доступом на чтение для типа согласия.

addEventCallback

API addEventCallback позволяет зарегистрировать функцию обратного вызова, которая будет вызываться в конце события. Обратный вызов будет вызван, когда все теги для события будут выполнены или если будет достигнут тайм-аут события на странице. В обратный вызов передаются два значения: идентификатор контейнера, вызывающего функцию, и объекта, содержащего информацию о событии.

Синтаксис

addEventCallback(callback)

Параметры

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

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

Имя ключа Тип Описание
tags Множество Массив объектов данных тега. Каждый тег, сработавший во время события, будет иметь запись в этом массиве. Объект данных тега содержит идентификатор тега ( id ), его статус выполнения ( status ) и время выполнения ( executionTime ). Данные тега также будут включать дополнительные метаданные тега, настроенные для тега.

Пример

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

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

read_event_metadata

aliasInWindow

API aliasInWindow позволяет создать псевдоним (например, window.foo = window.bar ), который помогает поддерживать определенные теги, требующие псевдонимов. Присваивает значение объекта window , найденного в fromPath , ключу в объекте window в toPath . Возвращает true в случае успеха и false в противном случае.

Синтаксис

aliasInWindow(toPath, fromPath)

Параметры

Параметр Тип Описание
toPath нить Путь к объекту window разделенный точками, куда следует скопировать значение. Все компоненты на пути до последнего компонента уже должны существовать в объекте window .
fromPath нить window к скопируемому значению, разделенный точкой. Если значение не существует, операция завершится неудачно.

Пример

aliasInWindow('foo.bar', 'baz.qux')

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

access_globals требуется как для toPath , так и fromPath ; toPath требует доступа для записи, fromPath требует доступа для чтения.

callInWindow

Позволяет вызывать функции из пути за пределами объекта window , способом, контролируемым политикой. Вызывает функцию по заданному пути в window с заданными аргументами и возвращает значение. Если тип возвращаемого значения невозможно напрямую сопоставить с типом, поддерживаемым в изолированном JavaScript, будет возвращено undefined . В изолированном JavaScript поддерживаются восемь типов: null , undefined , boolean , number , string , Array , Object и function . Если данный путь не существует или не ссылается на функцию, будет возвращено undefined .

Синтаксис

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

Параметры

Параметр Тип Описание
pathToFunction нить Путь к вызываемой функции в window , разделенный точками.
args * Аргументы, которые будут переданы в функцию.

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

access_globals с включенным разрешением execute .

callLater

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

Синтаксис

callLater(function)

Параметры

Параметр Тип Описание
function функция Функция для вызова.

copyFromDataLayer

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

Синтаксис

copyFromDataLayer(key[, dataLayerVersion])

Параметры

Параметр Тип Описание
key нить Ключ в формате «abc».
dataLayerVersion число Необязательная версия уровня данных . Значение по умолчанию — 2. Настоятельно не рекомендуется использовать значение 1.

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

read_data_layer

copyFromWindow

Копирует переменную из объекта window . Если значение в window невозможно напрямую сопоставить с типом, поддерживаемым в изолированном JavaScript, будет возвращено undefined . В изолированном JavaScript поддерживаются восемь типов: null , undefined , boolean , number , string , Array , Object и function . Возвращает полученное (и принудительное) значение.

Синтаксис

copyFromWindow(key)

Параметры

Параметр Тип Описание
key нить Ключ в window , значение которого необходимо скопировать.

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

access_globals

createArgumentsQueue

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

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

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

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

Пример:

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

Синтаксис

createArgumentsQueue(fnKey, arrayKey)

Параметры

Параметр Тип Описание
fnKey нить Путь в window , где установлена ​​функция, если он еще не существует. Этот аргумент поддерживает стандартную запись через точку. Если путь к ключу не существует, выдается исключение. То есть, если fnKey имеет значение 'one.two' , будет выдано исключение.
arrayKey нить Путь в window , где установлен массив, если он еще не существует. Этот аргумент поддерживает стандартную запись через точку. Если путь к ключу не существует, выдается исключение. То есть, если arrayKey имеет значение 'one.two' и нет глобального объекта с именем 'one' , будет выдано исключение.

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

access_globals

createQueue

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

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

Пример:

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

Синтаксис

createQueue(arrayKey)

Параметры

Параметр Тип Описание
arrayKey нить Ключ в window , где установлен массив, если он еще не существует. Этот аргумент поддерживает стандартную запись через точку. Если путь к ключу не существует, выдается исключение. Например, если arrayKey имеет значение 'one.two' и нет глобального объекта с именем 'one' , будет выдано исключение.

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

access_globals

decodeUri

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

Пример:

const decode = require('decodeUri');

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

Синтаксис

decodeUri(encoded_uri)

Параметры

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

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

Никто.

decodeUriComponent

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

Пример:

const decode = require('decodeUriComponent');

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

Синтаксис

decodeUriComponent(encoded_uri_component)

Параметры

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

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

Никто.

encodeUri

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

Пример:

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

Синтаксис

encodeUri(uri)

Параметры

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

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

Никто.

encodeUriComponent

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

Пример:

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

Синтаксис

encodeUriComponent(str)

Параметры

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

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

Никто.

fromBase64

API fromBase64 позволяет декодировать строки из их представления в base64. Возвращает undefined , если введен неверный ввод.

Синтаксис

fromBase64(base64EncodedString)

Параметры

Параметр Тип Описание
base64EncodedString нить Строка в кодировке Base64.

Пример

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

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

Никто

generateRandom

Возвращает случайное число (целое) в заданном диапазоне.

Синтаксис

generateRandom(min, max)

Параметры

Параметр Тип Описание
min число Минимальное потенциальное значение возвращаемого целого числа.
max число Максимальное потенциальное значение возвращаемого целого числа.

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

Никто.

getContainerVersion

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

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

Пример

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Синтаксис

getContainerVersion();

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

read_container_data

getCookieValues

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

Синтаксис

getCookieValues(name[, decode])

Параметры

Параметр Тип Описание
name нить Имя файла cookie.
decode логическое значение Определяет, должны ли значения cookie декодироваться с помощью decodeURIComponent() JavaScript. По умолчанию true .

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

get_cookies

getQueryParameters

Возвращает первый или все параметры для queryKey текущего URL-адреса. Возвращает первое значение из queryKey или массив значений из queryKey .

Синтаксис

getQueryParameters(queryKey[, retrieveAll])

Параметры

Параметр Тип Описание
queryKey нить Ключ для чтения параметров запроса.
retrieveAll логическое значение Нужно ли получать все значения.

Например, если текущий URL-адрес — https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo , то:

  • getQueryParameters('var') == 'foo'
  • getQueryParameters('var', false) == 'foo'
  • getQueryParameters('var', null) == 'foo'
  • getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

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

get_url должен разрешить компонент query и должен указать queryKey в разрешенных ключах запроса (или разрешить любой ключ запроса).

getReferrerQueryParameters

API getReferrerQueryParameters действует так же, как и getQueryParameters , за исключением того, что он воздействует на реферер, а не на текущий URL-адрес. Возвращает первый или все параметры для queryKey данного реферера. Возвращает первое значение из queryKey или массив значений из queryKey .

Синтаксис

getReferrerQueryParameters(queryKey[, retrieveAll])

Параметры

Параметр Тип Описание
queryKey нить Ключ для чтения параметров запроса.
retrieveAll логическое значение Нужно ли получать все значения.

Например, если URL-адрес реферера — https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo , то:

  • getReferrerQueryParameters('var') == 'foo'
  • getReferrerQueryParameters('var', false) == 'foo'
  • getReferrerQueryParameters('var', null) == 'foo'
  • getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

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

get_referrer должен разрешить компонент query и должен указать queryKey в разрешенных ключах запроса (или разрешить любой ключ запроса).

getReferrerUrl

Учитывая тип компонента, API считывает объект документа для реферера и возвращает строку, которая представляет часть реферера. Если компонент не указан, возвращается полный URL-адрес реферера.

Синтаксис

getReferrerUrl([component])

Параметры

Параметр Тип Описание
component нить Компонент, возвращаемый из URL-адреса. Может быть одним из следующих: protocol , host , port , path , query , extension . Если component undefined , null или не соответствует ни одному из этих компонентов, будет возвращен весь URL-адрес.

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

get_referrer должен разрешить компонент query и должен указать queryKey в разрешенных ключах запроса (или разрешить любой ключ запроса).

getTimestamp

Устарело. Предпочитайте getTimestampMillis .

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

Синтаксис

getTimestamp();

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

Никто.

getTimestampMillis

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

Синтаксис

getTimestampMillis();

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

Никто.

getType

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

Синтаксис

getType(data.someField)

Примечания

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

Входное значение Результат
undefined 'неопределенный'
null 'нулевой'
true 'логическое'
12 'число'
'string' 'нить'
{ a: 3 } 'объект'
[ 1, 3 ] 'множество'
(x) => x + 1 'функция'

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

Никто.

getUrl

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

Синтаксис

getUrl(component)

Параметры

Параметр Тип Описание
component нить Компонент, возвращаемый из URL-адреса. Должно быть одно из: protocol , host , port , path , query , extension , fragment . Если компонент undefined , null или не соответствует ни одному из этих компонентов, будет возвращено все значение href .

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

get_url

gtagSet

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

Например, если оно вызывается тегом, запущенным при инициализации согласия , обновление будет применено до обработки события инициализации. Примерами могут быть: ads_data_redaction установлено значение true или false или url_passthrough установлено значение true или false .

Примеры:

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

Синтаксис

gtagSet(object)

Параметры

Параметр Тип Описание
Object объект Объект, который обновляет глобальное состояние содержащихся в нем свойств.

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

write_data_layer проверяет разрешение на запись в dataLayer для всех указанных ключей. Если входные данные в gtagSet представляют собой простой объект, API проверит разрешение на запись для всех плоских ключей внутри этого объекта, например, для gtagSet({foo: {bar: 'baz'}}) API проверит разрешение на запись для foo.bar .

Если входные данные для gtagSet являются ключом и некоторым непростым значением объекта, API проверит разрешение на запись для этого ключа, например, для gtagSet('abc', true) API проверит разрешение на запись для 'abc' .

Обратите внимание: если во входном объекте есть цикл, будут проверены только клавиши до достижения того же объекта.

injectHiddenIframe

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

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

Синтаксис

injectHiddenIframe(url, onSuccess)

Параметры

Параметр Тип Описание
url нить URL-адрес, который будет использоваться в качестве значения атрибута src iframe.
onSuccess функция Вызывается при успешной загрузке кадра.

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

inject_hidden_iframe

injectScript

Добавляет тег скрипта на страницу для асинхронной загрузки данного URL-адреса. Обратные вызовы задаются как экземпляры функций и заключены в функции JavaScript, которые вызывают их.

Синтаксис

injectScript(url, onSuccess, onFailure[, cacheToken])

Параметры

Параметр Тип Описание
url нить Адрес скрипта, который будет внедрен.
onSuccess функция Вызывается при успешной загрузке сценария.
onFailure функция Вызывается, когда скрипт не загружается.
cacheToken нить Необязательная строка, указывающая, что данный URL-адрес должен быть кэширован. Если указано это значение, будет создан только один элемент сценария для запроса JavaScript. Любые дополнительные попытки загрузки приведут к тому, что данные методы onSuccess и onFailure будут поставлены в очередь до тех пор, пока скрипт не загрузится.

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

inject_script

isConsentGranted

Возвращает true, если указанный тип согласия предоставлен.

Согласие на определенный тип согласия считается предоставленным, если для типа согласия установлено значение «предоставлено» или не задано вообще. Если для типа согласия установлено любое другое значение, оно будет считаться не предоставленным.

Пользовательский интерфейс Диспетчера тегов для настроек тегов предложит возможность всегда активировать. Если тег с включенной функцией Always Fire использует этот API, согласие считается предоставленным и возвращается true , независимо от фактического состояния согласия.

Пример:

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

Синтаксис

isConsentGranted(consentType)

Параметры

Параметр Тип Описание
consentType нить Тип согласия, состояние которого необходимо проверить.

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

Разрешение access_consent с доступом на чтение для типа согласия.

JSON

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

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

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

Синтаксис

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

Параметры

JSON.parse

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

JSON.stringify

Параметр Тип Описание
ценить любой Значение для преобразования.

Пример

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

localStorage

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

Синтаксис

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

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

access_local_storage

Пример

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

logToConsole

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

Синтаксис

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

Параметры

Параметр Тип Описание
obj1 [, obj2,... objN] любой Аргументы

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

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 Список Объект таблицы для преобразования. Это список карт, где каждая Map представляет строку в таблице. Каждое имя свойства в объекте строки является именем столбца, а значение свойства — значением столбца в строке.
keyColumnName нить Имя столбца, значения которого станут ключами в преобразованном Map .
valueColumnName нить Имя столбца, значения которого станут значениями в преобразованной Map .

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

Никто.

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

Параметры

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

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

Никто.

Object

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

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

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

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

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

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

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

Синтаксис

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

Параметры

Объект.ключи

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

Объект.значения

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

Объект.записи

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

Объект.заморозка

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

Объект.удалить

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

Пример

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

parseUrl

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

Этот API вернет undefined для любого неправильного URL-адреса. Для правильно отформатированных 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 нить Полный URL-адрес, который будет проанализирован.

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

Никто.

queryPermission

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

Синтаксис

queryPermission(permission, functionArgs*)

Параметры

Параметр Тип Описание
permission нить Название разрешения.
functionArgs любой Аргументы функции различаются в зависимости от запрашиваемого разрешения. См. Аргументы функции ниже.

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

sendPixel , injectScript , injectHiddenIframe : второй параметр должен быть строкой URL.

writeGlobals , readGlobals : второй параметр должен быть записываемым или читаемым ключом.

readUrl : дополнительные аргументы не требуются для запроса возможности чтения всего URL-адреса. Чтобы узнать, можно ли прочитать данный компонент, передайте имя компонента в качестве второго аргумента:

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

Чтобы проверить, доступен ли для чтения конкретный ключ запроса, передайте ключ запроса в качестве третьего параметра:

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

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

Никто.

readCharacterSet

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

Синтаксис

readCharacterSet()

Параметры

Никто.

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

read_character_set

readTitle

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

Синтаксис

readTitle()

Параметры

Никто.

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

read_title

require

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

Синтаксис

require(name)

Параметры

Параметр Тип Описание
name нить Имя функции для импорта.

Пример

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

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

Никто.

sendPixel

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

Синтаксис

sendPixel(url, onSuccess, onFailure)

Параметры

Параметр Тип Описание
url нить Куда отправить пиксель.
onSuccess функция Вызывается при успешной загрузке пикселя. Примечание. даже если запрос успешно отправлен, браузерам может потребоваться действительный ответ изображения для запуска onSuccess.
onFailure функция Вызывается, когда пиксель не загружается. Примечание. Даже если запрос успешно отправлен, onFailure может запуститься, если сервер не возвращает действительный ответ изображения.

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

send_pixel

setCookie

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

Синтаксис

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

Параметры

Параметр Тип Описание
name нить Имя файла cookie.
value нить Значение файла cookie.
options объект Указывает атрибуты Domain, Path, Expires, Max-Age, Secure и SameSite . (См. «Параметры» ниже.)
encode логическое значение Определяет, должно ли значение cookie кодироваться с помощью JavaScript encodeURIComponent() . По умолчанию true .

Параметры

  • Домен: устанавливается свойством options['domain'] , если оно присутствует. Установите для этого значения значение 'auto' чтобы попытаться записать файл cookie с использованием максимально широкого домена в зависимости от местоположения документа. Если это не удастся, он будет последовательно пытаться использовать более узкие поддомены. Если все это не удастся, он попытается записать файл cookie без домена. Если значение не установлено, будет предпринята попытка записать файл cookie без указания домена. Примечание. Когда файл cookie без указанного домена записывается в document.cookie , пользовательский агент по умолчанию будет использовать домен файла cookie на хосте текущего местоположения документа.
  • Путь: устанавливается options['path'] , если они присутствуют. Когда файл cookie без указанного пути записывается в document.cookie , пользовательский агент по умолчанию будет использовать путь файла cookie к пути к текущему местоположению документа.
  • Максимальный возраст: устанавливается options['max-age'] , если они есть.
  • Срок действия: устанавливается параметром options['expires'] , если он присутствует. Если он присутствует, это должна быть строка даты в формате UTC. Date.toUTCString() можно использовать для форматирования Date для этого параметра.
  • Безопасность: устанавливается options['secure'] , если они присутствуют.
  • SameSite: устанавливается options['samesite'] , если они присутствуют.

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

set_cookies

setDefaultConsentState

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

Пример:

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

Синтаксис

setDefaultConsentState(consentSettings)

Параметры

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

Объект consentSettings представляет собой сопоставление произвольных строк типа согласия с одним из 'granted' или 'denied' . Он поддерживает следующие значения:

Имя ключа Тип Описание
consentType нить Значение для каждого типа согласия может быть установлено как «предоставлено» или «отказано». Любое значение, кроме «предоставлено», будет рассматриваться как «запрещено». Установка значения undef не повлияет на его предыдущее значение.
region Множество Необязательный массив кодов регионов, определяющий, к какому региону применяются настройки согласия. Коды регионов выражаются с использованием стран и/или подразделений в формате ISO 3166-2.
wait_for_update число Указывает значение в миллисекундах, определяющее продолжительность ожидания перед отправкой данных. Используется с инструментами согласия, которые загружаются асинхронно.

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

Разрешение access_consent с доступом на запись для всех типов согласия в объекте согласия.

setInWindow

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

Синтаксис

setInWindow(key, value, overrideExisting)

Параметры

Параметр Тип Описание
key нить Ключ в window для размещения значения.
value * Значение, которое нужно установить в window .
overrideExisting логическое значение Флаг, указывающий это значение, должен быть установлен в window , независимо от того, есть ли там значение или нет.

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

access_globals

sha256

Вычисляет дайджест входных данных SHA-256 и вызывает обратный вызов с дайджестом, закодированным в base64, если только в объекте options не указана другая кодировка выходных данных.

Пример:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

Синтаксис

sha256(input, onSuccess, onFailure = undefined, options = undefined)

Параметры

Параметр Тип Описание
input нить Строка, для которой вычисляется хэш.
onSuccess функция Вызывается с итоговым дайджестом, закодированным в base64, если только в объекте options не указана другая выходная кодировка.
onFailure функция Вызывается, если при вычислении дайджеста возникает ошибка или если в браузере нет встроенной поддержки sha256. Обратный вызов вызывается с объектом, содержащим имя ошибки и сообщение.
options объект Необязательный объект параметров для указания выходной кодировки. Если указано, объект должен содержать ключ outputEncoding со значением base64 или hex .

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

Никто.

templateStorage

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

Синтаксис

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

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

access_template_storage

Пример

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

API toBase64 позволяет кодировать строку в представление base64.

Синтаксис

toBase64(input)

Параметры

Параметр Тип Описание
input нить Строка для кодирования.

Пример

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

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

Никто

updateConsentState

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

Пример:

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

Синтаксис

updateConsentState(consentSettings)

Параметры

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

Объект consentSettings представляет собой сопоставление произвольных строк типа согласия с одним из 'granted' или 'denied' . Он поддерживает следующие значения:

Имя ключа Тип Описание
consentType нить Для каждого типа согласия можно установить значение «разрешено» или «отказано». Любое значение, кроме «предоставлено», будет рассматриваться как «отказано». Установка значения «неопределено» не повлияет на его предыдущее значение.

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

Разрешение access_consent с доступом на запись для всех типов согласия в объекте согласия.

Тестовые API

Эти API работают с изолированными тестами JavaScript для создания тестов для пользовательских шаблонов в Диспетчере тегов Google. Эти тестовые API не нуждаются в операторе require() . Узнайте больше о тестах на основе пользовательских шаблонов .

assertApi

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

Синтаксис

assertApi(apiName)

Параметры

Параметр Тип Описание
apiName нить Имя API для проверки; та же строка, что и переданная в require() .

Матчеры

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

Примеры

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

assertThat

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

Синтаксис

assertThat(actual, opt_message)

Параметры

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

Матчеры

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

Примеры

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

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

Синтаксис

fail(opt_message);

Параметры

Параметр Тип Описание
opt_message нить Необязательный текст сообщения об ошибке.

Пример

fail('This test has failed.');

mock

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

Синтаксис

mock(apiName, returnValue);

Параметры

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

Примеры

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

runCode

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

Синтаксис

runCode(data)

Параметры

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

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

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

Пример

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