Пользовательские разрешения для шаблонов

В этом документе описаны разрешения для пользовательских веб-шаблонов.

Каждое разрешение:

  • Проверено API, которым они требуются.
  • Автоматически обнаруживается в изолированном JavaScript в зависимости от используемых API. Это происходит при внесении изменений в редакторе пользовательских шаблонов (для быстрого цикла обратной связи) и при компиляции кода (для проверки соблюдения правильных разрешений).
  • Редактируется в редакторе пользовательских шаблонов, чтобы сделать разрешение более конкретным.
  • Доступен для запросов в изолированном JavaScript через API queryPermission .

access_globals

Отображаемое имя: Доступ к глобальным переменным.

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

Конфигурация: список ключей, к которым можно получить доступ. Каждый ключ представляет собой путь, разделенный точкой. Например: foo.bar Первый токен в каждом пути не должен быть ни предопределенным ключом в глобальной области браузера, ни ключевым словом JavaScript. Имеет флажки чтения, записи и выполнения, управляющие доступом.

Требуется: setInWindow , copyFromWindow , callInWindow , createQueue , createArgumentsQueue

Сигнатура запроса: queryPermission('access_globals', 'read', <key to read from>) или queryPermission('access_globals', 'write', <key to write to>) или queryPermission('access_globals', 'readwrite', <key to read and write>) или queryPermission('access_globals', 'execute', <key of function to execute>)

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

Пример кода 

const queryPermission = require('queryPermission');
const createQueue = require('createQueue');
if (queryPermission('access_globals', 'readwrite', 'dataLayer')) {
  const dataLayerPush = createQueue('dataLayer');
}

access_local_storage

Отображаемое имя: Доступ к локальному хранилищу.

Описание: Разрешает доступ к указанным ключам в локальном хранилище.

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

Требуется: localStorage

Сигнатура запроса: queryPermission('access_local_storage', 'read', <key to read from>) или queryPermission('access_local_storage', 'write', <key to write to>) или queryPermission('access_local_storage', 'readwrite', <key to read and write>)

Пример кода 

const queryPermission = require('queryPermission');
const localStorage = require('localStorage');
const key = 'my_key';
if (queryPermission('access_local_storage', 'read', key)) {
  const value = localStorage.getItem(key);
}

access_template_storage

Отображаемое имя: Доступ к хранилищу шаблонов.

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

Конфигурация: Нет

Требуется: templateStorage

Подпись запроса: queryPermission('access_template_storage')

Пример кода 

const queryPermission = require('queryPermission');
const templateStorage = require('templateStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateStorage.getItem(key);
}

get_cookies

Отображаемое имя: Считывает значения файлов cookie.

Описание: Считывает значения файлов cookie с указанным именем.

Конфигурация: список имен файлов cookie, разрешенных для чтения.

Требуется: getCookieValues

Сигнатура запроса: queryPermission('get_cookies', <name>)

Примечания. Определяет возможность чтения файла cookie в зависимости от его имени.

Пример кода 

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

get_referrer

Отображаемое имя: считывает URL-адрес реферера.

Описание: Разрешает доступ для чтения к суженным частям реферера.

Конфигурация: Следующие логические значения определяют, какая часть реферера может быть прочитана. Определенную часть реферера можно прочитать только в том случае, если соответствующая часть имеет true . Вызывающий может вызвать getReferrerUrl без указания компонента, чтобы получить полный URL-адрес реферера, если для всех этих логических значений установлено значение true . Если значение не задано, значение по умолчанию — all . Если значение установлено, оно должно быть массивом компонентов, где компонент является одним из следующих: protocol , host , port , path , query или extension .

queryKeys : если выбран запрос, автор шаблона может дополнительно ограничить набор ключей запроса, которые он может читать. Это простой массив ключей без подстановочных знаков.

Требуется: getReferrerUrl , getReferrerQueryParameters

Сигнатура запроса: queryPermission('get_referrer', <url_component>)

Пример кода 

const queryPermission = require('queryPermission');
const getReferrerUrl = require('getReferrerUrl');
let referrer;
if (queryPermission('get_referrer', 'query')) {
  referrer = getReferrerUrl('queryParams');
}

get_url

Отображаемое имя: читает URL-адрес.

Описание: Возвращает часть или весь URL-адрес текущей страницы.

Конфигурация: следующие логические значения определяют, какая часть URL-адреса может быть прочитана. Определенную часть URL-адреса можно прочитать, только если соответствующая часть верна. Вызывающий может вызвать getUrl без указания компонента для получения всего URL-адреса тогда и только тогда, когда для всех этих логических значений установлено значение true . Если значение не задано, значение по умолчанию — all . Если значение установлено, оно должно быть массивом компонентов, где компонент является одним из следующих: protocol , host , port , path , query , extension или fragment .

queryKeys : если выбран запрос, автор шаблона может дополнительно ограничить набор ключей запроса, которые он может читать. Это простой массив ключей без подстановочных знаков.

Требуется: getUrl

Подпись запроса: queryPermission('get_url', <optional url component>, <optional query key>)

Если он указан, компонент URL должен быть одним из 'protocol' , 'host' , 'port' , 'path' , 'query' , 'extension' , 'fragment' . Если этот параметр опущен, запрос разрешения представляет собой запрос на доступ ко всему URL-адресу.

Если он указан, ключ запроса должен быть аргументом строки запроса, который код шаблона хочет прочитать.

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

Пример кода 

const queryPermission = require('queryPermission');
const getUrl = require('getUrl');
if (queryPermission('get_url', 'query', 'gclid')) {
  const gclid = getUrl('query', false, null, 'gclid');
}

inject_hidden_iframe

Отображаемое имя: Вставляет скрытые iframe.

Описание: Вставляет невидимый iframe с заданным URL-адресом.

