自定义模板 API

核心 API

本文中介绍的 API 可以采用沙盒化 JavaScript 在 Google 跟踪代码管理器中创建自定义模板。每个 API 都可以通过 require() 语句添加，例如：

const myAPI = require('myAPI');

addConsentListener

注册在指定的用户意见征求类型的状态发生变化时执行的监听器函数。

每当指定的用户意见征求类型的状态从“denied”变为“granted”或从“granted”变为“denied”时，系统都会调用指定监听器。对于状态未设置的用户意见征求类型，系统会将其状态视为“granted”，因此当用户意见征求类型从未设置更新为“granted”时，系统不会调用监听器。监听器函数将负责确保其代码运行适当次数。

示例：

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

语法

addConsentListener(consentType, listener)

参数

参数 类型 说明
consentType 字符串 要监听状态变化的用户意见征求类型。
listener 函数 要在指定的用户意见征求类型的状态发生变化时运行的函数。

调用监听器时，系统会向其传递发生变化的用户意见征求类型以及该类型的新值：

参数 类型 说明
consentType 字符串 发生变化的用户意见征求类型。
granted 布尔值 一个布尔值，如果指定的用户意见征求类型会变为“granted”，则该布尔值为 true。

相关权限

access_consent 权限，其中包含对用户意见征求类型的读取权限。

addEventCallback

addEventCallback API 用于注册要在事件结束时调用的回调函数。如果该事件的所有代码都已执行完毕，或者页内事件已超时，系统就会调用回调函数。系统会向该回调函数传递两个值：调用该函数的容器的 ID 和包含事件相关信息的对象。

语法

addEventCallback(callback)

参数

参数 类型 说明
callback 函数 在事件结束时要调用的函数。

eventData 对象包含以下数据：

键名 类型 说明
tags 数组 一个由代码数据对象组成的数组。在事件期间触发的每个代码在此数组中都有一个对应的条目。代码数据对象包含代码 ID (id)、代码的执行状态 (status) 和执行时间 (executionTime)。代码数据还包含基于代码配置的其他代码元数据。

示例

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

相关权限

read_event_metadata

aliasInWindow

aliasInWindow API 用于创建别名（例如 window.foo = window.bar），这有助于支持某些需要别名处理的代码。它会将 window 对象中位于 fromPath 路径的值分配给 window 对象中位于 toPath 路径的键。如果成功，则返回 true；否则，返回 false。

语法

aliasInWindow(toPath, fromPath)

参数

参数 类型 说明
toPath 字符串 各部分以英文句点分隔的路径，表示应将值复制到 window 对象中的哪个位置。在该路径中，最后一个组成部分之前的所有组成部分均必须已存在于 window 对象中。
fromPath 字符串 各部分以英文句点分隔的路径，表示要将值复制到 window 对象中的哪个位置。如果值不存在，则操作将失败。

示例

aliasInWindow('foo.bar', 'baz.qux')

相关权限

toPath 和 fromPath 均需要有 access_globals 权限；toPath 需要有写入权限，fromPath 需要有读取权限。

callInWindow

用于以受政策控制的方式调用 window 对象中位于某个路径的函数。它以指定的参数调用 window 中位于指定路径的函数，并返回相应值。如果返回值类型无法直接映射到沙盒化 JavaScript 所支持的类型，则返回 undefined。沙盒化 JavaScript 支持以下八种类型：null、undefined、boolean、number、string、Array、Object 和 function。如果指定的路径不存在，或者未引用函数，则返回 undefined。

语法

callInWindow(pathToFunction, argument [, argument2,... argumentN])

参数

参数 类型 说明
pathToFunction 字符串 各部分以英文句点分隔的路径，表示要调用 window 中什么位置的函数。
args * 要传递给该函数的参数。

相关权限

access_globals（需启用 execute 权限）。

callLater

安排函数调用以异步方式进行。相应函数将在当前代码返回后调用。等效于 setTimeout(<function>, 0)。

语法

callLater(function)

参数

参数 类型 说明
function 函数 要调用的函数。

copyFromDataLayer

返回数据层中当前分配给指定键的值：如果指定键的值是基本类型、函数或对象字面量，则返回该值；否则，返回 undefined。

语法

copyFromDataLayer(key[, dataLayerVersion])

参数

参数 类型 说明
key 字符串 键，需采用“a.b.c”格式。
dataLayerVersion 数值 数据层版本，此参数可选。默认值为 2。强烈建议不要使用值 1。

