自定义模板权限

本文档简要介绍了网站自定义模板的权限。

---

每项权限均具有以下特点：

• 由需要相应权限的 API 进行检查。
• 由系统根据所使用的 API 在沙盒化 JavaScript 中自动检测。当您在自定义模板编辑器中进行修改时，为了实现快速反馈环，系统会执行此项自动检测；当编译代码时，为了验证是否强制执行了正确权限，系统也会这么做。
• 可在自定义模板编辑器中修改，让权限更为具体。
• 可通过 queryPermission API 在沙盒化 JavaScript 中查询。

access_globals

显示名：Accesses global variables

说明：允许访问全局变量（可能包括敏感 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

显示名：Accesses 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

显示名：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

显示名：Reads cookie value(s)

说明：读取具有指定名称的 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

显示名：Reads referrer URL

说明：授予对引荐来源网址中某些部分的读取访问权限。

配置：以下布尔值控制可以读取引荐来源网址的哪个部分。只有当引荐来源网址的给定部分为 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

显示名：Reads 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

显示名：Injects hidden iframes

说明：利用给定网址注入不可见 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

显示名：Injects scripts

说明：将脚本注入到网页中。

配置：网址格式列表

所需者：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);
}

日志记录

显示名：Logs to console

说明：将日志记录到开发者控制台和 GTM 的预览模式。

配置：用于在生产环境中启用日志记录的选项。默认为仅在调试/预览模式下启用日志记录。如果权限遭拒，则 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

显示名：Reads 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

显示名：Reads document 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

显示名：Reads 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

显示名：Reads 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

显示名：Reads document 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

显示名：Sends pixels

说明：向指定网址发送 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

显示名：Sets a cookie

说明：设置具有指定名称和参数的 Cookie。

配置：一个包含允许的 Cookie 名称的表，您可以根据需要在名称、网域、路径、secure 属性和有效期方面对每个 Cookie 施加限制。

所需者：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

显示名称：Writes 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'});
}