Пользовательские 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)

Параметры

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

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

разрешение 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 . В изолированном JavaScript поддерживаются восемь типов: 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. Возвращает первый или все параметры для queryKey заданного реферера. Возвращает первое значение из 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 реферера.

Синтаксис

getReferrerUrl([component])

Параметры

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

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

getTimestamp

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

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

Синтаксис

getTimestamp();

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

Никто.

getTimestampMillis

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

Синтаксис

getTimestampMillis();

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

Никто.

getType

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

Синтаксис

getType(data.someField)

Примечания

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

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

Никто.

getUrl

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

Синтаксис

getUrl(component)

Параметры

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

get_url

gtagSet

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

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

Примеры:

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

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

Синтаксис

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

Параметры

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

inject_script

isConsentGranted

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

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

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

Пример:

const isConsentGranted = require('isConsentGranted');

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

Синтаксис

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

Параметры

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

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() возвращает тот же объект, который был передан. Аргумент-примитив или null будет обработан как замороженный объект и будет возвращён.

Метод 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

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

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

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

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

Пример

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

Параметры

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

Никто.

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 : строка, представляющая идентификатор измерения для пункта назначения Analytics.
  • 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])

Параметры

Параметры

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

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

assertApi

Возвращает объект сопоставления, который можно использовать для быстрого создания утверждений о заданном 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'});