相关权限

read_data_layer

copyFromWindow

从 window 对象中复制变量。如果 window 中的值无法直接映射到沙盒化 JavaScript 所支持的类型，则返回 undefined。沙盒化 JavaScript 支持以下八种类型：null、undefined、boolean、number、string、Array、Object 和 function。返回提取（并强制转换后）的值。

语法

copyFromWindow(key)

参数

参数 类型 说明
key 字符串 window 中的键，要复制的就是这个键的值。

相关权限

access_globals

createArgumentsQueue

创建一个由参数对象填充的队列，以支持需要使用它的代码解决方案。

它首先会使用 fnKey 参数在全局范围内（即 window 中）创建一个函数（与 createQueue 的语义相同）。创建函数后，此 API 随即会使用 arrayKey 参数在 window 中创建一个数组（如果尚无数组）。

调用在 fnKey 下创建的函数时，该函数会将其参数对象推送到在 arrayKey 下创建的数组。此 API 的返回值是在 fnKey 下创建的函数。

该函数需要有 access_globals 权限，具体来说需要对 fnKey 和 arrayKey 有读写权限。

示例：

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

语法

createArgumentsQueue(fnKey, arrayKey)

参数

参数 类型 说明
fnKey 字符串 window 中的路径，表示要在什么位置设置该函数（如果尚无函数）。此参数支持以英文句点分隔的标准表示法。如果该键所表示的路径不存在，则会引发异常。也就是说，如果 fnKey 为 'one.two'，则会引发异常。
arrayKey 字符串 window 中的路径，表示要在什么位置设置该数组（如果尚无数组）。此参数支持以英文句点分隔的标准表示法。如果该键所表示的路径不存在，则会引发异常。也就是说，如果 arrayKey 为 'one.two'，而实际上并没有名为 'one' 的全局对象，则会引发异常。

相关权限

access_globals

createQueue

在 window 中创建一个数组（如果尚无数组），并返回一个将向该数组推送值的函数。

该函数需要有 access_globals 权限，具体来说需要对 arrayKey 有读写权限。

示例：

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

语法

createQueue(arrayKey)

参数

参数 类型 说明
arrayKey 字符串 window 中的键，表示要在什么位置设置该数组（如果尚无数组）。此参数支持以英文句点分隔的标准表示法。如果该键所表示的路径不存在，则会引发异常。例如，如果 arrayKey 为 'one.two'，而实际上并没有名为 'one' 的全局对象，则会引发异常。

相关权限

access_globals

decodeUri

用于对提供的 URI 中任何已编码的字符进行解码。返回值的类型为字符串，表示所提供的 URI 解码后的形式。如果提供的输入无效，它会返回 undefined。

示例：

const decode = require('decodeUri');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

语法

decodeUri(encoded_uri)

参数

参数 类型 说明
encoded_uri 字符串 已通过 encodeUri() 或其他方式编码的 URI。

相关权限

无。

decodeUriComponent

用于对提供的 URI 组成部分中任何已编码的字符进行解码。返回值的类型为字符串，表示所提供的 URI 组成部分解码后的形式。如果提供的输入无效，它会返回 undefined。

示例：

const decode = require('decodeUriComponent');

const decodedUrl = decode(data.encodedUrl);
if (decodedUrl) {
  // ...
}

语法

decodeUriComponent(encoded_uri_component)

参数

参数 类型 说明
encoded_uri_component 字符串 已通过 encodeUriComponent() 或其他方式编码的 URI 组成部分。

相关权限

无。

encodeUri

通过对特殊字符进行转义，返回经过编码的统一资源标识符 (URI)。返回值的类型为字符串，表示所提供的字符串编码为 URI 后的形式。如果提供的输入无效（单独的 surrogate 代理），它会返回 undefined。

示例：

sendPixel('https://www.example.com/' + encodeUri(pathInput));

语法

encodeUri(uri)

参数

参数 类型 说明
uri 字符串 完整的 URI。

相关权限

无。

encodeUriComponent

通过对特殊字符进行转义，返回经过编码的统一资源标识符 (URI)。返回值的类型为字符串，表示所提供的字符串编码为 URI 后的形式。如果提供的输入无效（单独的 surrogate 代理），它会返回 undefined。

示例：

sendPixel('https://www.example.com/?' + encodeUriComponent(queryInput));

语法

encodeUriComponent(str)

参数

参数 类型 说明
str 字符串 URI 的一个组成部分。

相关权限

无。

fromBase64

