服务器端代码植入 API

本文档简要介绍了适用于服务器端代码植入的 API。

---

addEventCallback

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

在代码中使用此 API 时，它会与当前事件相关联。在客户端中使用此 API 时，必须使用 runContainer API 的 bindToEvent 函数将其绑定到特定事件。如需了解详情，请参阅示例。

语法

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

参数

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

eventData 对象包含以下数据：

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

示例

在客户端中：

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

在代码中：

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

相关权限

read_event_metadata

---

callLater

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

示例

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

语法

callLater(function)

参数

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

相关权限

无。

---

claimRequest

在客户端中可使用此 API 来认领请求。认领请求后，容器便不会运行其他客户端。

如果在代码或变量中调用此 API，它会抛出异常。如果在客户端返回后调用此 API（例如，在 callLater 或 runContainer onComplete 函数等异步回调函数中调用），它会抛出异常。

客户端应先使用此 API 认领请求，然后再调用 runContainer API。

示例

const claimRequest = require('claimRequest');

claimRequest();

语法

claimRequest();

相关权限

无。

---

computeEffectiveTldPlusOne

返回指定网域或网址的有效顶级域名 + 1 (eTLD+1)。eTLD+1 是根据公共后缀列表规则评估网域后计算得出的。eTLD+1 通常是可让您设置 Cookie 的最高一级网域。

如果参数为 null 或未定义，则原样返回参数值。否则，会将该参数强制转换为字符串。如果该参数不是有效的网域或网址，则返回空字符串。如果服务器无法提取公共后缀列表，则原样返回参数值。

示例

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

语法

computeEffectiveTldPlusOne(domainOrUrl);

参数

参数	类型	说明
domainOrUrl	字符串	供计算 eTLD+1 用的网域或网址。

相关权限

无。

---

createRegex

创建一个新的正则表达式实例，并将其封装在一个对象中返回。您无法直接访问正则表达式。但是，您可以将其传递到 testRegex API、String.replace()、String.match() 和 String.search() 中。

如果正则表达式无效或 Re2 在服务器上不可用，则返回 null。

此 API 使用 Re2 实现。服务器 Docker 映像必须为 2.0.0 或更高版本。

示例

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

语法

createRegex(pattern, flags);

参数

参数	类型	说明
pattern	字符串	正则表达式的文本。
flags	字符串	包含要创建的正则表达式标志的可选字符串。 支持的字符串包括 `g` (global) 和 `i` (ignore case)。其他所有字符都将被静默忽略。

相关权限

无。

---

decodeUri

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

示例

const decodeUri = require('decodeUri');

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

语法

decodeUri(encoded_uri);

参数

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

相关权限

无。

---

decodeUriComponent

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

示例

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

语法

decodeUriComponent(encoded_uri_component);

参数

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

相关权限

无。

---

encodeUri

通过对特殊字符进行转义，返回经过编码的统一资源标识符 (URI)。返回值的类型为字符串，表示所提供的字符串编码为 URI 后的形式。

示例

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

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

语法

encodeUri(uri);

参数

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

相关权限

无。

---

encodeUriComponent

通过对特殊字符进行转义，返回经过编码的统一资源标识符 (URI)。返回值的类型为字符串，表示所提供的字符串编码为 URI 后的形式。

示例

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

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

语法

encodeUriComponent(str);

参数

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

相关权限

无。

---

extractEventsFromMpv1

将传入的 Measurement Protocol V1 请求转换为采用统一架构格式的事件列表。返回提取的事件列表。如果请求的格式不正确，则会抛出错误。

示例

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

语法

extractEventsFromMpv1();

相关权限

需要 read_request 权限。此权限必须配置为至少允许访问以下内容：

• body
• query parameters

---

extractEventsFromMpv2

将传入的 Measurement Protocol V2 请求转换为采用统一架构格式的事件列表。返回提取的事件列表。如果请求的格式不正确，则会抛出错误。

示例

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

语法

extractEventsFromMpv2();

相关权限

需要 read_request 权限。此权限必须配置为至少允许访问以下内容：

• body
• query parameters

---

fromBase64

对 base64 编码的字符串进行解码。如果输入无效，则返回 undefined。

语法

fromBase64(base64EncodedString);

参数

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

示例

const fromBase64 = require('fromBase64');

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

相关权限

无。

---

generateRandom

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

示例

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

语法

generateRandom(min, max);

