本頁面由 Cloud Translation 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 時，才能讀取參照網址的特定部分。如果所有布林值都設為 true，呼叫端可以呼叫 getReferrerUrl，而不指定元件，藉此取得完整的參照網址。如未設定值，預設值為 all。如果已設定值，該值必須是元件陣列，而元件是下列其中一項：protocol、host、port、path、query 或 extension。

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

顯示名稱：Reads URL

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

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

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')

注意：控制自訂範本是否可記錄至開發人員控制台。

程式碼範例

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_analytics_storage

顯示名稱：讀取 Analytics 儲存空間

說明：範本可藉此讀取儲存的 Analytics 資料，例如 Client-ID。

設定：無

必要條件： readAnalyticsStorage

查詢簽章： queryPermission('read_analytics_storage')

注意：控管自訂範本是否可從 Analytics 儲存空間讀取資料。

程式碼範例

const queryPermission = require('queryPermission');
const readAnalyticsStorage = require('readAnalyticsStorage');
if (queryPermission('read_analytics_storage')) {
  const value = readAnalyticsStorage();
}

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

自訂範本權限 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

access_globals

access_local_storage

access_template_storage

get_cookies

get_referrer

get_url

inject_hidden_iframe

inject_script

記錄

read_data_layer

read_analytics_storage

read_character_set

read_container_data

read_event_metadata

read_title

send_pixel

set_cookies

write_data_layer

自訂範本權限