您可以利用 fromBase64 API 从字符串的 Base64 表示法中解码字符串。如果提供的输入无效，它会返回 undefined。

语法

fromBase64(base64EncodedString)

参数

参数 类型 说明
base64EncodedString 字符串 Base64 编码的字符串。

示例

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

相关权限

无

generateRandom

返回指定范围内的一个随机数字（整数）。

语法

generateRandom(min, max)

参数

参数 类型 说明
min 数值 所返回的整数的下限值。
max 数值 所返回的整数的上限值。

相关权限

无。

getContainerVersion

返回一个对象，其中包含有关当前容器的数据。返回的对象具有以下字段：

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

示例

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

语法

getContainerVersion();

相关权限

read_container_data

getCookieValues

返回具有指定名称的所有 Cookie 的值。

语法

getCookieValues(name[, decode])

参数

参数 类型 说明
name 字符串 Cookie 的名称。
decode 布尔值 用于控制是否要通过 JavaScript 的 decodeURIComponent() 对 Cookie 值进行解码。默认值为 true。

相关权限

get_cookies

getQueryParameters

返回当前网址的 queryKey 的第一个参数或所有参数。具体来说，返回 queryKey 中的第一个值，或者返回由 queryKey 中的所有值构成的一个数组。

语法

getQueryParameters(queryKey[, retrieveAll])

参数

参数 类型 说明
queryKey 字符串 要从查询参数部分中读取的键。
retrieveAll 布尔值 是否检索所有值。

例如，如果当前网址为 https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo，则：

  • getQueryParameters('var') == 'foo'
  • getQueryParameters('var', false) == 'foo'
  • getQueryParameters('var', null) == 'foo'
  • getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

相关权限

get_url 必须允许使用 query 组成部分，并且必须在允许使用的查询键中指定 queryKey（或者允许使用任意查询键）。

getReferrerQueryParameters

getReferrerQueryParameters API 的运行方式与 getQueryParameters 相同，只不过它作用于引荐来源网址，而不是当前网址。返回指定引荐来源网址的 queryKey 的第一个参数或所有参数。具体来说，返回 queryKey 中的第一个值，或者返回由 queryKey 中的所有值构成的一个数组。

语法

getReferrerQueryParameters(queryKey[, retrieveAll])

参数

参数 类型 说明
queryKey 字符串 要从查询参数部分中读取的键。
retrieveAll 布尔值 是否检索所有值。

例如，如果引荐来源网址为 https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo，则：

  • getReferrerQueryParameters('var') == 'foo'
  • getReferrerQueryParameters('var', false) == 'foo'
  • getReferrerQueryParameters('var', null) == 'foo'
  • getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

相关权限

get_referrer 必须允许使用 query 组成部分，并且必须在允许使用的查询键中指定 queryKey（或者允许使用任意查询键）。

getReferrerUrl

此 API 会根据指定的组成部分类型，从文档对象中读取引荐来源网址，并返回一个表示该引荐来源网址中某一部分的字符串。如未指定任何组成部分，则返回完整的引荐来源网址。

语法

getReferrerUrl([component])

参数

参数 类型 说明
component 字符串 要返回的网址组成部分。可以是以下各项之一：protocol、host、port、path、query、extension。如果 component 为 undefined、null 或不是以上任一项，则返回整个网址。

相关权限

get_referrer 必须允许使用 query 组成部分，并且必须在允许使用的查询键中指定 queryKey（或者允许使用任意查询键）。

getTimestamp

已弃用。优先使用 getTimestampMillis。

返回一个表示当前时间的数字，该数字是指自 Unix 纪元起到当前时间经过了多少毫秒，与 Date.now() 返回的值相同。

语法

getTimestamp();

相关权限

无。

getTimestampMillis

返回一个表示当前时间的数字，该数字是指自 Unix 纪元起到当前时间经过了多少毫秒，与 Date.now() 返回的值相同。

语法

getTimestampMillis();

相关权限

无。

getType

返回一个字符串，该字符串描述了指定值的类型。与 typeof 不同的是，getType 会区分 array 和 object。

语法

getType(data.someField)

备注

下表列出了针对每个输入值返回的字符串。

输入值 结果
undefined 'undefined'
null 'null'
true 'boolean'
12 'number'
'string' 'string'
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

相关权限

无。

getUrl

根据指定的组成部分类型和一些配置参数，返回表示当前网址中全部内容或部分内容的字符串。

语法

getUrl(component)

参数

