自定义模板权限

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


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

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

access_globals

显示名:Accesses global variables

说明:允许访问全局变量(可能包括敏感 API)。

配置:可访问的键的列表。每个键都是一条以英文句点分隔的路径,例如:foo.bar。在每条路径中,第一个词元不能是浏览器全局范围内的预定义键,也不能是 JavaScript 关键字。带有用于控制访问权限的读取、写入和执行复选框。

所需者setInWindowcopyFromWindowcallInWindowcreateQueuecreateArgumentsQueue

查询签名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;否则,必须设置为组成部分的数组,且组成部分应是以下各项之一:protocolhostportpathqueryextension

queryKeys:如果选择的是查询,则模板作者可以进一步限制可供读取的查询键。这是简单的键数组,无通配符。

所需者getReferrerUrlgetReferrerQueryParameters

查询签名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;否则,必须设置为组成部分的数组,且组成部分应是以下各项之一:protocolhostportpathqueryextensionfragment

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