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

Основные API

Используются в изолированном скрипте JavaScript для создания пользовательских шаблонов Google Менеджера тегов. Всегда добавляются с оператором require(). Пример:

const myAPI = require('myAPI');

addConsentListener

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

Этот прослушиватель будет вызываться каждый раз, когда состояние для указанного типа согласия меняется с denied (отклонено) на granted (предоставлено) или наоборот. Тип согласия без статуса считается предоставленным. Прослушиватель не будет вызываться, если неустановленный тип согласия изменился на granted. Функции прослушивателя будут отвечать за то, чтобы код запускался столько раз, сколько требуется.

Пример

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)

Параметры

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

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

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

addEventCallback

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

Синтаксис

addEventCallback(callback)

Параметры

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

Пример

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)

Параметры

Пример

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

Параметры

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

Разрешение access_globals с доступом execute.

callLater

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

Синтаксис

callLater(function)

Параметры

copyFromDataLayer

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

Синтаксис

copyFromDataLayer(key[, dataLayerVersion])

Параметры

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

read_data_layer

copyFromWindow

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

Синтаксис

copyFromWindow(key)

Параметры

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

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)

Параметры

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

access_globals

createQueue

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

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

Пример

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

Синтаксис

createQueue(arrayKey)

Параметры

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

access_globals

decodeUri

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

Пример

const decode = require('decodeUri');

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

Синтаксис

decodeUri(encoded_uri)

Параметры

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

Нет.

decodeUriComponent

Декодирует любые закодированные символы в предоставленном компоненте URI. Возвращает строку с расшифрованным компонентом URI. Возвращает значение undefined в случае ввода неправильных данных.

Пример

const decode = require('decodeUriComponent');

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

Синтаксис

decodeUriComponent(encoded_uri_component)

Параметры

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

Нет.

encodeUri

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

Пример

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

Синтаксис

encodeUri(uri)

Параметры

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

Нет.

encodeUriComponent

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

Пример

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

Синтаксис

encodeUriComponent(str)

Параметры

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

Нет.

fromBase64

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

Синтаксис

fromBase64(base64EncodedString)

Параметры

Пример

const fromBase64 = require('fromBase64');

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

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

Нет.

generateRandom

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

Синтаксис

generateRandom(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])

Параметры

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

get_cookies

getQueryParameters

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

Синтаксис

getQueryParameters(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, а к URL перехода. Возвращает первый или все параметры для ключа queryKey URL перехода. Возвращает первое значение ключа queryKey или массив значений queryKey.

Синтаксис

getReferrerQueryParameters(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 перехода и возвращает строку, которая представляет собой фрагмент URL перехода. Если компонент не задан, возвращается полный URL перехода.

Синтаксис

getReferrerUrl([component])

Параметры

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

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

getTimestamp

Поддержка прекращена. Предпочитаемый API – getTimestampMillis.

Выводит число с текущим Unix-временем в миллисекундах, возвращенным функцией Date.now().

Синтаксис

getTimestamp();

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

Нет.

getTimestampMillis

Выводит число с текущим Unix-временем в миллисекундах, возвращенным функцией Date.now().

Синтаксис

getTimestampMillis();

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

Нет.

getType

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

Синтаксис

getType(data.someField)

Примечания

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

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

Нет.

getUrl

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

Синтаксис

getUrl(component)

Параметры

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

get_url

gtagSet

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

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

Примеры

const gtagSet = require('gtagSet');

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

Синтаксис

gtagSet(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)

Параметры

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

inject_hidden_iframe

injectScript

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

Синтаксис

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

Параметры

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

inject_script

isConsentGranted

Возвращает true, если согласие предоставлено.

Согласие для определенного типа считается предоставленным, если для него задано значение granted или не задано никакого. При любых других вариантах значений согласие не считается предоставленным.

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

Пример

const isConsentGranted = require('isConsentGranted');

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

Синтаксис

isConsentGranted(consentType)

Параметры

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

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

JSON

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

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

Функция 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])

Параметры

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

logging

makeInteger

Конвертирует указанное значение в целое число.

Синтаксис

makeInteger(value)

Параметры

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

Нет.

makeNumber

Конвертирует указанное значение в число.

Синтаксис

makeNumber(value)

Параметры

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

Нет.

makeString