参数 类型 说明
component 字符串 要返回的网址组成部分。必须是以下各项之一：protocol、host、port、path、query、extension、fragment。如果组成部分为 undefined、null 或不是以上任一项，则返回整个 href 值。

相关权限

get_url

gtagSet

将 gtag set 命令推送到数据层，以便系统在处理完当前事件及其触发的任何代码后（或达到代码处理超时时间后）尽快处理该命令。系统会先处理此容器中的更新，然后再处理数据层队列中的任何排队项目。

例如，如果此 API 被用户意见征求初始化触发的代码调用，则系统会在处理初始化事件之前应用相应更新。如，将 ads_data_redaction 设置为 true 或 false，或者将 url_passthrough 设置为 true 或 false。

示例：

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

语法

gtagSet(object)

参数

参数 类型 说明
Object 对象 用于更新所包含属性全局状态的对象。

相关权限

write_data_layer，检查所有指定键对 dataLayer 的写入权限。如果 gtagSet 的输入是一个普通对象，API 将检查该对象内所有扁平化键的写入权限，例如，对于 gtagSet({foo: {bar: 'baz'}})，API 将检查 foo.bar 的写入权限。

如果 gtagSet 的输入是一个键和一些非普通对象值，API 将检查该键的写入权限，例如，对于 gtagSet('abc', true) ，API 将检查 'abc' 的写入权限。

请注意，如果输入对象中存在循环，则只会检查到达同一对象之前的键。

injectHiddenIframe

向页面中添加一个不可见的 iframe。

回调以函数实例的形式提供，并封装在调用它们的 JavaScript 函数中。

语法

injectHiddenIframe(url, onSuccess)

参数

参数 类型 说明
url 字符串 要用作 iframe src 属性值的网址。
onSuccess 函数 在该框架加载成功时调用。

相关权限

inject_hidden_iframe

injectScript

向页面添加脚本代码，以异步加载给定网址。回调以函数实例的形式提供，并封装在调用它们的 JavaScript 函数中。

语法

injectScript(url, onSuccess, onFailure[, cacheToken])

参数

参数 类型 说明
url 字符串 要注入的脚本的地址。
onSuccess 函数 在该脚本加载成功时调用。
onFailure 函数 在该脚本加载失败时调用。
cacheToken 字符串 可选字符串，用于指示应缓存指定的网址。如果指定此值，系统将仅创建一个脚本元素来请求 JavaScript。如果额外尝试加载，则会导致指定的 onSuccess 和 onFailure 方法排队等待，一直等到该脚本加载完毕为止。

相关权限

inject_script

isConsentGranted

如果指定的用户意见征求类型为“granted”，则返回 true。

如果某一用户意见征求类型已设置为“granted”或根本未设置，那么该类型会被视为已征得用户同意。如果用户意见征求类型已设置为任何其他值，则会被视为未征得用户同意。

代码设置所在的跟踪代码管理器界面将提供一个用于始终触发的选项。如果使用此 API 的代码已启用“始终触发”选项，那么无论用户意见征求的实际状态为何，系统都会将其视为“granted”并返回 true。

示例：

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

语法

isConsentGranted(consentType)

参数

参数 类型 说明
consentType 字符串 要检查状态的用户意见征求类型。

相关权限

access_consent 权限，其中包含对用户意见征求类型的读取权限。

JSON

返回一个提供 JSON 函数的对象。

parse() 函数可解析 JSON 字符串，以构造字符串描述的值或对象。如果值无法解析（例如，JSON 字符串格式不正确），该函数将返回 undefined。如果输入值不是字符串，系统会将其强制转换为字符串。

stringify() 函数可将输入值转换为 JSON 字符串。如果值无法解析（例如对象包含一个循环），该方法将返回 undefined。

语法

JSON.parse(stringInput)
JSON.stringify(value);

参数

JSON.parse

参数 类型 说明
stringInput 任意类型 要转换的值。如果值不是字符串，系统会将其强制转换为字符串。

JSON.stringify

参数 类型 说明
值 任意类型 要转换的值。

示例

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

localStorage

返回具有访问本地存储空间的方法的对象。

语法

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

相关权限

access_local_storage

示例

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

将参数记录到浏览器控制台。

语法

logToConsole(obj1 [, obj2,... objN])

参数

参数 类型 说明
obj1 [, obj2,... objN] 任意类型 参数

相关权限

logging

makeInteger

将指定的值转换为数字（整数）。

语法

makeInteger(value)

参数

