自訂範本權限

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

---

每個權限皆具有以下特性：

• 由需要這些 API 的 API 檢查。
• 根據 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。呼叫端無需指定元件，即可呼叫 getReferrerUrl 如果所有這些布林值都設為 true，則會取得完整的參照網址。如果沒有數值 已設定，預設值為 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。呼叫端可在未指定元件的情況下呼叫 getUrl 來取得 整個網址 (僅限這些布林值都設為 true 時)。如果沒有 則預設值為 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);
}

logging

顯示名稱：前往主控台

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

顯示名稱：讀取資料層

說明：從 dataLayer 讀取資料。

設定：一組鍵比對運算式，其中比對鍵符合 以萬用字元結尾，接續一系列的虛線參照。網址比對 運算式管理可從資料層讀取哪些屬性。

要求原因： 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 是否可寫入 Cookie 名稱、網域、路徑、secure 屬性和有效期限。

範例程式碼

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

顯示名稱：寫入資料層

說明：將資料寫入 dataLayer。

設定：一組鍵比對運算式，其中比對鍵符合 以萬用字元結尾，接續一系列的虛線參照。網址比對 運算式會控管哪些屬性可寫入資料層。

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