本文概述網路自訂範本的權限。
每個權限皆為:
- 由需要這類 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
:如果選取查詢,範本作者可能會進一步限制可讀取的查詢索引鍵組合。此為不含萬用字元的簡易索引鍵陣列。
必填屬性: 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
:如果選取查詢,範本作者可能會進一步限制可讀取的查詢索引鍵組合。此為不含萬用字元的簡易索引鍵陣列。
必填資料欄: 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'});
}