Uprawnienia dotyczące szablonów niestandardowych

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

Każde uprawnienie:

  • Sprawdzone 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 podczas wprowadzania zmian w edytorze szablonów niestandardowych (aby zapewnić szybką pętlę informacji zwrotnych) oraz podczas skompilowania kodu (w celu sprawdzenia, czy egzekwowane są właściwe 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. Ma pola wyboru do odczytu, zapisu i wykonywania, które zarządzają dostępem.

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ć i/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 prosta tablica kluczy 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ślona część adresu docelowego może być odczytana tylko wtedy, gdy odpowiadająca jej część jest 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 odesłania. Jeśli nie ustawisz żadnej wartości, domyślną wartością będzie all. Jeśli jest ustawiona wartość, musi ona być tablicą komponentów, których komponent jest jednym z tych elementó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 część lub całość adresu URL bieżącej strony.

Konfiguracja: te wartości logiczne określają, która część adresu URL może być odczytana. Daną część adresu URL można odczytać tylko wtedy, gdy odpowiadająca jej część ma wartość prawda. 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 wstrzykiwać niewidoczny element iframe i z jakiego źródła może to robić.

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

Wyświetlana nazwa: powoduje 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 wstrzykiwać 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 włączone jest tylko rejestrowanie podczas debugowania lub wyświetlania 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

Wyświetlana nazwa: 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: czytanie 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 zdarzeń 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.

Wymagany przez: sendPixel

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

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

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 o określonej nazwie i parametrach.

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

Wyświetlana nazwa: 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 kropkami, na końcu których znajduje się symbol wieloznaczny. Wyrażenia dopasowania klucza określają, które właściwości mogą zapisywać dane w warstwie danych.

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