核心 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);
});
相关权限
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。 |
相关权限
copyFromWindow
从 window 对象中复制变量。如果 window 中的值无法直接映射到在沙盒中运行的 JavaScript 所支持的类型，则返回 undefined。在沙盒中运行的 JavaScript 支持以下八种类型：null、undefined、boolean、number、string、Array、Object 和 function。返回提取（并强制转换后）的值。
语法
copyFromWindow(key)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
key |
字符串 | window 中的键，要复制的就是这个键的值。 |
相关权限
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' 的全局对象，则会引发异常。 |
相关权限
createQueue
在 window 中创建数组（如果尚无数组），并返回会将值推送到该数组的函数。
该函数需要有 access_globals 权限，具体来说需要对 arrayKey 有读写权限。
示例：
const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});
语法
createQueue(arrayKey)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
arrayKey |
字符串 | window 中的键，表示要在什么位置设置该数组（如果尚无数组）。此参数支持以英文句点分隔的标准表示法。如果该键所表示的路径不存在，则会引发异常。例如，如果 arrayKey 为 'one.two'，而实际上并没有名为 'one' 的全局对象，则会引发异常。 |
相关权限
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 后的形式。
示例：
sendPixel('https://www.example.com/' + encodeUri(pathInput));
语法
encodeUri(uri)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
uri |
字符串 | 完整的 URI。 |
相关权限
无。
encodeUriComponent
通过对特殊字符进行转义，返回经过编码的统一资源标识符 (URI)。返回值的类型为字符串，表示所提供的字符串编码为 URI 后的形式。
示例：
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();
相关权限
getCookieValues
返回具有指定名称的所有 Cookie 的值。
语法
getCookieValues(name[, decode])
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name |
字符串 | Cookie 的名称。 |
decode |
布尔值 | 用于控制是否要通过 JavaScript 的 decodeURIComponent() 对 Cookie 值进行解码。默认值为 true。 |
相关权限
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 值。 |
相关权限
injectHiddenIframe
向页面中添加一个不可见的 iframe。
回调以函数实例的形式提供，并封装在调用它们的 JavaScript 函数中。
语法
injectHiddenIframe(url, onSuccess)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
url |
字符串 | 要用作 iframe src 属性值的网址。 |
onSuccess |
函数 | 在该框架加载成功时调用。 |
相关权限
injectScript
向页面添加脚本代码，以异步加载给定网址。回调以函数实例的形式提供，并封装在调用它们的 JavaScript 函数中。
语法
injectScript(url, onSuccess, onFailure[, cacheToken])
参数
| 参数 | 类型 | 说明 |
|---|---|---|
url |
字符串 | 要注入的脚本的地址。 |
onSuccess |
函数 | 在该脚本加载成功时调用。 |
onFailure |
函数 | 在该脚本加载失败时调用。 |
cacheToken |
字符串 | 可选字符串，用于指示应缓存指定的网址。如果指定此值，系统将仅创建一个脚本元素来请求 JavaScript。如果额外尝试加载，则会导致指定的 onSuccess 和 onFailure 方法排队等待，一直等到该脚本加载完毕为止。 |
相关权限
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);
相关权限
示例
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] |
任意类型 | 参数 |
相关权限
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);
参数
数学函数参数会转换为数字。
相关权限
无。
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()
参数
无。
相关权限
readTitle
返回 document.title 的值。
语法
readTitle()
参数
无。
相关权限
require
根据名称导入内置函数。返回一个可从您的程序中调用的函数或对象。如果浏览器不支持内置函数，会返回 undefined。
语法
require(name)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name |
字符串 | 要导入的函数的名称。 |
示例
const getUrl = require('getUrl');
const url = getUrl();
相关权限
无。
sendPixel
向指定网址端点发出 GET 请求。
语法
sendPixel(url, onSuccess, onFailure)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
url |
字符串 | 要将像素发往的位置。 |
onSuccess |
函数 | 在该像素发送成功时调用。 |
onFailure |
函数 | 在该像素发送失败时调用。 |
相关权限
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']进行设置（如果存在）。
相关权限
setDefaultConsentState
设置（或更新）网页上用户意见征求的默认状态。
示例：
const setDefaultConsentState = require('setDefaultConsentState');
setDefaultConsentState({
'ad_storage': 'denied',
'analytics_storage': 'granted',
'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 中是否已存在值，均应设置指定的值。 |
相关权限
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();
相关权限
示例
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'
});
语法
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 的行为。mock 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();
});
runCode
使用指定的输入数据对象在当前测试环境中运行模板代码，即代码标签页中的内容。
语法
runCode(data)
参数
| 参数 | 类型 | 说明 |
|---|---|---|
data |
对象 | 要在测试中使用的数据对象。 |
返回值
对于变量模板，返回相应变量的值；对于所有其他模板类型，返回 undefined。
示例
runCode({field1: 123, field2: 'value'});