参数

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

相关权限

无。

---

getAllEventData

返回事件数据的副本。

语法

getAllEventData();

相关权限

read_event_data

---

getClientName

返回一个字符串，其中包含当前客户端的名称。

语法

getClientName();

相关权限

read_container_data

---

getContainerVersion

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

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

示例

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

语法

getContainerVersion();

相关权限

read_container_data

---

getCookieValues

返回一个数组，其中包含具有指定名称的所有 Cookie 的值。

示例

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

语法

getCookieValues(name[, noDecode]);

参数

参数	类型	说明
name	字符串	Cookie 的名称。
noDecode	布尔值	如果值为 true，则在返回 Cookie 值之前不会对其进行解码。默认值为 false。

相关权限

get_cookies

---

getEventData

返回事件数据中指定路径上的值的副本。如果没有事件数据或者指定路径上没有任何值，则返回 undefined。

示例

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

参数

参数	类型	说明
keyPath	任意类型	键的路径，其中路径组成部分以点号分隔。路径组成部分可以是对象中的键，也可以是数组中的索引。如果 keyPath 不是字符串，系统会将其强制转换为字符串。

语法

getEventData(keyPath);

相关权限

read_event_data

---

getGoogleScript

从一组预定的 Google 脚本中检索资源，并返回包含脚本及所关联缓存元数据的 promise。

promise 将解析为包含以下两个键的对象：script 和 metadata。如果请求失败，promise 将拒绝并返回 reason 键。

metadata 对象将基于资源响应标头包含以下缓存元数据；每个字段仅会在资源响应中包含相应标头时显示。

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

示例

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

语法

getGoogleScript(script[, options]);

参数

参数	类型	说明
script	字符串	脚本的名称。支持的脚本包括 'ANALYTICS'、'GTAG' 和 'GTM'。 'ANALYTICS' 选项会从 https://www.google-analytics.com/analytics.js 中提取 Google Analytics（分析）脚本。 'GTAG' 选项会从 https://www.googletagmanager.com/gtag/js 中提取全局网站代码 (gtag.js) 脚本。 'GTM' 选项会从 https://www.googletagmanager.com/gtm.js 中提取 Google 跟踪代码管理器脚本。
options	对象	可选的请求选项。请参阅下文，了解受支持的选项。

选项

选项	类型	说明
id	字符串	适用于具有 gtag 衡量 ID 的 'GTAG' 和具有网站容器 ID 的 'GTM'（例如 GTM-XXXX）。
debug	任意类型	如果值为 true，则请求并返回调试版衡量脚本。
timeout	数值	请求超时（以毫秒为单位）；系统会忽略非正值。如果请求超时，对于脚本值，将使用 undefined 调用回调函数，对于元数据对象，将使用 {} 调用回调函数。

系统会忽略无法识别的选项键。

相关权限

需要 send_http 权限。此权限必须配置为至少允许访问以下内容：

• 允许 Google 网域

---

getRemoteAddress

通过读取 Forwarded 和 X-Forwarded-For 等请求标头，返回发起请求的 IP 地址的字符串表示形式，例如 12.345.67.890（对于 IPv4）或 2001:0db8:85a3:0:0:8a2e:0370:7334（对于 IPv6）。注意：此 API 会尽最大努力查找发起请求的 IP 地址，但无法保证结果的准确性。

语法

getRemoteAddress();

相关权限

需要 read_request 权限。此权限必须配置为至少允许访问以下内容：

• 标头 Forwarded 和 X-Forwarded-For
• 远程 IP 地址

---

getRequestBody

如果存在，则以字符串形式返回请求正文，否则返回 undefined。

语法

getRequestBody();

相关权限

read_request

---

getRequestHeader

如果存在，则以字符串形式返回已命名的请求标头的值，否则返回 undefined。如果该标头重复出现，则返回的值会使用 ', ' 组合在一起。

示例

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

语法

getRequestHeader(headerName);

参数

参数	类型	说明
headerName	字符串	标头名称。此值不区分大小写。

相关权限

read_request

---

getRequestMethod

以字符串形式返回请求方法，例如 'GET' 或 'POST'。

示例

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

语法

getRequestMethod();

相关权限

无。

---

getRequestPath

返回不带查询字符串的请求路径。例如，如果网址为 '/foo?id=123'，则返回 '/foo'。它会自动从路径中移除服务器容器网址前缀。例如，如果服务器容器网址为 https://example.com/analytics，请求路径为 '/analytics/foo'，则返回 '/foo'。

