Uprawnienia dotyczące szablonów niestandardowych

W tym dokumencie opisujemy uprawnienia do niestandardowych szablonów internetowych.

Każde uprawnienie:

  • Sprawdzane przez interfejsy API, które ich wymagają.
  • Wykrywane automatycznie w piaskownicy JavaScript na podstawie tego, które interfejsy API są używane. Dzieje się tak, gdy wprowadzasz zmiany w edytorze niestandardowego szablonu (aby szybko uzyskać informacje zwrotne) i gdy kompilujesz kod (aby sprawdzić, czy są stosowane odpowiednie uprawnienia).
  • Można je edytować w edytorze szablonów niestandardowych, aby dostosować uprawnienia.
  • Dostępny w sandboxowanym środowisku JavaScript za pomocą interfejsu queryPermission API.

access_globals

Nazwa wyświetlana: uzyskuje dostęp do zmiennych globalnych.

Opis: umożliwia dostęp do zmiennej globalnej (w tym do interfejsów API o wrażliwych danych).

Konfiguracja: lista kluczy, do których można uzyskać dostęp. Każdy klucz to ścieżka rozdzielona kropkami. Na przykład: foo.bar pierwszy element ścieżki nie może być zdefiniowanym wstępnie kluczem w zakresie globalnym przeglądarki ani słowem kluczowym JavaScriptu. Zawiera pola wyboru odczytu, zapisu i wykonywania, które określają dostęp.

Wymagane przez: setInWindow, copyFromWindow, callInWindow, createQueue, createArgumentsQueue

Podpis zapytania: 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>) lub queryPermission('access_globals', 'execute', <key of function to execute>)

Uwagi: określa, czy szablon niestandardowy może odczytywać lub zapisywać wartości globalne.

Przykładowy kod

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

access_local_storage

Wyświetlana nazwa: dostęp do pamięci lokalnej.

Opis: umożliwia dostęp do określonych kluczy w pamięci lokalnej.

Konfiguracja: lista kluczy pamięci lokalnej, do których można uzyskać dostęp. To jest prosty tablicowy klucz bez symboli wieloznacznych. Zawiera pola wyboru odczytu i zapisu, które regulują dostęp.

Wymagane przez: localStorage

Podpis zapytania: queryPermission('access_local_storage', 'read', <key to read from>), queryPermission('access_local_storage', 'write', <key to write to>) lub queryPermission('access_local_storage', 'readwrite', <key to read and write>)

Przykładowy kod

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

Wyświetlana nazwa: dostęp do pamięci szablonów.

Opis: umożliwia dostęp do tymczasowej pamięci dla szablonów, które mogą przetrwać przez cały czas istnienia strony.

Konfiguracja: brak.

Wymagane przez: templateStorage

Podpis zapytania: queryPermission('access_template_storage')

Przykładowy kod

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

get_cookies

Wyświetlana nazwa: odczytuje wartości plików cookie.

Opis: odczytuje wartości plików cookie o określonej nazwie.

Konfiguracja: lista nazw plików cookie dozwolonych do odczytu.

Wymagane przez: getCookieValues

Podpis zapytania: queryPermission('get_cookies', <name>)

Uwagi: określa, czy plik cookie może być odczytywany, w zależności od jego nazwy.

Przykładowy kod

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

get_referrer

Wyświetlana nazwa: odczytuje adres URL strony odsyłającej.

Opis: umożliwia odczyt ograniczonych części danych o odesłańcu.

Konfiguracja: te wartości logiczne określają, która część wartości odesłania może być odczytana. Określony fragment danych o odesłaniu można odczytać tylko wtedy, gdy odpowiadający mu fragment to true. Jeśli wszystkie te parametry są ustawione na wartość true, wywołujący może wywołać funkcję getReferrerUrl bez podawania komponentu, aby uzyskać pełny adres URL witryny odsyłającej. Jeśli nie ustawisz żadnej wartości, domyślną wartością będzie all. Jeśli wartość jest ustawiona, musi być tablicą komponentów, z których każdy może być jednym z tych typów: protocol, host, port, path, query lub extension.

