Примечание. Этот сайт для разработчиков будет перенесен на новый адрес developers.google.com/tag-platform к 30 сентября 2021 г.

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)

Параметры

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

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

Параметр Тип Описание
consentType string Изменяемый тип согласия.
granted boolean Логическое значение, которое принимает значение true, если указанный тип согласия меняется на granted.

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

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

addEventCallback

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

Синтаксис

addEventCallback(callback)

Параметры

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

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

Название ключа Тип Описание
tags Array Массив объектов с данными о тегах. Содержит записи о каждом теге, активированном во время события. Объект с данными о теге имеет такую структуру: идентификатор тега (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 string Разделенный точками путь к объекту window, в который копируется значение. Все части пути в объекте window должны уже существовать.
fromPath string Путь к копируемому значению window, разделенный точками. Если значение не существует, операция выполнена не будет.

Пример

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

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

Разрешение access_globals обязательно для параметров toPath и fromPath. Для toPath требуется доступ с правом записи, а для fromPath – чтения.

callInWindow

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

Синтаксис

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

Параметры

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

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

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

callLater

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

Синтаксис

callLater(function)

Параметры

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

copyFromDataLayer

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

Синтаксис

copyFromDataLayer(key[, dataLayerVersion])

Параметры

Параметр Тип Описание
key string Ключ в формате "a.b.c".
dataLayerVersion number Необязательная версия уровня данных. Значение по умолчанию – 2. Указывать значение "1" не рекомендуется.

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

read_data_layer

copyFromWindow

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

Синтаксис

copyFromWindow(key)

Параметры

Параметр Тип Описание
key string Ключ в объекте 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 string Путь в объекте window, где находится или будет создана функция. Аргумент поддерживает стандартную точечную нотацию. Если путь к ключу не существует, выдается исключение. Например, исключение будет выдано, если аргументу fnKey присвоить значение 'one.two'.
arrayKey string Путь в объекте window, где находится или будет создан массив. Аргумент поддерживает стандартную точечную нотацию. Если путь к ключу не существует, выдается исключение. Например, исключение будет выдано, если аргументу arrayKey присвоить значение 'one.two', но глобального объекта с названием 'one' не существует.

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

access_globals

createQueue

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

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

Пример:

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

Синтаксис

createQueue(arrayKey)

Параметры

Параметр Тип Описание
arrayKey string Ключ в объекте 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 string URI, закодированный с помощью функции encodeUri() или другими методами.

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

Нет.

decodeUriComponent

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

Пример:

const decode = require('decodeUriComponent');

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

Синтаксис

decodeUriComponent(encoded_uri_component)

Параметры

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

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

Нет.

encodeUri

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

Пример:

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

Синтаксис

encodeUri(uri)

Параметры

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

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

Нет.

encodeUriComponent

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

Пример:

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

Синтаксис

encodeUriComponent(str)

Параметры

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

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

Нет.

fromBase64

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

Синтаксис

fromBase64(base64EncodedString)

Параметры

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

Пример

const fromBase64 = require('fromBase64');

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

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

Нет

generateRandom

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

Синтаксис

generateRandom(min, max)

Параметры

Параметр Тип Описание
min number Минимальное значение диапазона.
max number Максимальное значение диапазона.

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

Нет.

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 string Имя файла cookie.
decode boolean Определяет, следует ли декодировать значения файлов cookie с помощью метода JavaScript decodeURIComponent(). Значение по умолчанию – true.

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

get_cookies

getQueryParameters

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

Синтаксис

getQueryParameters(queryKey[, retrieveAll])

Параметры

Параметр Тип Описание
queryKey string Ключ для считывания параметров запроса.
retrieveAll boolean Определяет, получать ли все значения.

Например, для текущего 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])

Параметры

Параметр Тип Описание
queryKey string Ключ для считывания параметров запроса.
retrieveAll boolean Определяет, получать ли все значения.

Например, для 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])

Параметры

Параметр Тип Описание
component string Возвращаемый компонент URL. Допустимые типы: protocol, host, port, path, query, extension. Если component имеет значение undefined, null или не совпадает с допустимыми типами, возвращается полный URL.

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

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

getTimestamp

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

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

Синтаксис

getTimestamp();

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

Нет.

getTimestampMillis

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

Синтаксис

getTimestampMillis();

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

Нет.

getType

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

Синтаксис

getType(data.someField)

Примечания

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

Значение Результат
undefined undefined
null null
true boolean
12 number
'string' string
{ a: 3 } object
[ 1, 3 ] array
(x) => x + 1 function

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

Нет.

getUrl

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

Синтаксис

getUrl(component)

Параметры

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

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

get_url

injectHiddenIframe

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

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

Синтаксис

injectHiddenIframe(url, onSuccess)

Параметры

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

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

inject_hidden_iframe

