自訂範本權限

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

---

每個權限皆為：

• 由需要這類 API 的 API 進行檢查。
• 在沙箱機制的 JavaScript 中自動偵測，視使用的 API 而定。這是因為在自訂範本編輯器中進行編輯 (可快速提供意見回饋循環)，以及編譯程式碼 (驗證是否強制執行正確權限) 時，就會發生這種情況。
• 可透過自訂範本編輯器編輯，以設定更精確的權限。
• 可透過 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 時，Google 才能讀取網址的指定部分。只有在所有布林值都設為 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，以及從哪些來源插入 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')

注意：控制是否允許自訂範本記錄到 Play 管理中心。

範例程式碼

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 名稱、網域、路徑、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

顯示名稱：寫入資料層

說明：將資料寫入 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'});
}