伺服器端標記 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 的最高層級網域。

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

範例

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

透過逸出特殊字元傳回經過編碼的統一資源識別碼 (URI)。傳回代表以 URI 編碼的提供字串的字串。

範例

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

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

語法

encodeUri(uri);

參數

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

關聯權限

無。

---

encodeUriComponent

透過逸出特殊字元傳回經過編碼的統一資源識別碼 (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	數字	傳回整數的潛在潛在值下限 (含)。
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	string	Cookie 的名稱。
noDecode	boolean	如果為 true，系統就不會在傳回 Cookie 值前解碼 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

---

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 指令碼擷取資源，並傳回包含指令碼和相關快取中繼資料的承諾。

承諾會解析為包含兩個鍵的物件：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	任何	如果壓力，系統就會要求並傳回評估指令碼的偵錯版本。
timeout	數字	要求逾時 (以毫秒為單位)；忽略非正值。如果要求逾時，系統會使用 undefined 叫用指令碼值，針對中繼資料物件使用 {}。

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

關聯權限

必須具備send_http權限。權限必須設為允許至少存取：

• 允許 Google 網域

---

getRemoteAddress

透過讀取要求標頭 (例如 Forwarded 和 X-Forwarded-For) 傳回要求來源 IP 位址的 string (字串)，例如 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'
boolean	'boolean'
空值	'null'
未定義	'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	任何	輸入值。

關聯權限

無。

---

hmacSha256

以 SHA-256 使用雜湊式訊息驗證代碼 (HMAC) 計算編碼簽章。預設值為 base64url 編碼。

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

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

這些值為採用 Base64 編碼的 HMAC 金鑰，

範例

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	string	從 JSON 金鑰檔案中參照所用金鑰的金鑰 ID。
options	object	選用 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 控制台的記錄檔探索工具中查看這些記錄檔。在記錄檔探索工具中執行查詢 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:[e-mail]: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	功能	所有標記都啟動後叫用的回呼。
onStart	功能	在代碼開始觸發之前立即叫用的回呼。

關聯權限

run_container

---

sendEventToGoogleAnalytics

使用常見事件資料將單一事件傳送至 Google Analytics (分析)，並傳回承諾，該金鑰會以 location 鍵解析為物件，或以 reason 鍵拒絕傳遞至物件。目的地 (通用 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 要求，並傳回在要求完成或逾時後以結果解析的承諾。

已解析的結果是一個物件，含有三個鍵：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	object	選填要求選項。(請參閱下方的選項)。

選項

選項	類型	說明
headers	string	其他要求標頭。
timeout	number	取消要求前的逾時時間 (以毫秒為單位)。預設值為 15000。
authorization	object	此為選用的授權物件，指透過呼叫 getGoogleAuth 的方式向 googleapis.com 發出要求時包含授權標頭。

關聯權限

send_http

---

sendHttpRequest

向指定的網址發出 HTTP 要求，並傳回在要求完成或逾時後與回應來解析的承諾。

已解析的結果是一個物件，含有三個鍵：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	object	選填要求選項。(請參閱下方的選項)。
body	string	選填要求主體。

選項

選項	類型	說明
headers	string	其他要求標頭。
method	物體	要求方法。預設值為 GET。
timeout	number	取消要求前的逾時時間 (以毫秒為單位)。預設值為 15000。
authorization	object	此為選用的授權物件，指透過呼叫 getGoogleAuth 的方式向 googleapis.com 發出要求時包含授權標頭。

關聯權限

send_http

---

sendPixelFromBrowser

傳送指令至瀏覽器，以 <img> 標記的形式載入提供的網址。GA4 的 Google 代碼和 Google Analytics (分析)：Google Analytics (分析) 事件網頁代碼都支援這項指令通訊協定。您必須設定伺服器容器網址。詳情請參閱操作說明。

如果傳入的要求不支援指令通訊協定，或回應已清除，這個 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 相同的路徑和網域，並為 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	boolean	如果是 true，系統就不會編碼 Cookie 值。預設值為 false。

• domain：用來接收 Cookie 的主機。如果設為特殊值「auto」，系統將使用下列策略自動計算主機：

  • Forwarded 標頭的 eTLD+1 (如有)。
  • X-Forwarded-Host 標頭的 eTLD+1 (如有)。
  • Host 標頭的 eTLD+1。

• expires：Cookie 的生命週期上限。這必須是世界標準時間格式的日期字串，例如「1985 年 10 月 26 日 08:21:00 GMT」。如果同時設定 expires 和 max-age，系統會優先採用 max-age。

• httpOnly：在 true 的情況下，禁止 JavaScript 存取 Cookie。

• max-age：Cookie 到期前的秒數。如果數字為零或負數，則 Cookie 會立即失效。如果同時設定 expires 和 max-age，系統會優先採用 max-age。

• 路徑：要求網址中必須存在的路徑，否則瀏覽器不會傳送 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	string undefined	標頭值。如果是空值或未定義，則會清除傳回回應中的具名標頭。

關聯權限

必須具備access_response權限。權限必須設為允許存取至少：

• headers

---

setResponseStatus

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

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

語法

setResponseStatus(statusCode);

參數

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

關聯權限

必須具備access_response權限。權限必須設為允許存取至少：

• status

---

sha256

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

這個 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	string	要雜湊的字串。
onSuccess	功能	除非 options 物件指定不同的輸出編碼，否則使用產生的摘要並採用 Base64 編碼。
options	物體	「Optional」選項物件，用於指定輸出編碼。如果有指定，物件應包含 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	物體	「Optional」選項物件，用於指定輸出編碼。如果有指定，物件應包含 outputEncoding 索引鍵，且值為 base64 或 hex。

關聯權限

無。

---

templateDataStorage

傳回具有存取範本資料儲存空間方法的物件。範本資料儲存功能可在執行單一範本時共用資料。範本資料儲存空間中儲存的資料會保留在執行容器的伺服器中。在大部分的情況下，會有多個伺服器執行容器，因此將資料儲存在範本資料儲存空間中，並不保證每個後續要求都能存取資料。

「templateDataStorage」的名稱中的「資料」是指只能利用這個 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。

使用全域旗標建立的規則運算式具有狀態。詳情請參閱 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	object	選用 API 設定。(請參閱下方的選項)。

選項

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

範例

const toBase64 = require('toBase64');

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

關聯權限

無。

---

BigQuery

傳回提供 BigQuery 函式的物件。

BigQuery.insert 函式允許將資料寫入 BigQuery 資料表。在發生錯誤時傳回承諾，表示成功插入或遭拒。

插入成功後，承諾就不會有引數。

插入失敗時，承諾會拒絕內含含有錯誤原因的物件清單，如果發生錯誤，可能還會顯示資料列物件。要求的某些部分可能會順利完成，但其他部分則沒有成功。在這個情況下，承諾會拒絕每個含有資料列物件的資料列錯誤清單，以區分插入的資料列 (請參閱下方的錯誤範例)。詳情請參閱 BigQuery 的錯誤訊息說明文件。

語法

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

參數	類型	說明
connectionInfo	物體	定義連結 BigQuery 資料表的必要資訊。其中有一個選用參數和兩個必要參數： projectId - 選用 Google Cloud Platform 專案 ID。如果省略 projectId，只要專案 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	boolean	如果設為 true，系統會接受與結構定義不相符的資料列。系統會忽略不明的值。預設值為 false。
skipInvalidRows	boolean	如果設為 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。如果文件不存在，承諾就會拒絕含有等於 not_found 的 reason 金鑰的物件。

注意： 根據預設，Firestore.read 會在容器執行期間快取回應。如要停用快取，請參閱下方的選項一節。所有交易期間都會自動停用快取功能。

語法

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	boolean	(選用) 決定是否要停用快取。 快取功能預設為啟用，在要求期間快取結果。
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	boolean	(選用) 如果設為 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 會在容器執行期間快取回應。如要停用快取，請參閱下方的選項一節。所有交易期間都會自動停用快取功能。

注意： Firestore 會自動為每個欄位建立索引。為查詢多個欄位，您可能需要為指定集合建立複合式索引。詳情請參閱 Firestore 的複合式索引說明文件。

語法

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

參數	類型	說明
collection	string	集合的路徑。開頭或結尾不得為「/」。
queryConditions	陣列	查詢條件陣列。每個查詢都會以陣列的形式呈現，並含有三個值：key、operator 和 expectedValue，E.g.: [[‘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	boolean	(選用) 決定是否要停用快取。 快取功能預設為啟用，在要求期間快取結果。
limit	數字	(選用) 變更查詢傳回的結果數量上限，預設為 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	功能	使用字串交易 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	功能	傳送適用訊息類型的訊息時執行的回呼。如果回呼不是函式，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

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

語法

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	任何	要列舉其鍵的物件。如果輸入內容不是物件，就會強制轉換為物件。

Object.values

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

Object.entries

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

Object.freeze

參數	類型	說明
objectInput	任何	要凍結的物件。如果輸入值不是物件，則系統會將其視為凍結物件。

Object.delete

參數	類型	說明
objectInput	任何	要刪除鍵的物件。
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 的方法，讓您在承諾和承諾發生時進一步採取行動：

• .then() - 處理已解決和遭拒的案件。這會使用兩個回呼做為參數：一個用於成功案例，另一個用於失敗情況。
• .catch() - 僅處理遭拒的案件。使用一個回呼做為參數。
• .finally()：讓程式碼執行，無論承諾產品是否已解決或遭拒。將一個回呼當做在沒有引數的情況下叫用的參數。

傳回承諾的變數等於承諾的解析值，或 false (如果承諾拒絕)。

注意： 如果問題仍未解決，採用沙箱機制的 JS 承諾會在五秒後逾時 (拒絕)。

範例

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.create(resolver);

參數

參數	類型	說明
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	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	任何	用於流利檢查的值。
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()	斷言主體為正面或負面 Infinity。
isNotInfinity()	斷言主體為正值或負 Infinity 以外的任何值。
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，但在非測試模式下無法使用模擬 API。系統會在每次測試執行前重設模擬畫面。

語法

mock(apiName, returnValue);

參數

參數	類型	說明
apiName	string	要模擬的 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

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

語法

runCode(data)

參數

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

傳回值

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

範例

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

---