参数 类型 说明
value 任意类型 要转换的值。

相关权限

无。

makeNumber

将指定的值转换为数字。

语法

makeNumber(value)

参数

参数 类型 说明
value 任意类型 要转换的值。

相关权限

无。

makeString

以字符串形式返回指定的值。

语法

makeString(value)

参数

参数 类型 说明
value 任意类型 要转换的值。

相关权限

无。

makeTableMap

将包含两列的简单表格对象转换为 Map。它用于将包含两列的 SIMPLE_TABLE 模板字段转换为更易于管理的格式。

例如，此函数可将以下表格对象：

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

转换为以下映射关系：

{
  'k1': 'v1',
  'k2': 'v2'
}

返回一个对象：如果为此函数添加了键值对，则返回转换后的 Map；否则，返回 null。

语法

makeTableMap(tableObj, keyColumnName, valueColumnName)

参数

参数 类型 说明
tableObj 列表 要转换的表格对象。这是一个映射关系列表，其中每个 Map 表示表格中的一行。行对象中的每个属性名称都是列名称，而属性值则是该行中的列值。
keyColumnName 字符串 列的名称，表示哪个列的值在转换后的 Map 中将成为键。
valueColumnName 字符串 列的名称，表示哪个列的值在转换后的 Map 中将成为值。

相关权限

无。

Math

提供 Math 函数的对象。

语法

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

参数

数学函数参数会转换为数字。

相关权限

无。

Object

返回提供 Object 方法的对象。

keys() 方法提供标准库 Object.keys() 行为。它返回给定对象自身的可枚举属性名称的数组，且顺序与 for...in... 循环的相同。如果输入值不是对象，则会被强制转换为对象。

values() 方法提供标准库 Object.values() 行为。它返回给定对象自身的可枚举属性值的数组，且顺序与 for...in... 循环的相同。如果输入值不是对象，则会被强制转换为对象。

entries() 方法提供标准库 Object.entries() 行为。它返回给定对象自身的可枚举属性 [key, value] 对的数组，且顺序与 for...in... 循环的相同。如果输入值不是对象，则会被强制转换为对象。

freeze() 方法提供标准库 Object.freeze() 行为。已冻结的对象无法再更改；冻结对象后，可防止向其添加新属性、移除现有的属性以及更改现有属性的值。freeze() 返回传入的同一个对象。基元参数或 null 参数将被视为已冻结的对象，且系统会将其返回。

delete() 方法提供标准库 delete 运算符行为。该方法会从对象中移除指定的键，除非该对象已冻结。与标准库 delete 运算符一样，如果第一个输入值 (objectInput) 是未冻结的对象，即使第二个输入值 (keyToDelete) 指定的键不存在，该方法也会返回 true。在所有其他情况下，该方法会返回 false。不过，它与标准库 delete 运算符在以下几个方面有所不同：

  • keyToDelete 不能是以英文句点分隔且可指定嵌套键的字符串。
  • delete() 不能用于从数组中移除元素。
  • delete() 不能用于从全局范围内移除任何属性。

语法

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

参数

Object.keys

参数 类型 说明
objectInput 任意类型 要枚举其键的对象。如果输入值不是对象，则会被强制转换为对象。

Object.values

参数 类型 说明
objectInput 任意类型 要枚举其值的对象。如果输入值不是对象，则会被强制转换为对象。

Object.entries

参数 类型 说明
objectInput 任意类型 要枚举其键值对的对象。如果输入值不是对象，则会被强制转换为对象。

Object.freeze

参数 类型 说明
objectInput 任意类型 要冻结的对象。如果输入值不是对象，则将其视为已冻结的对象。

Object.delete

参数 类型 说明
objectInput 任意类型 要删除其键的对象。
keyToDelete 字符串 要删除的顶级键。

示例

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

parseUrl

返回一个包含指定网址的所有组成部分的对象，与 URL 对象类似。

对于任何格式有误的网址，此 API 都将返回 undefined。对于格式正确的网址，未在网址字符串中出现的字段的值将为空字符串，如果是 searchParams，则为空对象。

所返回的对象将包含以下字段：

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

示例

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

语法

parseUrl(url);

参数

参数 类型 说明
url 字符串 要解析的完整网址。

相关权限

无。

queryPermission

查询允许的细化权限。返回一个布尔值：如果已授予权限，则返回 true；否则，返回 false。

语法

queryPermission(permission, functionArgs*)

参数