queryKeys: jeśli wybrana jest opcja zapytanie, autor szablonu może dodatkowo ograniczyć zestaw kluczy zapytań, z których może odczytywać dane. Jest to prosty tablicowy zbiór kluczy bez symboli wieloznacznych.

Wymagane przez: getReferrerUrl, getReferrerQueryParameters

Podpis zapytania: queryPermission('get_referrer', <url_component>)

Przykładowy kod

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

get_url

Wyświetlana nazwa: odczytuje adres URL.

Opis: zwraca cały adres URL bieżącej strony lub jego część.

Konfiguracja: te wartości logiczne określają, która część adresu URL może być odczytana. Podany fragment adresu URL może być odczytany tylko wtedy, gdy odpowiadający mu fragment jest ustawiony na wartość true. Rozmówca może wywołać getUrl bez podania składnika, aby uzyskać cały adres URL, tylko wtedy, gdy wszystkie te wartości logiczne są ustawione na true. Jeśli nie podasz żadnej wartości, domyślną wartością będzie all. Jeśli wartość jest ustawiona, musi być tablicą komponentów, z których każdy jest jedną z tych wartości: protocol, host, port, path, query, extension lub fragment.

queryKeys: jeśli wybrana jest opcja zapytanie, autor szablonu może dodatkowo ograniczyć zestaw kluczy zapytań, z których może odczytywać dane. Jest to prosty tablicowy zbiór kluczy bez symboli wieloznacznych.

Wymagane przez: getUrl

Podpis zapytania: queryPermission('get_url', <optional url component>, <optional query key>)

Jeśli jest podany, komponent URL powinien być jednym z tych: 'protocol', 'host', 'port', 'path', 'query', 'extension', 'fragment'. Jeśli nie zostanie pominięty, zapytanie o dostęp będzie oznaczać prośbę o dostęp do całego adresu URL.

Jeśli klucz zapytania zostanie podany, powinien być to ciąg zapytania, który kod szablonu ma odczytać.

Uwagi: określa, czy szablon niestandardowy może odczytywać dane z bieżącej lokalizacji. Umożliwia ograniczenie do określonej części lokalizacji.

Przykładowy kod

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

inject_hidden_iframe

Wyświetlana nazwa: wstrzykiwanie ukrytych elementów iframe

Opis: wstawia niewidoczny element iframe z określonym adresem URL.

Konfiguracja: lista wzorców adresów URL

Wymagane przez: injectHiddenIframe

Podpis zapytania: queryPermission('inject_hidden_iframe', <url>)

Uwagi: określa, czy szablon niestandardowy może wstrzyknąć niewidoczny element iframe i z jakiego źródła może to zrobić.

Przykładowy kod

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

Nazwa wyświetlana: wstrzykiwanie skryptów

Opis: umieszczanie skryptu na stronie.

Konfiguracja: lista wzorców adresów URL

Wymagane przez: injectScript

Podpis zapytania: queryPermission('inject_script', <url>)

Uwagi: określa, czy szablon niestandardowy może wstrzyknąć kod JavaScript i z jakiego źródła może to robić.

Przykładowy kod

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

logowanie

Wyświetlana nazwa: logowanie do konsoli.

Opis: logowanie do konsoli programisty i trybu podglądu Menedżera tagów.

Konfiguracja: opcja włączenia logowania w wersji produkcyjnej. Domyślnie rejestrowanie jest włączone tylko podczas debugowania i podglądu. Jeśli dostęp zostanie odrzucony, funkcja logToConsole nie wyrzuci błędu, ale nie wyświetli komunikatu w dzienniku.

Wymagane przez: logToConsole

Podpis zapytania: queryPermission('logging')

Uwagi: określa, czy szablon niestandardowy może rejestrować się w konsoli deweloperów.

Przykładowy kod

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