Конфигурация: список шаблонов URL-адресов.

Требуется: injectHiddenIframe

Сигнатура запроса: queryPermission('inject_hidden_iframe', <url>)

Примечания. Определяет, может ли пользовательский шаблон вставлять невидимый iFrame и из какого источника он может это делать.

Пример кода 

const queryPermission = require('queryPermission');
const injectHiddenIframe = require('injectHiddenIframe');
const url = 'https://www.example.com/iframes';
if (queryPermission('inject_hidden_iframe', url)) {
  injectHiddenIframe(url);
}

inject_script

Отображаемое имя: Внедряет сценарии.

Описание: Вставляет скрипт на страницу.

Конфигурация: список шаблонов URL-адресов.

Требуется: injectScript

Сигнатура запроса: queryPermission('inject_script', <url>)

Примечания. Определяет, может ли пользовательский шаблон внедрять JavaScript и из какого источника он может это делать.

Пример кода 

const queryPermission = require('queryPermission');
const injectScript = require('injectScript');
const url = 'https://www.example.com?api.js';
if (queryPermission('inject_script', url)) {
  injectScript(url);
}

регистрация

Отображаемое имя: Журналы на консоли.

Описание: вход в консоль разработчика и режим предварительного просмотра GTM.

Конфигурация: возможность включить вход в производство. По умолчанию включено только ведение журнала в режиме отладки/предварительного просмотра. Если в разрешении отказано, logToConsole не выдаст ошибку, но заблокирует сообщение журнала.

Требуется: logToConsole

Сигнатура запроса: queryPermission('logging')

Примечания. Определяет, может ли пользовательский шаблон войти в консоль разработчика.

Пример кода 

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

read_data_layer

Отображаемое имя: Считывает слой данных.

Описание: Считывает данные из dataLayer.

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

Требуется: copyFromDataLayer

Сигнатура запроса: queryPermission('read_data_layer', <data layer key to read from>)

Примечания. Определяет, может ли пользовательский шаблон читать данные с уровня.

Пример кода 

const queryPermission = require('queryPermission');
const copyFromDataLayer = require('copyFromDataLayer');
const dlKey = 'foo.bar';
if (queryPermission('read_data_layer', dlKey)) {
  const dlContents = copyFromDataLayer(dlKey);
}

read_character_set

Отображаемое имя: Считывает набор символов документа.

Описание: Читает document.characterSet .

Конфигурация: Нет

Требуется: readCharacterSet

Подпись запроса: queryPermission('read_character_set')

Примечания. Определяет, может ли пользовательский шаблон читать document.characterSet .

Пример кода 

const queryPermission = require('queryPermission');
const readCharacterSet = require('readCharacterSet');
if (queryPermission('read_character_set')) {
  const characterSet = readCharacterSet();
}

read_container_data

Отображаемое имя: Считывает данные контейнера.

Описание: Считывает данные о контейнере.

Конфигурация: Нет

Требуется: getContainerVersion

Подпись запроса: queryPermission('read_container_data')

Примечания. Определяет, может ли пользовательский шаблон читать данные о контейнере.

Пример кода 

const queryPermission = require('queryPermission');
const getCookieValues = require('getContainerVersion');
let version;
if (queryPermission('read_container_data')) {
  version = getContainerVersion();
}

read_event_metadata

Отображаемое имя: Считывает метаданные события.

Описание: Считывает метаданные событий в обратных вызовах событий.

Конфигурация: Нет

Требуется: addEventCallback

Подпись запроса: queryPermission('read_event_metadata')

Примечания. Определяет, может ли пользовательский шаблон читать метаданные событий в обратных вызовах.

Пример кода 

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_title

Отображаемое имя: читает заголовок документа.

Описание: Читает document.title .

Конфигурация: Нет

Требуется: readTitle

Подпись запроса: queryPermission('read_title')

Примечания. Определяет, может ли пользовательский шаблон читать document.title .

Пример кода 

const queryPermission = require('queryPermission');
const readTitle = require('readTitle');
if (queryPermission('read_title')) {
  const title = readTitle();
}

send_pixel

Отображаемое имя: Отправляет пиксели

Описание: Отправляет запрос GET на указанный URL-адрес. Ответ не обрабатывается.

Конфигурация: список разрешенных шаблонов URL-адресов.

Требуется: sendPixel

Сигнатура запроса: queryPermission('send_pixel', <url>)

Примечания. Определяет, может ли пользовательский шаблон отправлять запрос GET и в какой источник он может это сделать.

Пример кода 

const queryPermission = require('queryPermission');
const sendPixel = require('sendPixel');
const url = 'https://www.example.com?foo=3';
if (queryPermission('send_pixel', url)) {
  sendPixel(url);
}

set_cookies

Отображаемое имя: Устанавливает файл cookie.

Описание: Устанавливает файл cookie с указанным именем и параметрами.

Конфигурация: таблица разрешенных имен файлов cookie, каждое из которых имеет дополнительные ограничения по имени, домену, пути, атрибуту secure и сроку действия.

Требуется: setCookie

Сигнатура запроса: queryPermission('set_cookies', <name>, <options>)

Примечания. Определяет возможность записи файла cookie в зависимости от имени файла cookie, домена, пути, атрибута secure и срока действия.

Пример кода 

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

write_data_layer

Отображаемое имя: Записывает слой данных.

Описание: Записывает данные в dataLayer.

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

Требуется: gtagSet

Сигнатура запроса: queryPermission('write_data_layer', <data layer key to write from>)

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

Пример кода 

const queryPermission = require('queryPermission');
const gtagSet = require('gtagSet');
const dlKey = 'foo.bar';
if (queryPermission('write_data_layer', dlKey)) {
  gtagSet({dlKey: 'baz'});
}