伺服器端標記 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 function 在事件結束時要叫用的函式。

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 function 要呼叫的函式。

相關權限

無。

claimRequest

請在用戶端中使用這個 API 來認領要求。要求聲明後，容器就不會執行其他用戶端。

如果在標記或變數中呼叫這個 API，系統會擲回例外狀況。如果在用戶端傳回後呼叫此 API (例如在 callLater 或 runContainer onComplete 函式等非同步回呼中呼叫)，則會擲回例外狀況。

在呼叫 runContainer API 之前，用戶端應使用此 API 聲明要求。

範例

const claimRequest = require('claimRequest');

claimRequest();

語法

claimRequest();

相關權限

無。

computeEffectiveTldPlusOne

傳回指定網域或網址的有效頂層網域 + 1 (eTLD+1)。系統會根據公開字尾清單的規則，評估網域，並計算出 eTLD+1。eTLD+1 通常是可設定 Cookie 的最高層級網域。

如果引數為空值或未定義，則會傳回未變更的引數值。否則，引數會強制轉換為字串。如果引數不是有效的網域或網址，系統會傳回空白字串。如果伺服器無法擷取公開尾碼清單，則會傳回未經修改的引數值。

範例

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 string 用於計算 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 string 規則運算式的文字。
flags string 選用字串，其中包含要建立的規則運算式旗標。系統支援 `g` (全域) 和 `i` (不區分大小寫)。系統會靜默忽略所有其他字元。

相關權限

無。

圖片最低版本

2.0.0

decodeUri

解碼提供 URI 中的任何已編碼字元。傳回代表已解碼 URI 的字串。如果提供無效的輸入內容，則會傳回 undefined。

範例

const decodeUri = require('decodeUri');

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

語法

decodeUri(encoded_uri);

參數

參數 類型 說明
encoded_uri string 已透過 encodeUri() 或其他方式編碼的 URI。

相關權限

無。

decodeUriComponent

解碼提供的 URI 元件中的任何已編碼字元。傳回代表已解碼 URI 元件的字串。在收到無效輸入內容時，會傳回 undefined。

範例

const decodeUriComponent = require('decodeUriComponent');

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

語法

decodeUriComponent(encoded_uri_component);

參數

參數 類型 說明
encoded_uri_component string 已透過 encodeUriComponent() 或其他方式編碼的 URI 元件。

相關權限

無。

encodeUri

透過轉義特殊字元，傳回已編碼的統一資源 ID (URI)。傳回代表已編碼為 URI 的提供字串的 字串。

範例

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

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

語法

encodeUri(uri);

參數

參數 類型 說明
uri string 完整的 URI。

相關權限

無。

encodeUriComponent

透過轉義特殊字元，傳回已編碼的統一資源 ID (URI)。傳回代表已編碼為 URI 的提供字串的字串。

範例

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

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

語法

encodeUriComponent(str);

參數

參數 類型 說明
str string 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 string 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 number 傳回整數的最低可能值 (含)。
max number 傳回整數的最大可能值 (含最小值)。

相關權限

無。

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 string 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 any 金鑰路徑，其中路徑元件以半形句號分隔。路徑元件可以是物件中的鍵，或是陣列中的索引。如果 keyPath 不是字串，系統會將其強制轉換為字串。

語法

getEventData(keyPath);

相關權限

read_event_data

getGoogleAuth

傳回授權物件，如果與 sendHttpGet 或 sendHttpRequest 搭配使用，就會包含 Google Cloud API 的授權標頭。這個 API 會使用應用程式預設憑證，自動在伺服器環境中尋找憑證。

範例

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

語法

getGoogleAuth(scopes);

參數

參數 類型 說明
scopes 陣列 要申請存取權的 OAuth 2.0 Google API 範圍陣列。

相關權限

需要 use_google_credentials 權限。權限必須搭配一或多個允許的範圍進行設定。

getGoogleScript

