自訂範本權限

本文件概述網頁自訂範本的權限。

---

每項權限如下：

• 由需要這些值的 API 檢查。
• 根據所使用的 API，在沙箱 JavaScript 中自動偵測。這會發生在自訂範本編輯器中進行編輯 (快速回饋循環) 以及編譯程式碼時 (驗證是否強制執行正確的權限)。
• 可在自訂範本編輯器中編輯，讓權限更加明確。
• 透過 queryPermission API 在沙箱 JavaScript 中進行查詢。

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 名稱控管 Cookie 是否可供讀取。

程式碼範例

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

get_referrer

顯示名稱：讀取參照網址

說明：允許對參照網址較小的部分讀取權限。

設定：下列布林值管理可讀取參照網址的哪些部分。只有在對應的部分為 true 時，系統才能讀取參照網址的指定部分。如果所有布林值都設為 true，呼叫端可以不指定組件，直接呼叫 getReferrerUrl 來取得完整的引介網址。如未設定值，則採用預設值 all。如果已設定值，則該值必須是元件陣列，其中元件為下列其中一個：protocol、host、port、path、query 或 extension。

queryKeys：如果選取查詢，範本作者可能會進一步限制可以讀取的查詢索引鍵組合。這是一組簡單的鍵陣列，不含萬用字元。

注意： 由於採用 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

顯示名稱：讀取網址

說明：傳回目前網頁的部分或完整網址。

設定：下列布林值管理可讀取網址的哪些部分。只有在對應部分為 true 時，才能讀取網址的特定部分。只有在所有布林值都設為 true 的情況下，呼叫端可以在未指定元件的情況下呼叫 getUrl，取得完整的網址。如未設定任何值，預設值為 all。如果已設定值，則該值必須是元件的陣列，其中元件為下列其中一個：protocol、host、port、path、query、extension 或 fragment。

queryKeys：如果選取查詢，範本作者可以進一步限制可讀取的查詢鍵組合。這是不含萬用字元的簡單鍵陣列。

注意： 由於採用 queryKeys 的功能仍在開發中，因此理想的設定是允許任何查詢鍵。

依下列項目規定為必填： getUrl

查詢簽章： queryPermission('get_url', <optional url component>, <optional query key>)

如果提供此值，網址元件應為 'protocol'、'host'、'port'、'path'、'query'、'extension'、'fragment' 之一。如果省略，權限查詢就是要求存取整個網址。

如果提供查詢鍵，則應為範本程式碼要讀取的查詢字串引數。

附註：控制自訂範本是否可從目前位置讀取。可限制到特定位置的某個部分。

程式碼範例

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。

設定：網址模式清單

依下列項目規定為必填： 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

顯示名稱：插入指令碼

說明：將指令碼插入網頁。

設定：網址模式清單

要求原因： 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);
}

記錄

顯示名稱：記錄到控制台

說明：記錄到開發人員控制台和 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

顯示名稱：讀取資料層

說明：從資料層讀取資料。

設定：一組鍵比對運算式，其中鍵比對可為開頭的一系列點字參照，並附帶結尾的萬用字元。鍵匹配運算式會決定可從資料層讀取哪些資源。

要求原因： 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 要求。系統未處理回應。

設定：允許的網址模式清單。

要求原因： 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 屬性和到期日，控管 Cookie 是否可寫入。

範例程式碼

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

顯示名稱：寫入資料層

說明：將資料寫入資料層。

設定：一組鍵比對運算式，其中鍵比對可為開頭的一系列點狀參照，並附帶結尾的萬用字元。鍵比對運算式會控管哪些屬性可以寫入資料層。

要求原因： gtagSet

查詢簽章： queryPermission('write_data_layer', <data layer key to write from>)

附註：控制自訂範本是否可寫入資料層。

程式碼範例

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