Nazwa wyświetlana:odczytuje warstwę danych.

Opis: odczytuje dane z obiektu dataLayer.

Konfiguracja: zestaw wyrażeń dopasowania klucza, gdzie dopasowanie klucza może być wiodącą serią odwołań z kropką i końcowym symbolem wieloznacznym. Wyrażenia dopasowania klucza określają, które właściwości mogą być odczytywane z warstwy danych.

Wymagane przez: copyFromDataLayer

Podpis zapytania: queryPermission('read_data_layer', <data layer key to read from>)

Uwagi: określa, czy szablon niestandardowy może odczytywać dane z warstwy danych.

Przykładowy kod

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

Wyświetlana nazwa: odczytuje zestaw znaków dokumentu.

Opis: czyta document.characterSet.

Konfiguracja: brak.

Wymagane przez: readCharacterSet

Podpis zapytania: queryPermission('read_character_set')

Uwagi: określa, czy szablon niestandardowy może odczytywać document.characterSet.

Przykładowy kod

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

read_container_data

Wyświetlana nazwa: odczytuje dane kontenera.

Opis: odczytuje dane o kontenerze.

Konfiguracja: brak.

Wymagane przez: getContainerVersion

Podpis zapytania: queryPermission('read_container_data')

Uwagi: określa, czy szablon niestandardowy może odczytywać dane o kontenerze.

Przykładowy kod

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

read_event_metadata

Nazwa wyświetlana: odczytuje metadane zdarzenia.

Opis: odczytuje metadanych zdarzenia w wywołaniach zwrotnych zdarzenia

Konfiguracja: brak.

Wymagane przez: addEventCallback

Podpis zapytania: queryPermission('read_event_metadata')

Uwagi: określa, czy szablon niestandardowy może odczytywać metadane zdarzenia w wywołaniach zwrotnych.

Przykładowy kod

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

read_title

Wyświetlana nazwa: odczytuje tytuł dokumentu.

Opis: czyta document.title.

Konfiguracja: brak.

Wymagane przez: readTitle

Podpis zapytania: queryPermission('read_title')

Uwagi: określają, czy szablon niestandardowy może odczytywać document.title.

Przykładowy kod

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

send_pixel

Wyświetlana nazwa: wysyła piksele

Opis: wysyła żądanie GET do określonego adresu URL. Odpowiedź nie została przetworzona.

Konfiguracja: lista dozwolonych wzorców adresów URL.

Wymagane przez: sendPixel

Podpis zapytania: queryPermission('send_pixel', <url>)

Uwagi: określają, czy szablon niestandardowy może wysyłać żądanie GET i do jakiego źródła.

Przykładowy kod

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

Wyświetlana nazwa: ustawia plik cookie.

Opis: ustawia plik cookie z określonymi nazwą i parametrami.

Konfiguracja: tabela z dozwolonymi nazwami plików cookie, z opcjonalnymi ograniczeniami dotyczącymi nazwy, domeny, ścieżki, atrybutu secure i terminu ważności.

Wymagane przez: setCookie

Podpis zapytania: queryPermission('set_cookies', <name>, <options>)

Uwagi: określa, czy plik cookie może zostać zapisany, w zależności od jego nazwy, domeny, ścieżki, atrybutu secure i terminu ważności.

Przykładowy kod

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

Nazwa wyświetlana: zapisuje warstwę danych.

Opis: zapisuje dane w atrybucie dataLayer.

Konfiguracja: zestaw wyrażeń dopasowania klucza, gdzie dopasowanie klucza może być wiodącą serią odwołań z kropką i końcowym symbolem wieloznacznym. Wyrażenia dopasowania klucza określają, które właściwości mogą zapisywać dane w warstwie danych.

Wymagane przez: gtagSet

Podpis zapytania: queryPermission('write_data_layer', <data layer key to write from>)

Uwagi: określa, czy szablon niestandardowy może zapisywać dane na warstwie danych.

Przykładowy kod

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