示例

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

语法

getRequestPath();

相关权限

read_request

---

getRequestQueryParameter

以字符串形式返回已命名的查询字符串参数解码后的值；如果该参数不存在，则返回 undefined。如果该参数在查询字符串中重复出现，则会返回查询字符串中出现的第一个值。

示例

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

语法

getRequestQueryParameter(name);

参数

参数	类型	说明
name	字符串	查询参数名称。

相关权限

read_request

---

getRequestQueryParameters

以对象形式返回传入 HTTP 请求的查询参数，该对象会将查询参数名称映射到对应的一个或多个值。参数名称和值已解码。

示例

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

语法

getRequestQueryParameters();

相关权限

read_request

---

getRequestQueryString

以字符串形式返回请求查询，不带前导问号；如果请求网址不包含查询字符串，则返回空字符串。

示例

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

语法

getRequestQueryString();

相关权限

read_request

---

getTimestamp

已弃用。优先使用 getTimestampMillis。

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

语法

getTimestamp();

相关权限

无。

---

getTimestampMillis

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

语法

getTimestampMillis();

相关权限

无。

---

getType

返回一个字符串，该字符串描述了指定值的类型。

输入类型	返回值
字符串	'string'
数值	'number'
布尔值	'boolean'
null	'null'
undefined	'undefined'
数组	'array'
对象	'object'
函数	'function'

示例

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

语法

getType(value);

参数

参数	类型	说明
value	任意类型	输入值。

相关权限

无。

---

isRequestMpv1

如果传入的请求是 Measurement Protocol V1 请求，则返回 true，否则返回 false。

示例

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

语法

isRequestMpv1();

相关权限

无。

---

isRequestMpv2

如果传入的请求是 Measurement Protocol V2 请求，则返回 true，否则返回 false。

示例

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

语法

isRequestMpv2();

相关权限

无。

---

logToConsole

将其参数记录到控制台。

这些日志可在 Google Cloud 控制台的日志浏览器中查看。在日志浏览器中，运行查询 logName =~ "stdout" 以查看此 API 创建的日志条目。

示例

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

语法

logToConsole(argument1[, argument2, ...]);

参数

该 API 会采用一个或多个参数，其中每个参数都会转换为字符串（如有必要），并记录到控制台中。

相关权限

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 中将成为值。

相关权限

无。

---

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:[e-mail]:8080/foo?param=val%2Cue#bar');

语法

parseUrl(url);

参数

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

相关权限

无。

---

returnResponse

使用可修改响应的 API 清空其他模板之前设置的响应，其中包括：setCookie、setPixelResponse、setResponseBody、setResponseHeader 和 setResponseStatus。默认为 HTTP 状态代码 200、空正文和无标头。

建议您通过客户端模板使用此 API。

语法

returnResponse();

示例

请参阅 runContainer 示例。

相关权限

return_response

---

runContainer

在事件范围内运行容器逻辑（变量、触发器、代码）。如果在容器执行期间调用了此 API，则会再次运行该容器。

onComplete 和 onStart 回调函数会收到名为 bindToEvent 的函数。使用 bindToEvent 可在事件上下文中运行 API。如需了解详情，请参阅 addEventCallback 示例。

建议您通过客户端模板使用此 API。

示例

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

语法

runContainer(event, onComplete, onStart);

参数

参数	类型	说明
event	对象	事件参数。
onComplete	函数	在所有代码完成触发后调用的回调函数。
onStart	函数	在代码开始触发前立即调用的回调函数。

相关权限

run_container

---

sendEventToGoogleAnalytics

将使用常见事件数据的单个事件发送给 Google Analytics（分析），并返回一个 promise，它可以解析为一个带有 location 键的对象，或者拒绝并返回 reason 键。平台 Universal Analytics 或 Google Analytics（分析）4 均基于事件数据中的衡量 ID。

location 字段设置为 location 标头（如果存在）。

示例

const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

语法

sendEventToGoogleAnalytics(event);

参数

参数	类型	说明
event	对象	采用统一架构格式的事件。

相关权限

需要 send_http 权限。此权限必须配置为至少允许访问以下内容：

• 允许 Google 网域

---

sendHttpGet

向指定网址发出 HTTP GET 请求，并在请求完成或超时后返回通过结果解析的 promise。