從預先設定的一組 Google 指令碼中擷取資源，並傳回含有指令碼和相關快取中繼資料的 promise。

Promise 會解析為包含兩個鍵的物件：script 和 metadata。如果要求失敗，則應許會使用 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 string 劇本名稱。支援的指令碼為 '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 string 適用於使用 gtag 評估 ID 的 'GTAG'，以及使用網站容器 ID 的 'GTM' (例如GTM-XXXX)。
debug any 如果為真，則會要求並傳回評估指令碼的偵錯版本。
timeout number 以毫秒為單位的請求逾時時間。系統會忽略非正值。如果要求逾時，系統會使用 undefined 呼叫回呼，用於指令碼值，並使用 {} 呼叫中繼資料物件。

系統會忽略無法辨識的選項鍵。

相關權限

需要 send_http 權限。權限必須設定為至少允許存取以下項目：

  • 允許 Google 網域

getRemoteAddress

透過讀取 Forwarded 和 X-Forwarded-For 等要求標頭，傳回要求來源 IP 位址的 字串表示法，例如 IPv4 的 12.345.67.890 或 IPv6 的 2001:0db8:85a3:0:0:8a2e:0370:7334。注意：這個 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 string 標頭名稱。這個值不區分大小寫。

相關權限

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 string 查詢參數名稱。

相關權限

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 'string'
number 'number'
布林值 'boolean'
空值 '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 any 輸入值。

相關權限

無。

hmacSha256

使用 SHA-256 搭配雜湊式訊息驗證碼 (HMAC) 計算經過編碼的簽章。預設為 base64url 編碼。

如要使用這個 API，請將伺服器上的 SGTM_CREDENTIALS 環境變數設為 UTF-8 編碼 JSON 金鑰檔案的路徑，格式如下：

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

這些值是 Base64 編碼的 HMAC 金鑰。JSON 文字開頭不得為位元順序標記。

範例

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

語法

hmacSha256(data, keyId, options)

參數

參數 類型 說明
data string 用於計算 HMAC 值的資料。
keyId 字串 JSON 金鑰檔案中的金鑰 ID，用於參照要使用的金鑰。
options 物件 選用 API 設定。(請參閱下方的「選項」)。

選項

選項 類型 說明
outputEncoding 字串 指定傳回值的編碼格式。支援的格式為 hex、base64 或 base64url。如未指定，預設值為 base64url。

相關權限

use_custom_private_keys

圖片最低版本

1.0.0

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 控制台的 記錄檔探索工具中。在 Logs Explorer 中執行查詢 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 string 資料欄名稱，其值會成為轉換後的 Map 中的鍵。
valueColumnName string 資料欄名稱，其值會成為轉換後的 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:xyz@example.com:8080/foo?param=val%2Cue#bar');

語法

parseUrl(url);

參數

參數 類型 說明
url string 要剖析的完整網址。

相關權限

無。

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 function 在所有代碼完成觸發後，系統會叫用這個回呼。
onStart function 在代碼開始觸發之前立即叫用的回呼。

相關權限

run_container

sendEventToGoogleAnalytics

使用通用事件資料傳送單一事件至 Google Analytics，並傳回承諾，該承諾會解析為具有 location 鍵的物件，或拒絕具有 reason 鍵的物件。目的地 Google Analytics 4 是根據事件資料中的評估 ID 而定。

location 欄位會設為 location 標頭 (如有)。

範例

const logToConsole = require('logToConsole');
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();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

語法

sendEventToGoogleAnalytics(event);

參數

參數 類型 說明
event 物體 以統一結構定義格式呈現的事件。

相關權限

需要 send_http 權限。權限必須設定為至少允許存取以下項目：

  • 允許 Google 網域

sendHttpGet

向指定網址傳送 HTTP GET 要求，並傳回 promise，在要求完成或逾時時，會以結果解析。

