Permissões de modelo personalizado

Este documento descreve as permissões para modelos personalizados da Web.

Todas as permissões são:

  • verificadas pelas APIs que as exigem;
  • detectadas automaticamente em JavaScript em sandbox, com base em quais APIs são usadas. Isso acontece porque as edições são feitas no editor de modelos personalizados (para um loop de feedback rápido) e quando o código é compilado (para validar se as permissões corretas foram aplicadas);
  • modificáveis no editor de modelos personalizados para tornar a permissão mais específica;
  • consultáveis em JavaScript no modo sandbox pela API queryPermission.

access_globals

Nome de exibição: acessa as variáveis globais.

Descrição: permite acesso a uma variável global (possivelmente incluindo APIs confidenciais).

Configuração: lista de chaves que podem ser acessadas. Cada chave é um caminho separado por pontos. Por exemplo: foo.bar. O primeiro token em cada caminho não pode ser uma chave predefinida no escopo global do navegador nem uma palavra-chave em JavaScript. Tem caixas de seleção de leitura, gravação e execução que controlam o acesso.

Solicitado por: setInWindow, copyFromWindow, callInWindow, createQueue e createArgumentsQueue

Assinatura da 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>) ou queryPermission('access_globals', 'execute', <key of function to execute>)

Observações: define se um modelo personalizado pode ler e/ou gravar nos valores globais.

Exemplo de código

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

access_local_storage

Nome de exibição: acessa o armazenamento local.

Descrição: permite acesso às chaves especificadas no armazenamento local.

Configuração: lista das chaves de armazenamento local que podem ser acessadas. Essa é uma matriz simples de chaves que não contém caracteres curinga. Tem caixas de seleção de leitura e gravação que controlam o acesso.

Solicitado por: localStorage.

Assinatura da consulta: queryPermission('access_local_storage', 'read', <key to read from>), queryPermission('access_local_storage', 'write', <key to write to>) ou queryPermission('access_local_storage', 'readwrite', <key to read and write>).

Exemplo de código

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

Nome de exibição: acessa o armazenamento de modelos.

Descrição: permite acesso ao armazenamento temporário de modelos que podem persistir durante a vida útil da página.

Configuração: nenhuma

Solicitado por: templateStorage.

Assinatura da consulta: queryPermission('access_template_storage').

Exemplo de código

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

get_cookies

Nome de exibição: Reads cookie value(s)

Descrição: lê os valores dos cookies com os nomes especificados.

Configuração: lista de nomes dos cookies permitidos para leitura.

Solicitado por: getCookieValues.

Assinatura da consulta: queryPermission('get_cookies', <name>).

Observações: determina se um cookie pode ser lido, dependendo do nome.

Exemplo de código

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

get_referrer

Nome de exibição: lê o URL do referenciador.

Descrição: concede acesso de leitura a partes restritas do referenciador.

Configuração: os booleanos a seguir determinam qual parte do referenciador pode ser lida. Certos fragmentos dele só permitirão a leitura se a parte correspondente for true. O autor poderá chamar getReferrerUrl sem especificar um componente para receber o URL completo do referenciador se todos os booleanos forem definidos como true. Se nenhum valor for definido, o padrão será all. Se for definido, o valor precisará ser uma matriz de componentes em que um deles seja protocol, host, port, path, query ou extension.

queryKeys: se a consulta for selecionada, o autor do modelo poderá limitar ainda mais o conjunto de chaves de consulta em que é possível realizar a leitura. Essa é uma matriz simples de chaves que não contém caracteres curinga.

Solicitado por: getReferrerUrl, getReferrerQueryParameters.

Assinatura da consulta: queryPermission('get_referrer', <url_component>).

Exemplo de código

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

get_url

Nome de exibição: Reads URL

Descrição: retorna o URL parcial ou completo da página atual.

Configuração: os seguintes booleanos determinam qual parte do URL pode ser lida. Uma parte específica do URL só poderá ser lida se a parte correspondente for verdadeira. O autor só poderá chamar getUrl sem um componente especificado para receber o URL completo se todos esses booleanos estiverem configurados como true. Se nenhum valor for definido, o padrão será all. Se for definido, o valor precisará ser uma matriz de componentes em que um deles seja protocol, host, port, path, query, extension ou fragment.

queryKeys: se a consulta for selecionada, o autor do modelo poderá limitar ainda mais o conjunto de chaves de consulta em que é possível realizar a leitura. Essa é uma matriz simples de chaves que não contém caracteres curinga.

Solicitado por: getUrl.

Assinatura da consulta: queryPermission('get_url', <optional url component>, <optional query key>).

Se fornecido, o componente de URL deverá ser uma destas opções: 'protocol', 'host', 'port', 'path', 'query', 'extension' ou 'fragment'. Se ele for omitido, a consulta de permissão será uma solicitação de acesso ao URL inteiro.