解析后的结果是包含以下三个键的对象：statusCode、headers 和 body。如果请求失败（例如网址无效、没有通向主机的路由、SSL 协商失败等），promise 将拒绝，并返回 {reason: 'failed'}。如果已设置 timeout 选项且请求超时，promise 将拒绝并返回：{reason: 'timed_out'}

示例

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

语法

sendHttpGet(url[, options]);

参数

参数	类型	说明
url	字符串	请求网址。
options	对象	可选的请求选项。支持的选项包括：标头和超时。系统会忽略未知的选项键（请参阅下文中的选项部分）。

选项

• 标头：以对象形式表示的其他请求标头。
• 超时：表示请求取消之前的超时时间（以毫秒为单位）。 默认值为 15000。

相关权限

send_http

---

sendHttpRequest

向指定网址发出 HTTP 请求，并在请求完成或超时后返回通过响应解析的 promise。

解析后的结果是包含以下三个键的对象：statusCode、headers 和 body。如果请求失败（例如网址无效、没有通向主机的路由、SSL 协商失败等），promise 将拒绝，并返回 {reason: 'failed'}。如果已设置 timeout 选项且请求超时，promise 将拒绝并返回：{reason: 'timed_out'}

示例

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

语法

sendHttpRequest(url[, options[, body]]);

参数

参数	类型	说明
url	字符串	请求网址。
options	对象	可选的请求选项。支持的选项包括：标头、方法和超时。系统会忽略未知的选项键。（请参阅下文中的选项部分）。
body	字符串	可选的请求正文。

选项

• 标头：其他请求标头。
• 方法：请求方法，默认为“GET”。
• 超时：表示请求取消之前的超时时间（以毫秒为单位）。默认值为 15000。

相关权限

send_http

---

sendPixelFromBrowser

向浏览器发送一个命令，将提供的网址作为 <img> 代码加载。Google Analytics（分析）：GA4 配置和 Google Analytics（分析）：GA 事件网站代码支持此命令协议。您必须在配置代码中启用发送到服务器容器选项。请参阅相关说明了解详情。

如果收到的请求不支持命令协议，或响应已刷新，则此 API 会返回 false。否则，此 API 会返回 true。

示例：

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

语法

sendPixelFromBrowser(url)

参数

参数	类型	说明
url	字符串	要发送到浏览器的网址。

相关权限

send_pixel_from_browser

---

setCookie

根据指定的选项设置或删除 Cookie。

若要删除某个 Cookie，必须使用该 Cookie 创建时所用的同一路径和域名对其进行设置，并为其指定一个使用过去时间的 expires 值，例如 "Thu, 01 Jan 1970 00:00:00 GMT"。

请注意，要将该响应发送回客户端，必须调用 returnResponse。

示例

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

语法

setCookie(name, value[, options[, noEncode]]);

参数

参数	类型	说明
name	字符串	Cookie 名称。该名称不区分大小写。
value	字符串	Cookie 值。
options	对象	可选的 Cookie 属性：domain、expires、fallbackDomain、httpOnly、max-age、path、secure 和 sameSite（请参阅下文中的选项部分）。
noEncode	布尔值	如果值为 true，则不会对 Cookie 值进行编码。默认值为 false。

选项

• domain：用于接收 Cookie 的主机。如果设置为特殊值“auto”，则系统会使用以下策略自动计算主机：

  • Forwarded 标头的 eTLD+1（如果存在）。
  • X-Forwarded-Host 标头的 eTLD+1（如果存在）。
  • Host 标头的 eTLD+1。

• expires：Cookie 的最长有效期。该值必须是采用 UTC 格式的日期字符串，例如“Sat, 26 Oct 1985 08:21:00 GMT”。如果同时设置了 expires 和 max-age，则以 max-age 为准。

• httpOnly：如果为 true，则禁止 JavaScript 访问 Cookie。

• max-age：Cookie 过期前剩余的时间（以秒为单位）。如果为零或负数，Cookie 将立即过期。如果同时设置了 expires 和 max-age，则以 max-age 为准。

• path：即路径，必须存在于请求的网址中，否则浏览器不会发送 Cookie 标头。

• secure：如果设置为 true，则仅在从 https: 端点发出请求时，才会将 Cookie 发送到服务器。

• sameSite：这些断言语句表示 Cookie 不得与跨源请求一起发送。必须为 'strict'、'lax' 或 'none'。