解析結果是包含三個索引鍵的物件：statusCode、headers 和 body。如果要求失敗 (例如網址無效、沒有主機路徑、SSL 協商失敗等)，承諾會拒絕，並傳回 {reason: 'failed'}。如果已設定 timeout 選項，且要求逾時，則承諾會拒絕，並顯示以下訊息：{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 string 要求的網址。
options 物件 選用要求選項。(請參閱下方的「選項」)。

選項

選項 類型 說明
headers string 其他要求標頭。
timeout 數字 要求中止前的逾時時間，以毫秒為單位。預設值為 15000。
authorization 物件 選用授權物件，來自對 getGoogleAuth 的呼叫，用於在提出對 googleapis.com 的要求時，加入授權標頭。

相關權限

send_http

sendHttpRequest

向指定網址提出 HTTP 要求，並傳回 promise，在要求完成或逾時時，會透過回應解析。

解析結果是包含三個索引鍵的物件：statusCode、headers 和 body。如果要求失敗 (例如網址無效、沒有主機路徑、SSL 協商失敗等)，承諾會拒絕，並傳回 {reason: 'failed'}。如果已設定 timeout 選項，且要求逾時，則承諾會拒絕，並顯示以下訊息：{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 string 要求的網址。
options 物件 選用要求選項。(請參閱下方的「選項」)。
body string 選用要求主體。

選項

選項 類型 說明
headers string 其他要求標頭。
method 物體 要求方法。預設值為 GET。
timeout 數字 要求中止前的逾時時間，以毫秒為單位。預設值為 15000。
authorization 物件 選用授權物件，來自對 getGoogleAuth 的呼叫，用於在提出對 googleapis.com 的要求時，加入授權標頭。

相關權限

send_http

sendPixelFromBrowser

向瀏覽器傳送指令，以便將提供的網址載入為 <img> 標記。Google 代碼 (GA4) 和 Google Analytics：GA 事件網站代碼支援此指令通訊協定。您必須設定伺服器容器網址。詳情請參閱操作說明。

如果傳入的要求不支援指令通訊協定，或是回應已刷新，這個 API 會傳回 false。否則，這個 API 會傳回 true。

範例：

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

語法

sendPixelFromBrowser(url)

參數

參數 類型 說明
url string 要傳送至瀏覽器的網址。

相關權限

send_pixel_from_browser

setCookie

使用指定選項設定或刪除 Cookie。

如要刪除 Cookie，您必須設定 Cookie 的路徑和網域，並將過期值指派給該 Cookie，例如 "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 string Cookie 名稱。名稱不區分大小寫。
value string 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 的最大生命週期。這必須是採用世界標準時間格式的日期字串，例如「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 string 要設為回應主體的值。
encoding string 回應主體的字元編碼 (預設為 'utf8')。支援的值包括 'ascii'、'utf8'、'utf16le'、'ucs2'、'base64'、'latin1'、'binary' 和 'hex'。

相關權限

需要 access_response 權限。權限必須設定為至少允許存取以下項目：

  • body

setResponseHeader

在傳回的回應中設定標頭。如果這個 API 先前已設定同名 (不區分大小寫) 的標頭，後續的呼叫會覆寫或清除先前呼叫端設定的值。

請注意，必須呼叫 returnResponse，才能將回應傳回給用戶端。

語法

setResponseHeader(name, value);

參數

參數 類型 說明
name string 標頭名稱。HTTP 標頭名稱不區分大小寫，因此標頭名稱會以小寫顯示。
value 字串 未定義 標頭值。如果為空值或未定義，則會從傳回的回應中清除命名的標頭。

相關權限

需要 access_response 權限。權限必須設定為至少允許存取以下項目：

  • headers

setResponseStatus

設定傳回回應的 HTTP 狀態碼。

請注意，必須呼叫 returnResponse，才能將回應傳回給用戶端。

語法

setResponseStatus(statusCode);

參數

參數 類型 說明
statusCode number 要傳回的 HTTP 狀態碼。

相關權限

需要 access_response 權限。權限必須設定為至少允許存取以下項目：

  • status

sha256

計算輸入內容的 SHA-256 摘要，並以 Base64 編碼的摘要叫用回呼，除非 options 物件指定不同的輸出編碼。

這個 API 簽名和行為與 Web 容器的 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 string 要進行雜湊處理的字串。
onSuccess function 除非 options 物件指定其他輸出編碼，否則會以 Base64 編碼的結果摘要呼叫。
options 物體 選用選項物件，用於指定輸出編碼。如果指定了這個值，物件應包含 outputEncoding 鍵，且值為 base64 或 hex 之一。

相關權限

無。

sha256Sync

計算並傳回以 Base64 編碼的輸入內容 SHA-256 摘要，除非 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 string 要進行雜湊處理的字串。
options 物體 選用選項物件，用於指定輸出編碼。如果指定了這個值，物件應包含 outputEncoding 鍵，且值為 base64 或 hex 之一。

相關權限

無。

templateDataStorage

傳回物件，其中包含用於存取範本資料儲存空間的方法。範本資料儲存空間可讓資料在單一範本的執行作業中共用。儲存在範本資料儲存空間中的資料會持續保留在執行容器的伺服器上。在大多數情況下，會有多個伺服器執行容器，因此將資料儲存在範本資料儲存空間中，並不能保證每個後續要求都能存取資料。

「templateDataStorage」名稱中的「data」是指，這個 API 只能儲存純文字、非函式資料類型。任何傳遞至 API 的函式或函式參照，都會改為儲存為 null。

語法

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。

使用通用旗標建立的規則運算式具有狀態。詳情請參閱 RegExp 說明文件。

範例

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 string 要測試的測試字串。

相關權限

無。

toBase64

將字串以 base64 或 base64url 編碼。預設為 base64 編碼。

語法

toBase64(input, options);

參數

參數 類型 說明
input string 要編碼的字串。
options 物件 選用 API 設定。(請參閱下方的「選項」)。

選項

選項 類型 說明 最低版本
urlEncoding 布林值 如果為 true，結果會使用 base64url 格式編碼。 1.0.0

範例

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

相關權限

無。

BigQuery

傳回提供 BigQuery 函式的物件。

BigQuery.insert 函式可將資料寫入 BigQuery 資料表。它會傳回 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。此外，這個 API 僅支援使用預設資料庫。

Firestore.read

Firestore.read 函式會從 Firestore 文件讀取資料，並傳回一個承諾，該承諾會解析為包含兩個鍵的物件：id 和 data。如果文件不存在，則應許條件會拒絕，並傳回包含 reason 鍵等於 not_found 的物件。

語法

Firestore.read(path[, options]);

參數

參數 類型 說明
path string 文件或集合的路徑。開頭或結尾不得為「/」。
options 物體 選用要求選項。支援的選項包括：projectId、disableCache 和 transaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」)。

選項

參數 類型 說明
projectId string (選用) Google Cloud Platform 專案 ID。如果省略，只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT，系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId。如果伺服器容器在 Google Cloud 上執行，GOOGLE_CLOUD_PROJECT 就會設為 Google Cloud 專案的 ID。
disableCache 布林值 (選用) 決定是否要停用快取。系統預設會啟用快取功能，在要求期間快取結果。
transaction string (選用) 從 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 會傳回承諾，將解析為已新增或修改的文件 ID。如果使用交易選項，API 仍會傳回承諾，但由於寫入作業已分批處理，因此不會包含 ID。

語法

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

參數

參數 類型 說明
path string 文件或集合的路徑。開頭或結尾不得為「/」。
input 物體 要寫入文件的值。如果設定了合併選項，API 就會將輸入內容中的鍵合併至文件中。
options 物體 選用要求選項。支援的選項包括：projectId、merge 和 transaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」)。