参数 类型 说明
permission 字符串 权限的名称。
functionArgs 任意类型 函数参数因所查询的权限而异。请参阅下文中的函数参数部分。

函数参数

sendPixel、injectScript、injectHiddenIframe：第二个参数应该是网址字符串。

writeGlobals、readGlobals：第二个参数应该是要写入或读取的键。

readUrl：无需其他参数即可查询是否可以读取整个网址。要查询是否可以读取指定的组成部分，请将该组成部分的名称作为第二个参数传递给此函数：

if (queryPermission('readUrl','port')) {
  // read the port
}

要查看是否可读取特定的查询键，请将该查询键作为第三个参数传递给此函数：

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

相关权限

无。

readCharacterSet

返回 document.characterSet 的值。

语法

readCharacterSet()

参数

无。

相关权限

read_character_set

readTitle

返回 document.title 的值。

语法

readTitle()

参数

无。

相关权限

read_title

require

根据名称导入内置函数。返回一个可从您的程序中调用的函数或对象。如果浏览器不支持内置函数，会返回 undefined。

语法

require(name)

参数

参数 类型 说明
name 字符串 要导入的函数的名称。

示例

const getUrl = require('getUrl');
const url = getUrl();

相关权限

无。

sendPixel

向指定网址端点发出 GET 请求。

语法

sendPixel(url, onSuccess, onFailure)

参数

参数 类型 说明
url 字符串 要将像素发往的位置。
onSuccess 函数 在像素加载成功时调用。注意：即使请求成功发送，浏览器也可能需要有效的图片响应才能运行 onSuccess。
onFailure 函数 在像素加载失败时调用。注意：即使请求成功发送，如果服务器未返回有效的图片响应，也可能会运行 onFailure。

相关权限

send_pixel

setCookie

根据指定的名称、值和选项设置或删除 Cookie。

语法

setCookie(name, value[, options, encode])

参数

参数 类型 说明
name 字符串 Cookie 的名称。
value 字符串 Cookie 的值。
options 对象 指定 Domain、Path、Expires、Max-Age、Secure 和 SameSite 属性。（请参阅下文中的选项部分。）
encode 布尔值 用于控制是否通过 JavaScript 的 encodeURIComponent() 对 Cookie 值进行编码。默认值为 true。

选项

  • Domain：通过 options['domain'] 属性进行设置（如果存在）。如果将此值设置为 'auto'，系统会尝试根据文档位置使用尽可能宽泛的域名写入 Cookie。如果失败，它将相继尝试更为具体的子域名。如果所有这些尝试均失败，则将尝试在无域名的情况下写入 Cookie。如果未设置任何值，则将尝试在未指定域名的情况下写入 Cookie。注意：如果在未指定域名的情况下将 Cookie 写入 document.cookie，用户代理会默认该 Cookie 的域名为当前文档位置的主机。
  • Path：通过 options['path'] 进行设置（如果存在）。如果在未指定路径的情况下将 Cookie 写入 document.cookie，用户代理会默认该 Cookie 的路径为当前文档位置的路径。
  • Max-Age：通过 options['max-age'] 进行设置（如果存在）。
  • Expires：通过 options['expires'] 进行设置（如果存在）。如果存在，则必须是采用 UTC 格式的日期字符串。Date.toUTCString() 可用于为此参数设置 Date 格式。
  • Secure：通过 options['secure'] 进行设置（如果存在）。
  • SameSite：通过 options['samesite'] 进行设置（如果存在）。

相关权限

set_cookies

setDefaultConsentState

将默认同意情况更新推送到数据层，以便系统在处理完当前事件及其触发的任何代码后（或达到代码处理超时时间后）尽快处理该更新。系统会先处理此容器中的更新，然后再处理数据层中的任何排队项目。详细了解用户意见征求。

示例：

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

语法

setDefaultConsentState(consentSettings)

参数

参数 类型 说明
consentSettings 对象 一个对象，用于定义指定的用户意见征求类型的默认状态。

consentSettings 对象是从任意用户意见征求类型字符串到 'granted' 或 'denied' 其中之一的映射。该对象支持以下值：

键名 类型 说明
consentType 字符串 每种用户意见征求类型的值均可设置为 `'granted'` 或 `'denied'`。如果设置为 `'granted'` 之外的任何值，则会被视为 `'denied'`。将此值设置为 `undefined` 不会对其之前的值产生任何影响。
region 数组 可选的区域代码数组，用于指定应用用户意见征求设置的区域。区域代码使用国家/地区和/或下属行政单位表示，采用 ISO 3166-2 格式。
wait_for_update 数值 指定一个单位为毫秒的值，以控制在发送数据前等待的时间。与异步加载的用户意见征求工具搭配使用。

