自定义模板权限

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

  • 由需要相应权限的 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 query = require('queryPermission');
const createQueue = require('createQueue');
if (query('access_globals', 'readwrite', 'dataLayer')) {
  const dataLayerPush = createQueue('dataLayer');
}

get_cookies

显示名:Reads cookie value(s)

说明:读取具有指定名称的 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 query = require('queryPermission');
const getUrl = require('getUrl');
if (query('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 query = require('queryPermission');
const iframe = require('injectHiddenIframe');
const url = 'https://www.example.com/iframes';
if (query('inject_hidden_iframe', url)) {
  iframe(url);
}

inject_script

显示名:Injects Scripts

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

配置:网址格式列表

所需者injectScript

查询签名queryPermission('inject_script', <url>)

备注:控制自定义模板是否可以注入 JavaScript,以及可以从哪个来源注入。

示例代码

const query = require('queryPermission');
const injectScript = require('injectScript');
const url = 'https://www.example.com?api.js';
if (query('inject_script', url)) {
  injectScript(url);
}

logging

显示名:Logs to Console

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

配置:用于在生产环境中启用日志记录的选项。默认为仅在调试/预览模式下启用日志记录。所需者:由 logToConsole 使用。如果权限遭拒,则 logToConsole 将不执行操作,而不是引发错误。

所需者logToConsole

查询签名queryPermission('logging')

备注:控制自定义模板是否可以将日志记录到开发者控制台。

示例代码

const query = require('queryPermission');
const log = 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.
log('diagnostic info');

read_data_layer

显示名:Reads Data Layer

说明:从 dataLayer 读取数据。

配置:键匹配表达式集,其中键匹配的开头部分可以是虚线形式的引用,末尾部分可以是通配符。键匹配表达式控制可以从数据层读取哪些属性。

所需者copyFromDataLayer

查询签名queryPermission('read_data_layer', <data layer key to read from>)

备注:控制自定义模板是否可以从数据层读取数据。

示例代码

const query = require('queryPermission');
const dlKey = 'foo.bar';
const copyDL = require('copyFromDataLayer');
if (query('read_data_layer', dlKey)) {
  const dlContents = copyDL(dlKey);
}

read_character_set

显示名:Reads Document Character Set

说明:读取 document.characterSet

配置:无

所需者readCharacterSet

查询签名queryPermission('read_character_set')

备注:控制自定义模板是否可以读取 document.characterSet。

示例代码

const query = require('queryPermission');
const readCharacterSet = require('readCharacterSet');
if (query('read_character_set')) {
  const characterSet = readCharacterSet();
}

read_event_metadata

显示名:Reads Event Metadata

说明:读取事件回调函数中的事件元数据

配置:无

所需者addEventCallback

查询签名queryPermission('read_event_metadata')

备注:控制自定义模板是否可以读取回调函数中的事件元数据。

示例代码

const query = require('queryPermission');
const addEventCallback = require('read_event_metadata);
if (query('read_event_metadata)) {
  addEventCallback((ctid, eventData) => {
    // Read eventData.
  });
}

read_title

显示名:Reads Document Title

说明:读取 document.title

配置:无

所需者readTitle

查询签名queryPermission('read_title')

备注:控制自定义模板是否可以读取 document.title

示例代码

const query = require('queryPermission');
const readTitle = require('readTitle');
if (query('read_title')) {
  const title = readTitle();
}

send_pixel

显示名:Sends Pixels

说明:向指定网址发送 GET 请求。系统不处理响应。

配置:网址格式白名单列表。

所需者sendPixel

查询签名queryPermission('send_pixel', <url>)

备注:控制自定义模板是否可以发送 GET 请求,以及可以向哪个来源发送。

示例代码

const query = require('queryPermission');
const sendPixel = require('sendPixel');
const url = 'https://www.example.com?foo=3';
if (query('send_pixel', url)) {
  sendPixel(url);
}

set_cookies

显示名:Sets a cookie

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

所需者setCookie

查询签名queryPermission('set_cookies', <name>, <options>)

备注:根据 Cookie 的名称、域名、路径、安全标志和到期参数控制是否可以写入相应 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);
}