選項

參數 類型 說明
projectId string (選用) 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 string (選用) 從 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 文件陣列。Firestore 文件物件與上述 Firestore.read 中列出的相同。如果沒有符合查詢條件的文件，傳回的承諾會解析為空陣列。

語法

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

參數

參數 類型 說明
collection string 集合路徑。開頭或結尾不得為「/」。
queryConditions 陣列 查詢條件的陣列。每個查詢都以陣列的形式提供，其中包含三個值：鍵、運算子和預期值。例如： [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

系統會將條件以「AND」連結，產生查詢結果。如需相容的查詢運算子清單，請參閱 Firestore 的查詢運算子。
options 物體 選用要求選項。支援的選項包括：projectId、disableCache、limit 和 transaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」)。

選項

參數 類型 說明
projectId string (選用) Google Cloud Platform 專案 ID。如果省略，只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT，系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId。如果伺服器容器在 Google Cloud 上執行，GOOGLE_CLOUD_PROJECT 就會設為 Google Cloud 專案的 ID。
disableCache 布林值 (選用) 決定是否要停用快取。系統預設會啟用快取功能，在要求期間快取結果。
limit number (選用) 變更查詢傳回的結果數上限，預設為 5。
transaction string (選用) 從 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 陣列，如果交易失敗，則會拒絕並傳回錯誤。