相关权限

access_consent 权限，其中包含对 consentSettings 对象中所有用户意见征求类型的写入权限。

setInWindow

在 window 中为指定的键设置指定的值。默认情况下，如果 window 中已有相应的值，则此方法不会设置任何值。不过，如果将 overrideExisting 设置为 true，则无论 window 中是否已存在相应的值，均会设置指定的值。返回一个布尔值：如果值设置成功，则返回 true；否则，返回 false。

语法

setInWindow(key, value, overrideExisting)

参数

参数 类型 说明
key 字符串 window 中的键，表示要为哪个键设置值。
value * 要在 window 中设置的值。
overrideExisting 布尔值 一个标志，指示无论 window 中是否已存在值，均应设置指定的值。

相关权限

access_globals

sha256

计算已输入内容的 SHA-256 摘要，并通过采用 base64 编码的摘要调用回调函数，除非 options 对象指定其他输出编码。

示例：

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

语法

sha256(input, onSuccess, onFailure = undefined, options = undefined)

参数

参数 类型 说明
input 字符串 要计算哈希值的字符串。
onSuccess 函数 通过计算得出的、采用 base64 编码的摘要进行调用，除非 options 对象指定其他输出编码。
onFailure 函数 如果在计算摘要时出错，或浏览器本身不支持 Sha256，则会调用此函数。系统会使用一个包含错误名称和错误消息的对象调用该回调函数。
options 对象 用于指定输出编码的选项对象，此参数可选。如果已指定，则该对象应包含值为 base64 或 hex 其中之一的键 outputEncoding。

相关权限

无。

templateStorage

返回具有访问模板存储空间的方法的对象。模板存储允许在单个模板的执行之间共享数据。存储在模板存储空间中的数据会在页面的生命周期内持续有效。

语法

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

// Deletes all stored values for the template.
templateStorage.clear();

相关权限

access_template_storage

示例

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

您可以利用 toBase64 API 将字符串编码为 Base64 表示法。

语法

toBase64(input)

参数

参数 类型 说明
input 字符串 要编码的字符串。

示例

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

相关权限

无

updateConsentState

将同意情况更新推送到数据层，以便系统在处理完当前事件及其触发的任何代码后（或达到代码处理超时时间后）尽快处理该更新。系统会先处理此容器中的更新，然后再处理数据层中的任何排队项目。详细了解用户意见征求。

示例：

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

语法

updateConsentState(consentSettings)

参数

参数 类型 说明
consentSettings 对象 用于更新指定的用户意见征求类型的状态的对象。

consentSettings 对象是从任意用户意见征求类型字符串到 'granted' 或 'denied' 其中之一的映射。该对象支持以下值：

键名 类型 说明
consentType 字符串 每种用户意见征求类型的值均可设置为“granted”或“denied”。如果设置为“granted”之外的任何值，则会被视为“denied”。将此值设置为“undefined”不会对其之前的值产生任何影响。

相关权限

access_consent 权限，其中包含对 consentSettings 对象中所有用户意见征求类型的写入权限。

测试 API

这些 API 采用沙盒化 JavaScript 测试，在 Google 跟踪代码管理器中为自定义模板构建测试。这些测试 API 不需要使用 require() 语句。详细了解自定义模板测试。

assertApi

返回一个匹配函数对象，该对象可用于顺畅地就指定的 API 进行断言。

语法

assertApi(apiName)

参数

参数 类型 说明
apiName 字符串 要检查的 API 的名称；与传递给 require() 的字符串相同。

匹配函数

  • Subject.wasCalled()
  • Subject.wasNotCalled()
  • Subject.wasCalledWith(...expected)
  • Subject.wasNotCalledWith(...expected)

示例

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

assertThat

assertThat API 是以 Google 的 [Truth] 库为模型设计的。它会返回一个对象，该对象可用于顺畅地就某一主体的值进行断言。如果断言失败，系统会立即停止测试，并将其标记为未通过。不过，一项测试未通过不会影响其他测试用例。

语法

assertThat(actual, opt_message)

参数

参数 类型 说明
actual 任意类型 完成顺畅检查所用的值。
opt_message 字符串 断言失败时输出的消息（可选）。

匹配函数