相关权限

set_cookie

---

setPixelResponse

将响应正文设置为 1x1 GIF，将 Content-Type 标头设置为“image/gif”，设置缓存标头（这样用户代理就不会缓存响应），以及将响应状态设置为 200。

请注意，要将该响应发送回客户端，必须调用 returnResponse。

语法

setPixelResponse();

相关权限

需要 access_response 权限。此权限必须配置为至少允许访问以下内容：

• headers - 必须允许以下键
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

---

setResponseBody

将响应正文设置到该参数。

请注意，要将该响应发送回客户端，必须调用 returnResponse。

语法

setResponseBody(body[, encoding]);

参数

参数	类型	说明
body	字符串	要设置为响应正文的值。
encoding	字符串	响应正文的字符编码（默认为 'utf8'）。支持的值包括：'ascii'、'utf8'、'utf16le'、'ucs2'、'base64'、'latin1'、'binary' 和 'hex'。

相关权限

需要 access_response 权限。此权限必须配置为至少允许访问以下内容：

• body

---

setResponseHeader

在要返回的响应中设置标头。如果采用此名称（不区分大小写）的标头以前曾通过此 API 进行了设置，那么，后面的调用会覆盖或清除前面的调用方设置的值。

请注意，要将该响应发送回客户端，必须调用 returnResponse。

语法

setResponseHeader(name, value);

参数

参数	类型	说明
name	字符串	标头名称。HTTP 标头名称不区分大小写，因此标头名称将采用小写形式。
value	字符串（未定义）	标头值。如果为 null 或 undefined，系统会从要返回的响应中清除已命名的标头。

相关权限

需要 access_response 权限。此权限必须配置为至少允许访问以下内容：

• headers

---

setResponseStatus

设置要返回的响应的 HTTP 状态代码。

请注意，要将该响应发送回客户端，必须调用 returnResponse。

语法

setResponseStatus(statusCode);

参数

参数	类型	说明
statusCode	数值	要返回的 HTTP 状态代码。

相关权限

需要 access_response 权限。此权限必须配置为至少允许访问以下内容：

• status

---

sha256

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

此 API 签名和行为会与网站容器的 sha256 API 相匹配；不过，服务器容器中的自定义模板应使用 sha256Sync API，以便简化代码。

示例

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

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

语法

sha256(input, onSuccess, options = undefined);

参数

参数	类型	说明
input	字符串	要进行哈希处理的字符串。
onSuccess	函数	通过计算得出的、采用 base64 编码的摘要进行调用，除非 options 对象指定其他输出编码。
options	对象	用于指定输出编码的选项对象，此参数可选。如果已指定，则该对象应包含值为 base64 或 hex 其中之一的键 outputEncoding。

相关权限

无。

---

sha256Sync

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

示例

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

语法

sha256Sync(input, options = undefined);

参数

参数	类型	说明
input	字符串	要进行哈希处理的字符串。
options	对象	用于指定输出编码的选项对象，此参数可选。如果已指定，则该对象应包含值为 base64 或 hex 其中之一的键 outputEncoding。

相关权限

无。

---

templateDataStorage

返回具有访问模板数据存储空间的方法的对象。模板数据存储空间可跨单个模板的执行过程共享数据。存储在模板数据存储空间中的数据会在运行容器的服务器上持续有效。在大多数情况下，会存在多个运行容器的服务器，因此将数据存储在模板数据存储空间中并不能保证每个后续请求都可以访问数据。

名称“templateDataStorage”中的“Data”一词表示只能使用该 API 存储普通的非函数数据类型。而任何函数或对传递到该 API 的函数的引用将存储为 null。

注意：在调试模式或预览模式下发出或通过模板编辑器发出的请求可获得对模板数据存储空间的访问权限，相应存储空间会被初始化为空的存储空间，且仅在请求的生命周期内有效（以免调试数据或测试数据与生产数据相混淆）。

注意：与 Web Storage API 不同，templateDataStorage 不会将数据序列化/反序列化为字符串。

语法

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

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

示例

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

相关权限

access_template_storage

---

testRegex

针对通过 createRegex API 创建的正则表达式测试字符串。如果正则表达式匹配，则返回 true。否则返回 false。

使用全局标志创建的正则表达式有状态。如需了解详情，请参阅正则表达式文档。

示例

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

语法

testRegex(regex, string);

参数