語法

Firestore.runTransaction(callback[, options]);

參數

參數 類型 說明
callback function 使用字串交易 ID 叫用的回呼。交易 ID 可傳遞至讀取/寫入/查詢 API 呼叫。這個回呼函式「必須」傳回承諾。回呼最多可執行三次，之後就會失敗。
options 物體 選用要求選項。唯一支援的選項是 projectId。系統會忽略不明的選項鍵。(請參閱下方的「選項」)。

選項

參數 類型 說明
projectId string (選用) 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 string 要監聽的訊息類型。如果值不是字串，系統會將其強制轉換為字串。
callback function 傳送適用訊息類型的訊息時要執行的回呼。如果回呼不是函式，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

如果已為指定的訊息類型新增訊息事件監聽器，則傳回「是」。否則傳回 false。

語法

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

相關權限

無。

sendMessage

將指定類型的訊息傳送至已註冊的事件監聽器。這可用於將標記中的訊息傳回執行容器的用戶端。

語法

const sendMessage = require('sendMessage');

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

參數

參數 類型 說明
messageType string 要傳送的訊息類型。如果值不是字串，系統會將其強制轉換為字串。
message 物體 要傳送的訊息。如果訊息不是物件，API 就不會執行任何操作。

相關權限

需要 use_message 權限。權限必須至少設為允許下列項目：

  • 訊息類型，其 Usage 為 listen_and_send 或 send。

Object

傳回提供 Object 方法的物件。

keys() 方法提供標準程式庫 Object.keys() 行為。它會以 for...in... 迴圈相同的順序，傳回指定物件本身可枚舉的屬性名稱陣列。如果輸入值不是物件，系統會將其強制轉換為物件。

values() 方法提供標準程式庫 Object.values() 行為。它會以 for...in... 迴圈的相同順序，傳回指定物件本身可枚舉的屬性值陣列。如果輸入值不是物件，系統會將其強制轉換為物件。

entries() 方法提供標準程式庫 Object.entries() 行為。它會以 for...in... 迴圈的相同順序，傳回指定物件本身可枚舉屬性 [key, value] 組合的陣列。如果輸入值不是物件，系統會將其強制轉換為物件。

freeze() 方法提供標準程式庫 Object.freeze() 行為。已凍結的物件無法再變更；凍結物件後，系統就會防止新增新屬性、移除現有屬性，以及變更現有屬性的值。freeze() 會傳回傳入的相同物件。系統會將原始或空值引數視為已凍結的物件，並傳回該物件。