Se fornecida, a chave de consulta deverá ser o argumento de string de consulta que será lido pelo código do modelo.

Observações: define se um modelo personalizado pode fazer a leitura no local atual. Permite restringir a uma parte específica do local.

Exemplo de código

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

inject_hidden_iframe

Nome de exibição: injeta iframes ocultos.

Descrição: injeta um iframe invisível com um URL especificado.

Configuração: lista de padrões do URL.

Solicitado por: injectHiddenIframe.

Assinatura da consulta: queryPermission('inject_hidden_iframe', <url>).

Observações: define se um modelo personalizado pode injetar um iFrame invisível e em qual origem é possível fazer isso.

Exemplo de código

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

Nome de exibição: injeta scripts.

Descrição: insere um script na página.

Configuração: lista de padrões do URL.

Solicitado por: injectScript.

Assinatura da consulta: queryPermission('inject_script', <url>).

Observações: define se um modelo personalizado pode injetar JavaScript e em qual origem é possível fazer isso.

Exemplo de código

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

logging

Nome de exibição: registra no console.

Descrição: faz registros no console para desenvolvedores e no modo de visualização do GTM.

Configuração: opção para ativar registros em produção. O padrão é ativar os registros apenas na depuração/visualização. Quando a permissão é negada, logToConsole não gera um erro, mas suprime a mensagem de registro.

Solicitado por: logToConsole.

Assinatura da consulta: queryPermission('logging').

Observações: define se um modelo personalizado pode fazer registros no console do desenvolvedor.

Exemplo de código

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

Nome de exibição: lê a camada de dados.

Descrição: lê dados do objeto dataLayer.

Configuração: conjunto de expressões de correspondência de chave em que uma correspondência pode ser uma série principal de referências pontilhadas, com um caractere curinga à direita; essas expressões definem quais propriedades podem ser lidas na camada de dados

Solicitado por: copyFromDataLayer

Assinatura da consulta: queryPermission('read_data_layer', <data layer key to read from>).

Observações: define se um modelo personalizado pode ler a camada de dados.

Exemplo de código

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

Nome de exibição: lê o conjunto de caracteres do documento.

Descrição: lê document.characterSet.

Configuração: nenhuma

Solicitado por: readCharacterSet.

Assinatura da consulta: queryPermission('read_character_set').

Observações: controla se um modelo personalizado pode ler o document.characterSet.

Exemplo de código

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

read_container_data

Nome de exibição: lê dados do contêiner.

Descrição: lê dados sobre o contêiner.

Configuração: nenhuma

Solicitado por: getContainerVersion.

Assinatura da consulta: queryPermission('read_container_data').

Observações: controla se um modelo personalizado pode ler dados sobre o contêiner.

Exemplo de código

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

read_event_metadata

Nome de exibição: lê metadados de evento.

Descrição: lê metadados de evento em callbacks de evento.

Configuração: nenhuma

Solicitado por: addEventCallback.

Assinatura da consulta: queryPermission('read_event_metadata').

Observações: controla se um modelo personalizado pode ler metadados de evento em callbacks.

Exemplo de código

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

read_title

Nome de exibição: lê o título do documento.

Descrição: lê document.title.

Configuração: nenhuma

Solicitado por: readTitle.

Assinatura da consulta: queryPermission('read_title').

Observações: controla se um modelo personalizado pode ler o document.title.

Exemplo de código

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

send_pixel

Nome de exibição: envia pixels.

Descrição:envia uma solicitação GET a um URL especificado. A resposta não é processada.

Configuração: lista de padrões do URL permitidos.

Solicitado por: sendPixel.

Assinatura da consulta: queryPermission('send_pixel', <url>).

Observações: define se um modelo personalizado pode enviar uma solicitação GET e para qual origem ele pode fazer isso.

Exemplo de código

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

Nome de exibição: Sets a cookie

Descrição: define um cookie com o nome e os parâmetros especificados.

Configuração: tabela com os nomes dos cookies permitidos, cada um com restrições opcionais de nome, domínio, caminho, atributo secure e validade.

Solicitado por: setCookie.

Assinatura da consulta: queryPermission('set_cookies', <name>, <options>).

Observações: determina se um cookie pode ser gravado, dependendo do nome, domínio, caminho, atributo secure e validade dele.

Exemplo de código

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

Nome de exibição: faz gravações na camada de dados.

Descrição: grava dados na camada de dados.

Configuração: conjunto de expressões de correspondência de chave em que uma correspondência pode ser uma série principal de referências pontilhadas, com um caractere curinga à direita. Expressões de correspondência de chave definem quais propriedades podem fazer gravações na camada de dados.

Solicitado por: gtagSet

Assinatura da consulta: queryPermission('write_data_layer', <data layer key to write from>)

Observações: controla se um modelo personalizado pode fazer gravações na camada de dados.

Exemplo de código

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