参数	类型	说明
regex	对象	要针对其进行测试的正则表达式，通过 createRegex API 返回。
string	字符串	要测试的测试字符串。

相关权限

无。

---

toBase64

对字符串进行 base64 编码。

语法

toBase64(input);

参数

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

示例

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

相关权限

无。

---

BigQuery

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

BigQuery.insert 函数允许将数据写入 BigQuery 表。它会返回一个 promise，该 promise 会在插入成功后进行解析或在出现错误后拒绝。

插入成功后，promise 会进行解析且不使用任何参数。

如果插入失败，promise 会拒绝并返回包含错误原因的对象列表，如果发生错误，则可能还会返回行对象。出现错误的原因可能是请求的某一部分成功完成，但其他部分未能完成。在这种情况下，promise 会遭到拒绝，同时每行的错误列表都会包含行对象，以帮助区分插入了哪些行（请参阅下文的错误示例）。如需了解详情，请参阅 BigQuery 有关错误消息的文档。

语法

BigQuery.insert(connectionInfo, rows[, options]);

参数

参数	类型	说明
connectionInfo	对象	定义连接到 BigQuery 表所需的信息。有一个可选参数和两个必需参数： projectId - 可选参数，是 Google Cloud Platform 项目 ID。如果省略此参数，只要项目 ID 的 access_bigquery 权限设置设为 * 或 GOOGLE_CLOUD_PROJECT，系统就会从环境变量 GOOGLE_CLOUD_PROJECT 中检索 projectId。如果服务器容器在 Google Cloud 上运行，则表明 GOOGLE_CLOUD_PROJECT 已设置为 Google Cloud 项目的 ID。 datasetId - BigQuery 数据集 ID。 tableId - BigQuery 表 ID。
rows	数组	要插入到表中的行。
options	对象	可选的请求选项。支持的选项包括：ignoreUnknownValues 和 skipInvalidRows。系统会忽略未知的选项键。（请参阅下文中的选项部分。）

选项

参数	类型	说明
ignoreUnknownValues	布尔值	如果设置为 true，则会接受包含与架构不匹配的值的行。未知值会被忽略。默认值为 false。
skipInvalidRows	布尔值	如果设置为 true，系统会插入请求的所有有效行，即使存在无效行也是如此。默认值为 false。

错误示例

“模块未找到”错误表示您的服务器容器可能正在运行尚未包含 BigQuery 模块的旧版映像。请使用我们的部署脚本以相同的设置重新部署您的服务器容器。操作完成后，模块将自动包含在内。

非插入错误通常包含一个具有 reason 键的错误对象：

[{reason: 'invalid'}]

插入错误可以包含多个具有 errors 数组和 row 对象的错误对象。以下是在插入两行时只有一行出现错误的错误响应示例：

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

示例

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

相关权限

access_bigquery

---

Firestore

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

此 API 仅支持原生模式下的 Firestore，而不支持 Datastore 模式下的 Firestore。

Firestore.read

Firestore.read 函数从 Firestore 文档中读取数据，并返回一个 promise，它可以解析为一个包含两个键（id 和 data）的对象。如果文档不存在，则 promise 会拒绝，并返回一个键为 reason、值为 not_found 的对象。

注意：默认情况下，Firestore.read 会在容器执行期间缓存其响应。如需停用缓存，请参阅下文中的选项部分。在任何事务期间，缓存都会自动停用。

语法

Firestore.read(path[, options]);

参数

参数	类型	说明
path	字符串	指向文档或集合的路径。不得以“/”开头或结尾。
options	对象	可选的请求选项。支持的选项包括：projectId、disableCache 和 transaction。系统会忽略未知的选项键。（请参阅下文中的选项部分。）

选项

参数	类型	说明
projectId	字符串	可选参数。是 Google Cloud Platform 项目 ID。如果省略此参数，只要项目 ID 的 access_firestore 权限设置设为 * 或 GOOGLE_CLOUD_PROJECT，系统就会从环境变量 GOOGLE_CLOUD_PROJECT 中检索 projectId。如果服务器容器在 Google Cloud 上运行，则表明 GOOGLE_CLOUD_PROJECT 已设置为 Google Cloud 项目的 ID。
disableCache	布尔值	可选参数。决定是否停用缓存。缓存默认处于启用状态，可在请求期间缓存结果。
transaction	字符串	可选参数。从 Firestore.runTransaction() 中检索的值。标记要在事务中使用的操作。

