伺服器端標記 API

本文件概要說明適用於伺服器端代碼的 API。


addEventCallback

註冊一個回呼函式,該函式會在事件結束時叫用。事件的所有標記執行完畢後,系統就會叫用回呼。回呼會傳遞兩個值:叫用函式的容器 ID,以及包含事件相關資訊的物件。

在標記中使用這個 API 時,系統會將該 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 會擲回例外狀況 (例如在非同步回呼中呼叫,例如在 callLaterrunContainer 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

建立新的 regex 執行個體,並將其包裝在物件中。您無法直接存取規則運算式。不過,您可以將其傳入 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

傳回與 sendHttpGetsendHttpRequest 搭配使用的授權物件,將會包含 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 Array 用來要求存取權的 OAuth 2.0 Google API 範圍陣列。

關聯權限

必須具備 use_google_credentials 權限。權限必須設定一或多個允許的範圍。


getGoogleScript

從預先決定的一組 Google 指令碼擷取資源,並傳回具有指令碼和關聯快取中繼資料的「promise」

這項承諾會解析為包含兩個鍵的物件:scriptmetadata。如果要求失敗,承諾會拒絕並顯示 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',以及 'GTM' 和網站容器 ID (例如GTM-XXXX)。
debug 任何 如果 truthy,就會要求並傳回評估指令碼的偵錯版本。
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 權限。權限必須設為允許至少存取:

  • 標題 ForwardedX-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 字串 JSON 金鑰檔案中的金鑰 ID 是指要使用的金鑰。
options object 選用 API 設定。(請參閱下方的選項)。

選項

選項 類型 說明
outputEncoding 字串 指定回傳值的編碼格式。支援的格式為 hexbase64base64url。若未指定,則預設值為 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 控制台的「記錄檔探索工具」中。如要查看這個 API 建立的記錄項目,請在記錄檔探索工具中執行查詢 logName =~ "stdout"

範例

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 清除先前由其他範本設定的回應,包括 setCookiesetPixelResponsesetResponseBodysetResponseHeadersetResponseStatus。預設值為 HTTP 狀態碼 200、空白內文,且沒有標頭。

建議您透過用戶端範本使用這個 API。

語法

returnResponse();

範例

請參閱 runContainer 範例

關聯權限

return_response


runContainer

執行事件範圍內的容器邏輯 (變數、觸發條件、代碼)。 如果在容器執行期間呼叫這個 API,系統就會再次執行容器。

onCompleteonStart 回呼會收到名為 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 要求,並傳回在要求完成或逾時後解析結果的 promise

已解析的結果是一個包含三個索引鍵的物件:statusCodeheadersbody。如果要求失敗 (例如網址無效、沒有主機路徑、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 要求,並傳回 promise,並在要求完成或逾時後與回應解析。

已解析的結果是一個包含三個索引鍵的物件:statusCodeheadersbody。如果要求失敗 (例如網址無效、沒有主機路徑、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 (分析):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 屬性:domainexpiresfallbackDomainhttpOnlymax- agepathsecuresameSite。(請參閱下方的選項)。
noEncode boolean 如為 true,系統不會編碼 Cookie 值。預設值為 false

  • domain:要接收 Cookie 的主機。如果設為特殊值「auto」,系統就會自動使用下列策略計算主機:

    • Forwarded 標頭的 eTLD+1 (如果有的話)。
    • X-Forwarded-Host 標頭的 eTLD+1 (如果有的話)。
    • Host 標頭的 eTLD+1。
  • expires:Cookie 的效期上限。這必須是世界標準時間格式的日期字串,例如「週六, 1985 08:21:00 GMT」。如果同時設定 expiresmax-age,系統會優先採用 max-age

  • httpOnly:如果 true,會禁止 JavaScript 存取 Cookie。

  • max-age:Cookie 到期前的秒數。零或負數都會立即使 Cookie 失效。如果同時設定 expiresmax-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 string 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 string 要雜湊處理的字串。
onSuccess 功能 除非 options 物件指定其他輸出編碼,否則使用產生的摘要呼叫,並以 Base64 編碼。
options 物件 Optional 選項物件,用於指定輸出編碼。如有指定,物件應包含索引鍵 outputEncoding,值為 base64hex

關聯權限

無。


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,值為 base64hex

關聯權限

無。


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 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。如果省略此屬性,只要專案 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 物件 選用的要求選項。支援的選項為:ignoreUnknownValuesskipInvalidRows。系統會忽略不明的選項鍵。(請參閱下方的「選項」一節)。

參數 類型 說明
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」

Firestore.read

Firestore.read 函式會讀取 Firestore 文件中的資料,並傳回「承諾」,可解析為包含兩個索引鍵的物件:iddata。如果文件不存在,承諾會拒絕並透過包含 reason 鍵且等於 not_found 的物件拒絕。

語法

Firestore.read(path[, options]);

參數 類型 說明
path string 文件或集合的路徑。開頭或結尾不得為「/」。
options 物件 選用要求選項。支援的選項為:projectIddisableCachetransaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」一節)。

參數 類型 說明
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 物件 選用要求選項。支援的選項為:projectIdmergetransaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」一節)。

參數 類型 說明
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 中所列的相同。如果沒有符合查詢條件的文件,傳回的 promise 會解析為空白陣列。

語法

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

參數 類型 說明
collection string 集合的路徑。開頭或結尾不得為「/」。
queryConditions 陣列 查詢條件的陣列。每個查詢都會以包含三個值的陣列形式:keyoperatorexpectedValue。E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]。

系統會運用「AND」結合條件來建立查詢結果。如需相容的查詢運算子清單,請參閱 Firestore 的查詢運算子
options 物件 選用要求選項。支援的選項為:projectIddisableCachelimittransaction。系統會忽略不明的選項鍵。(請參閱下方的「選項」一節)。

參數 類型 說明
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 呼叫。這個回呼函式必須傳回 promise。回呼可能會執行最多三次,否則會失敗。
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 權限。權限必須設為允許的最低權限:

  • Usagelistenlisten_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 權限。權限必須設為允許的最低權限:

  • Usagelisten_and_sendsend 的訊息類型。

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() - 無論承諾已解決或遭到拒絕,提供程式碼執行的方式。使用一個回呼做為使用無引數叫用的參數。

傳回 promise 的變數等於承諾的解析值,而如果承諾拒絕,則傳回 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.create(resolver);

參數

參數 類型 說明
resolver 功能 使用兩個函式叫用的函式:解析和拒絕。叫用對應的參數時,傳回的 promise 將會解析或拒絕。如果解析器不是函式,就會擲回錯誤。

範例

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() 聲明拍攝主體只是正常。Falsy 值為 undefinednullfalseNaN、0 和「'」(空字串)。
isTruthy() 斷言主旨為強人情。Falsy 值為 undefinednullfalseNaN、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() 斷言主體是空白的陣列或字串 (length = 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 可讓您覆寫 Sandboxed API 的行為。模擬 API 可以安全用於範本程式碼,但在測試模式下則無法運作。系統會在每次執行測試前重設模擬畫面。

語法

mock(apiName, returnValue);

參數

參數 類型 說明
apiName string 要模擬的 API 名稱;傳遞至 require() 的字串
returnValue 任何 API 的傳回值,或是呼叫的函式 (用來取代 API)。如果 returnValue 是函式,系統會呼叫該函式來取代沙箱版 API;如果 returnValue 是函式以外的任何項目,則會傳回該值,以取代 Sandboxed 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'});