Permisos de plantillas personalizadas

En este documento, se describen los permisos de las plantillas personalizadas de páginas web.

Cada permiso:

Lo comprueban las APIs que lo necesitan.
Se detecta automáticamente en JavaScript en zona de pruebas, según las APIs que se utilicen. Esto sucede cuando se realizan modificaciones en el editor de plantillas personalizadas (para conseguir un bucle de retroalimentación rápido) y cuando se compila el código (para validar que se aplican los permisos correctos).
Se puede editar en el editor de plantillas personalizadas para hacerlo más específico.
Se puede consultar en JavaScript en zona de pruebas a través de la API queryPermission.

access_globals

Nombre visible: Accede a variables globales

Descripción: Permite el acceso a variables globales (posiblemente incluidas las APIs sensibles).

Configuración: Lista de claves a las que se puede acceder. Cada clave es una ruta separada por puntos. Por ejemplo, foo.bar. El primer token de cada ruta no debe ser una clave predefinida en el alcance global del navegador ni una palabra clave de JavaScript. Tiene casillas para permisos de lectura, escritura y ejecución que determinan el acceso.

Requerido por: setInWindow, copyFromWindow, callInWindow, createQueue y createArgumentsQueue

Firma de la consulta: 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>) o queryPermission('access_globals', 'execute', <key of function to execute>)

Notas: Controla si una plantilla personalizada puede leer y escribir valores globales.

Código de ejemplo

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

acceso_local_storage

Nombre visible: Accede al almacenamiento local

Descripción: Permite el acceso a las claves especificadas del almacenamiento local.

Configuración: Lista de claves de almacenamiento local a las que se puede acceder. Se trata de una matriz de claves simple, sin comodines. Tiene casillas para permisos de lectura y escritura que determinan el acceso.

Requerido por: localStorage

Sintaxis de la consulta: queryPermission('access_local_storage', 'read', <key to read from>), queryPermission('access_local_storage', 'write', <key to write to>) o queryPermission('access_local_storage', 'readwrite', <key to read and write>)

Código de ejemplo

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

Nombre visible: Accede al almacenamiento de la plantilla

Descripción: Permite el acceso al almacenamiento temporal de las plantillas que se aplican durante todo el periodo de publicación de la página.

Configuración: Ninguna.

Requerido por: templateStorage

Sintaxis de la consulta: queryPermission('access_template_storage')

Código de ejemplo

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

get_cookies

Nombre visible: Lee los valores de las cookies

Descripción: Lee los valores de las cookies con el nombre especificado.

Configuración: Lista de nombres de cookies que se pueden leer.

Requerido por: getCookieValues

Sintaxis de la consulta: queryPermission('get_cookies', <name>)

Notas: Determina si se puede leer una cookie en función de su nombre.

Código de ejemplo

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

get_referrer

Nombre visible: Lee la URL referente

Descripción: Permite el acceso de lectura a partes específicas de la URL referente.

Configuración: Los siguientes valores booleanos determinan qué parte de la URL referente se pueden leer. Una parte determinada de la URL referente solo puede leerse si el valor de la parte correspondiente es true. Se puede llamar a getReferrerUrl sin especificar un componente para obtener la URL referente completa si se asigna el valor true a todos los booleanos. El valor predeterminado es all si no se especifica ninguno. Si se especifica, debe ser una matriz de componentes que contenga uno de los siguientes: protocol, host, port, path, query o extension.

queryKeys: Si se selecciona "query", el autor de la plantilla puede limitar aún más el conjunto de claves de consulta desde las que se puede leer. Se trata de una matriz de claves simple, sin comodines.

Requerido por: getReferrerUrl y getReferrerQueryParameters

Sintaxis de la consulta: queryPermission('get_referrer', <url_component>)

Código de ejemplo

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

get_url

Nombre visible: Lee URLs

Descripción: Devuelve la URL de la página abierta en parte o en su totalidad.

Configuración: Los siguientes valores booleanos determinan qué parte de la URL se puede leer. Una parte determinada de la URL solo se puede leer si el valor de la parte correspondiente es "true". Se puede llamar a getUrl sin especificar un componente para obtener la URL completa solo si se asigna el valor true a todos los booleanos. El valor predeterminado es all si no se especifica ninguno. Si se especifica, debe ser una matriz de componentes que contenga uno de los siguientes: protocol, host, port, path, query, extension o fragment.

Requerido por: getUrl

Firma de la consulta: queryPermission('get_url', <optional url component>, <optional query key>)

Si se proporciona, la URL debe ser una de estas: 'protocol', 'host', 'port', 'path', 'query', 'extension' o 'fragment'. Si no se incluye, la consulta de permisos es una solicitud de acceso a toda la URL.