示例

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

Firestore.write 函数将数据写入 Firestore 文档或集合。如果路径指向集合，则系统将使用随机生成的 ID 创建文档。如果路径指向某个并不存在的文档，则系统将创建该文档。此 API 会返回一个 promise，它可以解析为所添加或修改文档的 ID。如果使用事务选项，该 API 仍会返回一个 promise，但不包含 ID，因为写入是批量进行的。

语法

Firestore.write(path, input[, options]);

参数

参数	类型	说明
path	字符串	指向文档或集合的路径。不得以“/”开头或结尾。
input	对象	要写入文档的值。如果设置了合并选项，该 API 会将输入中的键合并到文档中。
options	对象	可选的请求选项。支持的选项包括：projectId、merge 和 transaction。系统会忽略未知的选项键。（请参阅下文中的选项部分。）

选项

参数	类型	说明
projectId	字符串	可选参数。是 Google Cloud Platform 项目 ID。如果省略此参数，只要项目 ID 的 access_firestore 权限设置设为 * 或 GOOGLE_CLOUD_PROJECT，系统就会从环境变量 GOOGLE_CLOUD_PROJECT 中检索 projectId。如果服务器容器在 Google Cloud 上运行，则表明 GOOGLE_CLOUD_PROJECT 已设置为 Google Cloud 项目的 ID。
merge	布尔值	可选参数。如果设置为 true，则系统会将输入中的键合并到文档中，否则该方法会替换整个文档。默认值为 false。
transaction	字符串	可选参数。从 Firestore.runTransaction() 中检索的值。标记要在事务中使用的操作。

示例

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

Firestore.query 函数会查询给定集合，并返回解析为与查询条件匹配的 Firestore 文档数组的 promise。Firestore 文档对象与上文 Firestore.read 中列出的对象相同。如果没有与查询条件匹配的文档，返回的 promise 将解析为一个空数组。

注意：默认情况下，Firestore.query 会在容器执行期间缓存其响应。如需停用缓存，请参阅下文中的选项部分。在任何事务期间，缓存都会自动停用。

注意：Firestore 会自动为每个字段创建索引。为了对多个字段进行查询，可能需要为指定集合创建复合索引。如需了解详情，请参阅 Firestore 有关复合索引的文档。

语法

Firestore.query(collection, queryConditions[, options]);

参数