匹配函数 说明
isUndefined() 断言主体的值为 undefined。
isDefined() 断言主体的值不为 undefined。
isNull() 断言主体的值为 null。
isNotNull() 断言主体的值不为 null。
isFalse() 断言主体的值为 false。
isTrue() 断言主体的值为 true。
isFalsy() 断言主体的值为 falsy。Falsy 值包括 undefined、null、false、NaN、0 和 ''（空字符串）。
isTruthy() 断言主体的值为 truthy。Falsy 值包括 undefined、null、false、NaN、0 和 ''（空字符串）。
isNaN() 断言主体的值为 NaN。
isNotNaN() 断言主体的值为 NaN 以外的任何值。
isInfinity() 断言主体为正无穷大或负无穷大。
isNotInfinity() 断言主体为正无穷大或负无穷大之外的任何值。
isEqualTo(expected) 断言主体的值等于指定值。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
isNotEqualTo(expected) 断言主体的值不等于指定值。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
isAnyOf(...expected) 断言主体的值等于某个指定值。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
isNoneOf(...expected) 断言主体的值不等于任何指定值。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
isStrictlyEqualTo(expected) 断言主体的值严格等于 (===) 指定值。
isNotStrictlyEqualTo(expected) 断言主体的值不严格等于 (!==) 指定值。
isGreaterThan(expected) 断言主体的值大于 (>) 有序比较中的指定值。
isGreaterThanOrEqualTo(expected) 断言主体的值大于或等于 (>=) 有序比较中的指定值。
isLessThan(expected) 断言主体的值小于 (<) 有序比较中的指定值。
isLessThanOrEqualTo(expected) 断言主体的值小于或等于 (<=) 有序比较中的指定值。
contains(...expected) 断言主体的值是以任意顺序包含所有指定值的数组或字符串。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
doesNotContain(...expected) 断言主体的值是不包含任何指定值的数组或字符串。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
containsExactly(...expected) 断言主体的值是以任意顺序包含所有指定值且不包含任何其他值的数组。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
doesNotContainExactly(...expected) 断言主体的值是以任意顺序包含不同于指定值的一组值的数组。这是对值的比较，而不是对引用的比较。对象和数组的内容以递归方式进行比较。
hasLength(expected) 断言主体的值是指定长度的数组或字符串。如果值不是数组或字符串，则断言失败。
isEmpty() 断言主体的值是空数组或字符串（长度 = 0）。如果值不是数组或字符串，则断言失败。
isNotEmpty() 断言主体的值是非空数组或字符串（长度 > 0）。如果值不是数组或字符串，则断言失败。
isArray() 断言主体类型是数组。
isBoolean() 断言主体类型是布尔值。
isFunction() 断言主体类型是函数。
isNumber() 断言主体类型是数字。
isObject() 断言主体类型是对象。
isString() 断言主体类型是字符串。

示例

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

立即将当前测试认定为未通过，并输出指定的消息（如果已提供）。

语法

fail(opt_message);

参数

参数 类型 说明
opt_message 字符串 错误消息文本（可选）。

示例

fail('This test has failed.');

mock

mock API 用于覆盖沙盒化 API 的行为。模拟 API 在模板代码中可以安全使用，但它只能在测试模式下运行。在每个测试运行前，模拟都会被重置。

语法

mock(apiName, returnValue);

参数

参数 类型 说明
apiName 字符串 要模拟的 API 的名称；与传递给 require() 的字符串相同
returnValue 任意类型 要为此 API 返回的值或者代替此 API 被调用的函数。如果 returnValue 是函数，则调用该函数，而不是沙盒化 API；如果 returnValue 是除函数之外的任何其他值，则返回该值，而不是沙盒化 API。

示例

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

mockObject

mockObject API 用于覆盖返回对象的沙盒化 API 的行为。该 API 在模板代码中可以安全使用，但只能在测试模式下运行。在每个测试运行前，模拟都会被重置。

语法

mockObject(apiName, objectMock);

参数

参数 类型 说明
apiName 字符串 要模拟的 API 的名称；与传递给 require() 的字符串相同
objectMock 对象 要为此 API 返回的值或者代替此 API 被调用的函数。必须是对象。

示例

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

使用指定的输入数据对象在当前测试环境中运行模板代码，即代码标签页中的内容。

语法

runCode(data)

参数

参数 类型 说明
data 对象 要在测试中使用的数据对象。

返回值

对于变量模板，返回相应变量的值；对于所有其他模板类型，返回 undefined。

示例

runCode({field1: 123, field2: 'value'});