delete() 方法會提供標準程式庫的刪除運算子行為。除非物件已凍結，否則會從物件中移除指定的鍵。與標準程式庫刪除運算子一樣，如果第一個輸入值 (objectInput) 是未凍結的物件，即使第二個輸入值 (keyToDelete) 指定不存在的鍵，也會傳回 true。在所有其他情況下，它會傳回 false。不過，它與標準程式庫刪除運算子的差異如下：

  • keyToDelete 不能是使用點號分隔的字串，因為這會指定巢狀鍵。
  • delete() 無法用於從陣列中移除元素。
  • delete() 無法用於從全域範圍移除任何屬性。

語法

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

參數

Object.keys

參數 類型 說明
objectInput any 要列舉其鍵的物件。如果輸入內容不是物件，系統會將其強制轉換為物件。

Object.values

參數 類型 說明
objectInput any 要列舉值的物件。如果輸入內容不是物件，系統會將其強制轉換為物件。

Object.entries

參數 類型 說明
objectInput any 要列舉鍵/值組合的物件。如果輸入內容不是物件，系統會將其強制轉換為物件。

Object.freeze

參數 類型 說明
objectInput any 要凍結的物件。如果輸入內容不是物件，系統會將其視為已凍結的物件。

Object.delete

參數 類型 說明
objectInput any 要刪除鍵值的物件。
keyToDelete string 要刪除的頂層鍵。

範例

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 的功能與 JavaScript 承諾相同。每個例項都有三個方法，可傳回 Promise，讓您在 Promise 完成時採取進一步行動：

  • .then() - 處理已解決和已拒絕的案件。它會將兩個回呼做為參數：一個用於成功案例，另一個用於失敗案例。
  • .catch() - 僅處理遭拒案件。將一個回呼做為參數。
  • .finally()：無論承諾是否已解析或遭到拒絕，都會提供執行程式碼的方法。將一個回呼做為參數，且不帶引數即可叫用。

傳回承諾的變數等於承諾的解析值，如果承諾遭到拒絕，則為 false。

範例

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.all(inputs);

參數

參數 類型 說明
inputs 陣列 值或承諾的陣列。如果輸入內容不是承諾，系統會將輸入內容傳遞，就好像是承諾的解析值一樣。如果輸入值不是陣列，系統會擲回錯誤。

範例

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 function 這個函式會使用兩個函式 (resolve 和 reject) 來叫用。在叫用對應參數時，系統會解析或拒絕傳回的承諾。如果解析器不是函式，則會擲回錯誤。

範例

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 string 要檢查的 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 any 在流暢檢查中使用的值。
opt_message string 斷言失敗時要列印的選用訊息。

比對器

Matcher 說明
isUndefined() 斷言主體為 undefined。
isDefined() 斷言主體不是 undefined。
isNull() 斷言主體為 null。
isNotNull() 斷言主體不是 null。
isFalse() 斷言主體為 false。
isTrue() 斷言主體為 true。
isFalsy() 斷言主體為假值。值為 undefined、null、false、NaN、0 和 '' (空字串) 為假值。
isTruthy() 斷言主體為真。值為 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 string 選用錯誤訊息文字。

範例

fail('This test has failed.');

mock

mock API 可讓您覆寫沙箱 API 的行為。模擬 API 可安全地用於範本程式碼，但只能在測試模式下運作。系統會在每次測試執行前重設模擬資料。

語法

mock(apiName, returnValue);

參數

參數 類型 說明
apiName string 要模擬的 API 名稱；與傳遞至 require() 的字串相同
returnValue any 要傳回的 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 string 要模擬的 API 名稱；與傳遞至 require() 的字串相同
objectMock 物體 要傳回的 API 值，或代替 API 呼叫的函式。必須是物件。

範例

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

runCode

在目前的測試環境中，使用指定的輸入資料物件，執行範本的程式碼，也就是「Code」分頁中的內容。

語法

runCode(data)

參數

參數 類型 說明
data 物體 在測試中使用的資料物件。

傳回值

針對變數範本傳回變數的值；針對所有其他範本類型傳回 undefined。

範例

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