Возвращает указанное значение в виде строки.

Синтаксис

makeString(value)

Параметры

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

Нет.

makeTableMap

Преобразует простую таблицу из двух столбцов в массив Map. Используется для преобразования полей шаблона SIMPLE_TABLE в более удобный для работы формат.

Например, так могут выглядеть данные в таблице до преобразования:

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

А так будут выглядеть те же самые данные в виде массива:

{
  'k1': 'v1',
  'k2': 'v2'
}

Возвращаемый объект: ассоциативный массив Map (если в него при преобразовании были добавлены пары "ключ-значение") или значение null.

Синтаксис

makeTableMap(tableObj, keyColumnName, valueColumnName)

Параметры

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

Нет.

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

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

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

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

Синтаксис

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

Параметры

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Пример

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

Если формат 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);

Параметры

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

Нет.

queryPermission

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

Синтаксис

queryPermission(permission, functionArgs*)

Параметры

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

sendPixel, injectScript, injectHiddenIframe. Второй параметр представляет собой строку URL.

writeGlobals, readGlobals. Второй параметр представляет собой ключ для записи или чтения.

readUrl. Для запроса разрешения на чтение целого URL дополнительные аргументы указывать не нужно. Если вы запрашиваете разрешение на чтение определенного компонента, передайте его название в качестве второго аргумента:

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

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

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

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

Нет.

readAnalyticsStorage

Извлекает данные, сохраненные для аналитики, и возвращает объект с client_id и sessions.

• client_id: строка, представляющая идентификатор клиента, который используется для аналитики.
• sessions – массив объектов, содержащих информацию о текущих сеансах. Каждый объект включает:
  • measurement_id: строка, представляющая идентификатор потока данных целевого сервиса Аналитики.
  • session_id – строка, представляющая временную метку, которая идентифицирует текущий сеанс.
  • session_number – число, представляющее количество сеансов, которые пользователь провел до текущего сеанса.

Синтаксис

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

Параметры

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

read_analytics_storage

Пример

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

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

Синтаксис

readCharacterSet()

Параметры

Нет.

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

read_character_set

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

Параметры

Настройки

• Domain. Задается свойством options['domain'], если оно есть. Укажите значение 'auto', чтобы создать файл cookie, используя максимально широкий домен с учетом того, где находится документ. Если это не удастся, попытки будут последовательно повторяться со все более узкими субдоменами. Если все попытки закончатся неудачей, функция попытается создать файл cookie без домена. Если значение этого свойства не указано, функция также попытается создать файл cookie без домена. Примечание: если в свойстве document.cookie указан файл cookie без домена, то агент пользователя по умолчанию использует для этого файла cookie домен, в котором размещен текущий документ.
• Path. Задается свойством options['path'], если оно есть. Если в свойстве document.cookie указан файл cookie без пути, агент пользователя будет по умолчанию применять путь текущего местоположения документа.
• Max-Age. Задается свойством options['max-age'], если оно есть.
• Expires. Задается свойством options['expires'], если оно есть. В нем указывается строковое значение даты в формате UTC. Форматировать свойство Date этого параметра можно с помощью метода Date.toUTCString().
• Secure. Задается свойством 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 представляет собой сопоставление строк произвольного типа согласия с 'granted' или 'denied'. Возможные значения:

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

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

setInWindow

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

Синтаксис

setInWindow(key, value, overrideExisting)

Параметры

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

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)

Параметры

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

Нет.

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)

Параметры

Пример

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 представляет собой сопоставление строк произвольного типа согласия с 'granted' или 'denied'. Возможные значения:

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

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

API тестирования

Используются для создания тестов, проверяющих работу изолированного JavaScript в пользовательских шаблонах Google Менеджера тегов. Для этих API не требуется оператор require(). Подробнее о тестировании пользовательских шаблонов…

assertApi

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

Синтаксис

assertApi(apiName)

Параметры

Методы сопоставления

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

Параметры

Методы сопоставления

Примеры

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

Параметры

Пример

fail('This test has failed.');

mock

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

Синтаксис

mock(apiName, returnValue);

Параметры

Примеры

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

mockObject

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

Синтаксис

mockObject(apiName, objectMock);

Параметры

Примеры

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

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

Синтаксис

runCode(data)

Параметры

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

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

Пример

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