injectScript

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

Синтаксис

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

Параметры

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

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

inject_script

isConsentGranted

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

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

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

Пример:

const isConsentGranted = require('isConsentGranted');

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

Синтаксис

isConsentGranted(consentType)

Параметры

Параметр Тип Описание
consentType string Тип согласия, состояние которого нужно проверить.

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

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

JSON

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

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

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

Синтаксис

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

Параметры

JSON.parse

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

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 List Таблица, которую нужно преобразовать. Представляет собой список массивов, в котором каждому объекту Map соответствует одна строка в таблице. Имена свойств в строках являются названиями столбцов, а значения этих свойств – значениями столбцов в строке.
keyColumnName string Название столбца, значения из которого станут ключами в полученном массиве Map.
valueColumnName string Название столбца, значения из которого станут значениями в полученном массиве 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);

Параметры

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

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

Нет.

parseUrl

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

Если формат URL неверный, этот API будет возвращать код undefined. При правильном формате URL поля, отсутствующие в строке URL, будут иметь значение пустой строки, а при использовании searchParams – пустой объект.

Объект содержит следующие поля:

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Пример

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Синтаксис

parseUrl(url);

Параметры

Параметр Тип Описание
url string Полный URL для анализа.

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

Нет.

queryPermission

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

Синтаксис

queryPermission(permission, functionArgs*)

Параметры

Параметр Тип Описание
permission string Название разрешения.
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

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

Синтаксис

require(name)

Параметры

Параметр Тип Описание
name string Название импортируемой функции.

Пример

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

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

Нет.

sendPixel

Отправляет запрос GET в конечную точку заданного URL.

Синтаксис

sendPixel(url, onSuccess, onFailure)

Параметры

Параметр Тип Описание
url string Куда передавать пиксель.
onSuccess function Вызывается при успешной отправке пикселя.
onFailure function Вызывается при ошибке отправки пикселя.

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

send_pixel

setCookie

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

Синтаксис

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

Параметры

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

Дополнительные параметры

  • 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',
  'region': ['US-CA'],
  'wait_for_update': 500
});

Синтаксис

setDefaultConsentState(consentSettings)

Параметры

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

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

Название ключа Тип Описание
consentType string Для каждого типа согласия может быть установлено значение 'granted' или 'denied'. Если значение не равно 'granted', оно воспринимается как 'denied'. Если вы зададите значение undefined, это не повлияет на ранее указанное значение.
region Array Необязательный массив кодов регионов, определяющих, к какому региону применяются настройки согласия. Допустимые значения – коды стран и/или административных единиц в формате ISO 3166-2.
wait_for_update number Время ожидания перед отправкой данных. Значение в миллисекундах. Используется с инструментами для запроса согласия, которые загружаются асинхронно.

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

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

setInWindow

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

Синтаксис

setInWindow(key, value, overrideExisting)

Параметры

Параметр Тип Описание
key string Ключ в объекте window, куда нужно ввести данные.
value * Значение задается в window.
overrideExisting boolean Вводить ли данные, независимо от того, пустой объект 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 string Строка для вычисления хеша.
onSuccess function Вызывается с полученным дайджестом, закодированным в base64, если только в объекте options не указана другая кодировка выходных данных.
onFailure function Вызывается, если при вычислении дайджеста возникает ошибка либо если в браузере нет встроенной поддержки sha256. Обратный вызов осуществляется с объектом, содержащим имя ошибки и сообщение.
options object Необязательный объект настроек, в котором можно задать кодировку выходных данных. Если объект используется, он должен содержать ключ 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 string Кодируемая строка.

Пример

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

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

Нет

updateConsentState

Обновляет состояние указанных типов согласия.

Пример:

const updateConsentState = require('updateConsentState');

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

Синтаксис

updateConsentState(consentSettings)

Параметры

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

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

Название ключа Тип Описание
consentType string Для каждого типа согласия может быть установлено значение 'granted' или 'denied'. Если значение не равно 'granted', оно воспринимается как 'denied'. Если вы зададите значение undefined, это не повлияет на ранее указанное значение.

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

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

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

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

assertApi

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

Синтаксис

assertApi(apiName)

Параметры

Параметр Тип Описание
apiName string Название тестируемого 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 string Необязательное сообщение, которое будет показано, если утверждение окажется неверным.

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

Метод сопоставления Описание
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() Проверяет утверждение о том, что значение не является числовым.
isNotNaN() Проверяет утверждение о том, что значение является любым, кроме нечислового.
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 string Вариант сообщения об ошибке.

Пример

fail('This test has failed.');

mock

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

Синтаксис

mock(apiName, returnValue);

Параметры

Параметр Тип Описание
apiName string Название имитируемого 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 object Объект данных, который будет использоваться в тесте.

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

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

Пример

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