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

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

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

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

  • проверяется тем 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 перехода".

Описание: разрешает доступ для чтения к более коротким фрагментам URL перехода.

Настройки: следующие логические значения определяют, какая часть URL перехода будет доступна для чтения. Часть URL будет доступна для чтения, если для нее задано значение true. Если значение true будет задано для всех частей, то функцию getReferrerUrl можно вызвать, даже если не указан компонент, определяющий доступ к полному URL перехода. По умолчанию используется значение 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

Отображаемое название: Reads URL.

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

Настройки: доступность частей URL для чтения определяется перечисленными в конце абзаца логическими значениями. Часть URL будет доступна для чтения, если для нее задано значение true. Если в вызове 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.

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

Примечание. Этот ключ определяет, может ли пользовательский шаблон считывать данные 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);
}

logging

Отображаемое название: "Вход в консоль".

Описание. Передает данные журнала в консоль разработчика и делает их доступными в режиме предварительного просмотра Google Менеджера тегов.

Настройки: определяет возможность ведения журнала в рабочей версии. По умолчанию журнал ведется только в режиме отладки (предварительного просмотра). Если не предоставить разрешение, 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, в зависимости от следующих его параметров: имени, домена и пути, атрибута 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);
}