Si se proporciona, la clave de consulta debe ser el argumento de la cadena de consulta que el código de la plantilla quiere leer.

Notas: Controla si una plantilla personalizada puede leer desde la ubicación correspondiente. Se puede limitar a una parte específica de la ubicación.

Código de ejemplo

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

inject_hidden_iframe

Nombre visible: Inserta iframes ocultos

Descripción: Inserta un iframe invisible en una URL específica.

Configuración: Lista de patrones de URL.

Requerido por: injectHiddenIframe

Firma de la consulta: queryPermission('inject_hidden_iframe', <url>)

Notas: Controla si una plantilla personalizada puede insertar un iframe invisible y desde qué origen puede hacerlo.

Código de ejemplo

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

Nombre visible: Inserta secuencias de comandos

Descripción: Inserta una secuencia de comandos en la página.

Configuración: Lista de patrones de URL.

Requerido por: injectScript

Firma de la consulta: queryPermission('inject_script', <url>)

Notas: Controla si una plantilla personalizada puede insertar código JavaScript y desde qué origen puede hacerlo.

Código de ejemplo

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

logging

Nombre visible: Registra información en la consola

Descripción: Registra información en la consola para desarrolladores y en el modo de vista previa de Tag Manager.

Configuración: Opción para habilitar el registro en producción. De forma predeterminada, solo se habilita el registro en depuración o vista previa. Si se deniega el permiso, logToConsole no generará un error, pero eliminará el mensaje de registro.

Requerido por: logToConsole

Sintaxis de la consulta: queryPermission('logging')

Notas: Controla si una plantilla personalizada puede registrar información en la consola para desarrolladores.

Código de ejemplo

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

Nombre visible: Lee la capa de datos

Descripción: Lee los datos de dataLayer.

Configuración: Conjunto de expresiones de coincidencia de claves, donde una coincidencia de clave puede ser una serie de referencias compuestas por puntos al principio con un comodín al final. Las expresiones de coincidencia de claves determinan qué propiedades se pueden leer de la capa de datos.

Requerido por: copyFromDataLayer

Sintaxis de la consulta: queryPermission('read_data_layer', <data layer key to read from>)

Notas: Controla si una plantilla personalizada puede leer la capa de datos.

Código de ejemplo

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

Nombre visible: Lee el conjunto de caracteres del documento

Descripción: Lee document.characterSet.

Configuración: Ninguna.

Requerido por: readCharacterSet

Firma de la consulta: queryPermission('read_character_set')

Notas: Controla si una plantilla personalizada puede leer document.characterSet.

Código de ejemplo

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

read_container_data

Nombre visible: Lee los datos del contenedor

Descripción: Lee datos sobre el contenedor.

Configuración: Ninguna.

Requerido por: getContainerVersion

Sintaxis de la consulta: queryPermission('read_container_data')

Notas: Controla si una plantilla personalizada puede leer datos sobre el contenedor.

Código de ejemplo

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

read_event_metadata

Nombre visible: Lee los metadatos de eventos

Descripción: Lee metadatos de eventos en retrollamadas de eventos.

Configuración: Ninguna.

Requerido por: addEventCallback

Firma de la consulta: queryPermission('read_event_metadata')

Notas: Controla si una plantilla personalizada puede leer metadatos de eventos en retrollamadas.

Código de ejemplo

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

read_title

Nombre visible: Lee el título del documento

Descripción: Lee document.title.

Configuración: Ninguna.

Requerido por: readTitle

Sintaxis de la consulta: queryPermission('read_title')

Notas: Controla si una plantilla personalizada puede leer document.title.

Código de ejemplo

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

send_pixel

Nombre visible: Envía píxeles

Descripción: Envía una solicitud GET a la URL especificada. La respuesta no se procesa.

Configuración: Lista de patrones de URL permitidos.

Requerido por: sendPixel

Firma de la consulta: queryPermission('send_pixel', <url>)

Notas: Controla si una plantilla personalizada puede enviar una solicitud GET y a qué origen puede hacerlo.

Código de ejemplo

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

Nombre visible: Configura una cookie

Descripción: Configura una cookie con el nombre y los parámetros especificados.

Configuración: Tabla de nombres de cookies admitidos, cada uno con restricciones opcionales de nombre, dominio, ruta, atributo secure y caducidad.

Requerido por: setCookie

Firma de la consulta: queryPermission('set_cookies', <name>, <options>)

Notas: Controla si se puede escribir una cookie, en función de su nombre, el dominio, la ruta, el atributo secure y la caducidad.

Código de ejemplo

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