参数	类型	说明
collection	字符串	集合的路径，不得以“/”开头或结尾。
queryConditions	数组	查询条件数组。每个查询都是包含以下三个值的数组：键、运算符及预期值。例如：[[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]。 这些条件之间是 AND 关系，用于生成查询结果。如需查看兼容的查询运算符列表，请参阅 Firestore 的查询运算符。
options	对象	可选的请求选项。支持的选项包括：projectId、disableCache、limit 和 transaction。系统会忽略未知的选项键。（请参阅下文中的选项部分。）

选项

参数	类型	说明
projectId	字符串	可选参数。是 Google Cloud Platform 项目 ID。如果省略此参数，只要项目 ID 的 access_firestore 权限设置设为 * 或 GOOGLE_CLOUD_PROJECT，系统就会从环境变量 GOOGLE_CLOUD_PROJECT 中检索 projectId。如果服务器容器在 Google Cloud 上运行，则表明 GOOGLE_CLOUD_PROJECT 已设置为 Google Cloud 项目的 ID。
disableCache	布尔值	可选参数。决定是否停用缓存。缓存默认处于启用状态，可在请求期间缓存结果。
limit	数值	可选参数。用于更改查询返回的结果数上限，默认值为 5。
transaction	字符串	可选参数。从 Firestore.runTransaction() 中检索的值。标记要在事务中使用的操作。

示例

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

Firestore.runTransaction 函数允许用户以原子方式在 Firestore 中读写数据。如果发生并发写入或其他事务冲突，最多会重试事务两次。如果尝试三次后仍然失败，此 API 会拒绝并抛出错误。如果事务成功，此 API 会针对每次写入操作返回一个可解析为一组文档 ID 的 promise；如果事务失败，此 API 会拒绝并抛出错误。

语法

Firestore.runTransaction(callback[, options]);

参数

参数	类型	说明
callback	函数	一个使用字符串事务 ID 调用的回调函数。事务 ID 可传递到读取/写入/查询 API 调用中。此回调函数必须返回一个 promise。回调函数在失败前最多可运行三次。
options	对象	可选的请求选项。唯一支持的选项为：projectId。系统会忽略未知的选项键。（请参阅下文中的选项部分。）

选项

参数	类型	说明
projectId	字符串	可选参数。是 Google Cloud Platform 项目 ID。如果省略此参数，只要项目 ID 的 access_firestore 权限设置设为 * 或 GOOGLE_CLOUD_PROJECT，系统就会从环境变量 GOOGLE_CLOUD_PROJECT 中检索 projectId。如果服务器容器在 Google Cloud 上运行，则表明 GOOGLE_CLOUD_PROJECT 已设置为 Google Cloud 项目的 ID。

示例

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

错误示例

每个出现错误的 Firestore 函数都将被拒绝，并返回一个包含 reason 键的对象：

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

错误原因包括但不限于 Firestore REST API 错误代码。

相关权限

access_firestore

---

JSON

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

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

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

示例

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

语法

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

相关权限

无。

---

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

参数

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

相关权限

无。

---

Messages

以下 API 可配合使用，以允许在容器的不同部分之间传递消息。

---

addMessageListener

添加一个函数，用于监听特定类型的消息。在使用 sendMessage API 发送该类型的消息（通常是通过代码）时，回调函数将同步运行。通过以下两个参数运行该回调函数：

1. messageType:string
2. message:Object

在客户端中添加回调函数后，该回调函数将跨客户端创建的所有事件接收消息。如果该回调函数应仅接收来自特定事件的消息，可以使用 runContainer API 的 onStart 函数中的 bindToEvent 将此 API 绑定到相应事件。请参阅示例。

语法

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

参数

参数	类型	说明
messageType	字符串	要监听的消息类型。如果值不是字符串，系统会将其强制转换为字符串。
callback	函数	发送属于适用消息类型的消息时要运行的回调函数。如果回调函数不是函数，该 API 将不执行任何操作。

示例

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

相关权限

需要 use_message 权限。此权限必须配置为至少允许以下内容：

• 一种 Usage 为 listen 或 listen_and_send 的消息类型。

---

hasMessageListener

如果已为指定消息类型添加消息监听器，则返回 true。否则，返回 false。

语法

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

相关权限

无。

---

sendMessage

向已注册监听器发送指定类型的消息。此 API 可用于将消息从代码发送回运行容器的客户端。

语法

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

参数

参数	类型	说明
messageType	字符串	要发送的消息类型。如果值不是字符串，系统会将其强制转换为字符串。
message	对象	要发送的消息。如果消息不是对象，该 API 将不执行任何操作。

相关权限

需要 use_message 权限。此权限必须配置为至少允许以下内容：

• 一种 Usage 为 listen_and_send 或 send 的消息类型。

---

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.

---

Promise

返回一个对象，该对象提供与 promise 交互的方法。

promise 的功能等同于 JavaScript promise。每个实例有三种方法，分别返回一个 promise，可在 promise 结束时执行进一步操作：

• .then() - 处理已解析和遭到拒绝的情况。它使用两个回调作为参数：一个用于成功情况，另一个用于失败情况。
• .catch() - 仅处理遭到拒绝的情况，使用一个回调作为参数。
• .finally() - 提供一种代码运行方式，无论 promise 是已解析还是遭到拒绝。使用一个回调作为参数（调用时无需参数）。

返回一个 promise 的变量相当于返回该 promise 的解析值，或者如果该 promise 拒绝，则返回 false。

注意：沙盒化 JS 的 promise 如果未解析，则会在 5 秒后超时（拒绝）。

示例

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

返回满足以下任一条件的 promise：

• 在解析完所有输入后解析，或者
• 在拒绝任一输入后拒绝

语法

Promise.all(inputs);

参数

参数	类型	说明
inputs	数组	一个由值或 promise 构成的数组。如果输入不是 promise，则输入会作为 promise 的解析值进行传递。如果输入不是数组，则会抛出错误。

示例

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

相关权限

无。

Promise.create

创建一个功能等同于 JavaScript promise 的 promise。

语法

Promise.create(resolver);

参数

参数	类型	说明
resolver	函数	一个使用两个函数（resolve 和 reject）调用的函数。返回的 promise 会在调用相应参数后解析或拒绝。如果 resolver 不是一个函数，则会抛出错误。

示例

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

相关权限

无。

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

---