自訂範本 API

核心 API

這些 API 會與沙箱 JavaScript 搭配運作，在 Google 代碼管理工具中建構自訂範本。每個 API 都會透過 require() 陳述式新增，例如：

const myAPI = require('myAPI');

addConsentListener

註冊要在指定同意聲明類型的狀態變更時執行的事件監聽器函式。

每當指定的同意聲明類型狀態從拒絕變為授予，或從授予變更為拒絕時，系統都會叫用指定事件監聽器。系統會將沒有狀態的同意聲明類型視為已授予，因此如果未設定的同意聲明類型更新為授予，系統就不會呼叫事件監聽器。事件監聽器函式將負責確保程式碼執行適當的次數。

範例：

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

語法

addConsentListener(consentType, listener)

參數

參數 類型 說明
consentType string 要監聽狀態變更的同意聲明類型。
listener 功能 指定同意聲明類型的狀態變更時要執行的函式。

叫用事件監聽器後，系統會傳遞正在變更的同意聲明類型，以及該同意聲明類型的新值：

參數 類型 說明
consentType string 要變更的同意聲明類型。
granted boolean 如果指定的同意聲明類型變更為「授予」，布林值則為 true。

關聯權限

具有同意聲明類型的 access_consent 權限。

addEventCallback

addEventCallback API 可讓您註冊回呼函式，該函式會在事件結束時叫用。事件的所有標記都執行完畢，或達到網頁事件逾時時，系統就會叫用回呼。回呼會傳遞兩個值，分別是叫用函式的容器 ID，以及包含事件相關資訊的物件。

語法

addEventCallback(callback)

參數

參數 類型 說明
callback 功能 事件結束時要叫用的函式。

eventData 物件包含下列資料：

鍵名 類型 說明
tags 陣列 標記資料物件的陣列。事件期間觸發的每個代碼都會在這個陣列中都有項目。標記資料物件內含標記的 ID (id)、執行狀態 (status) 和執行時間 (executionTime)。標記資料也會包含標記設定的其他標記中繼資料。

範例

addEventCallback(function(ctid, eventData) {
  logToConsole('Tag count for container ' + ctid + ': ' + eventData['tags'].length);
});

關聯權限

read_event_metadata

aliasInWindow

aliasInWindow API 可讓您建立別名 (例如 window.foo = window.bar)，以支援需要別名的特定標記。在 fromPath 中找到的 window 物件中的值，指派給 toPath 物件中 window 的鍵。如果成功，會傳回 true，否則會傳回 false。

語法

aliasInWindow(toPath, fromPath)

參數

參數 類型 說明
toPath string window 物件中以點分隔的路徑，應複製值。路徑中直到最後一個元件為止的所有元件都必須已存在於 window 物件中。
fromPath string 指向要複製的值，以點分隔的 window 路徑。如果這個值不存在，作業就會失敗。

範例

aliasInWindow('foo.bar', 'baz.qux')

關聯權限

toPath 和 fromPath 都需要 access_globals；toPath 需要寫入權限，fromPath 則需要讀取權限。

callInWindow

可讓您透過受政策控管的方式，從 window 物件的路徑呼叫函式。使用指定的引數呼叫 window 內指定路徑的函式，然後傳回該值。如果傳回類型無法直接對應至沙箱 JavaScript 支援的類型，系統就會傳回 undefined。沙箱 JavaScript 支援的八種類型為 null、undefined、boolean、number、string、Array、Object 和 function。如果指定路徑不存在，或未參照函式，系統會傳回 undefined。

語法

callInWindow(pathToFunction, argument [, argument2,... argumentN])

參數

參數 類型 說明
pathToFunction string 用於呼叫 window 中函式的路徑 (以點分隔)。
args * 要傳遞至函式的引數。

關聯權限

access_globals已啟用 execute 權限。

callLater

排程對函式的呼叫安排以非同步方式進行。目前程式碼傳回後，系統就會呼叫這個函式。這相當於 setTimeout(<function>, 0)。

語法

callLater(function)

參數

參數 類型 說明
function 功能 要呼叫的函式。

copyFromDataLayer

傳回目前指派給資料層中特定鍵的值：如果是原始類型、函式或物件常值，會在指定鍵中找到的值，反之則傳回 undefined。

語法

copyFromDataLayer(key[, dataLayerVersion])

參數

參數 類型 說明
key string 金鑰格式為「a.b.c」。
dataLayerVersion 數字 選用的資料層版本。預設值為 2。強烈建議不要使用值 1。

關聯權限

read_data_layer

copyFromWindow

複製 window 物件中的變數。如果 window 中的值無法直接對應至沙箱 JavaScript 支援的類型，系統就會傳回 undefined。沙箱 JavaScript 支援的八種類型為 null、undefined、boolean、number、string、Array、Object 和 function。傳回擷取 (及強制轉換) 的值。

語法

copyFromWindow(key)

參數

參數 類型 說明
key string 用來複製 window 值的鍵。

關聯權限

access_globals

createArgumentsQueue

建立填入引數物件的佇列，以支援需要該引數的標記解決方案。

使用 fnKey 引數 (語意與 createQueue 相同) 在全域範圍 (例如 window) 中建立函式。建立函式後，這個 API 會使用 arrayKey 引數，在 window 內建立陣列 (如果尚未存在)。

呼叫 fnKey 下建立的函式時，系統會將其引數物件推送至 arrayKey 下建立的陣列。API 的傳回值是在 fnKey 下建立的函式。

這個函式需要 access_globals 權限的 fnKey 和 arrayKey 讀取及寫入設定。

範例：

const gtag = createArgumentsQueue('gtag', 'dataLayer');
gtag('set', {'currency': 'USD'});

語法

createArgumentsQueue(fnKey, arrayKey)

參數

參數 類型 說明
fnKey string 函式設定的 window 路徑 (如果尚未存在)。這個引數支援標準的點號標記法。如果金鑰的路徑不存在，系統會擲回例外狀況。也就是說，如果 fnKey 是 'one.two'，就會擲回例外狀況。
arrayKey string 已設定陣列的 window 路徑 (如果尚未存在)。這個引數支援標準的點號標記法。如果金鑰的路徑不存在，系統會擲回例外狀況。也就是說，如果 arrayKey 是 'one.two'，且沒有名為 'one' 的全域物件，便會擲回例外狀況。

關聯權限

access_globals

createQueue

在 window 中建立陣列 (如果尚未建立)，並傳回可將值推送至該陣列的函式。

這個函式需要 access_globals 權限的 arrayKey 讀取及寫入設定。

範例：

const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});

語法

createQueue(arrayKey)

參數

參數 類型 說明
arrayKey string 已設定陣列的 window 金鑰 (如果尚不存在)。這個引數支援標準的點號標記法。如果金鑰的路徑不存在，系統會擲回例外狀況。舉例來說，如果 arrayKey 是 'one.two'，且沒有名為 'one' 的全域物件，便會擲回例外狀況。

關聯權限

access_globals

decodeUri

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

範例：

const decode = require('decodeUri');

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

語法

decodeUri(encoded_uri)

參數

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

關聯權限

無。

decodeUriComponent

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

範例：

const decode = require('decodeUriComponent');

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

語法

decodeUriComponent(encoded_uri_component)

參數

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

關聯權限

無。

encodeUri

透過逸出特殊字元，傳回經過編碼的統一資源識別碼 (URI)。傳回字串，代表編碼為 URI 的提供字串。提供無效的輸入 (孤立的代理值) 時，傳回 undefined。

範例：

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

語法

encodeUri(uri)

參數

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

關聯權限

無。

encodeUriComponent

透過逸出特殊字元，傳回經過編碼的統一資源識別碼 (URI)。傳回字串，代表編碼為 URI 的提供字串。提供無效的輸入 (孤立的代理值) 時，傳回 undefined。

範例：

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

語法

encodeUriComponent(str)

參數

參數 類型 說明
str string URI 的元件。

關聯權限

無。

fromBase64

fromBase64 API 可讓您從 Base64 表示法解碼字串。如果提供的輸入內容無效，則傳回 undefined。

語法

fromBase64(base64EncodedString)

參數

參數 類型 說明
base64EncodedString string Base64 編碼字串。

範例

const fromBase64 = require('fromBase64');

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

關聯權限

無

generateRandom

傳回指定範圍內的隨機數字 (整數)。

語法

generateRandom(min, max)

參數

參數 類型 說明
min 數字 傳回整數的潛在最小值。
max 數字 所傳回整數的潛在值上限。

關聯權限

無。

getContainerVersion

傳回包含目前容器相關資料的物件。傳回的物件包含下列欄位：

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

範例

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

語法

getContainerVersion();

關聯權限

read_container_data

getCookieValues

傳回所有含指定名稱的 Cookie 值。

語法

getCookieValues(name[, decode])

參數

參數 類型 說明
name string Cookie 的名稱。
decode boolean 控管是否要使用 JavaScript 的 decodeURIComponent() 解碼 Cookie 值。預設值為 true。

關聯權限

get_cookies

getQueryParameters

傳回目前網址的 queryKey 的第一個或所有參數。傳回 queryKey 的第一個值或 queryKey 值的陣列。

語法

getQueryParameters(queryKey[, retrieveAll])

參數

參數 類型 說明
queryKey string 用來讀取查詢參數的鍵。
retrieveAll boolean 是否要擷取所有值。

舉例來說，如果目前的網址是 https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo，則：

  • getQueryParameters('var') == 'foo'
  • getQueryParameters('var', false) == 'foo'
  • getQueryParameters('var', null) == 'foo'
  • getQueryParameters('var', true) == ['foo', 'foo2', 'foo']

關聯權限

get_url 必須允許 query 元件，且必須在允許的查詢鍵中指定 queryKey (或允許任何查詢鍵)。

getReferrerQueryParameters

getReferrerQueryParameters API 的運作方式與 getQueryParameters 相同，但對參照網址的行為不同，而非目前網址。傳回指定參照網址 queryKey 的第一個或所有參數。傳回 queryKey 的第一個值或 queryKey 值的陣列。

語法

getReferrerQueryParameters(queryKey[, retrieveAll])

參數

參數 類型 說明
queryKey string 用來讀取查詢參數的鍵。
retrieveAll boolean 是否要擷取所有值。

舉例來說，如果參照網址為 https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo，則：

  • getReferrerQueryParameters('var') == 'foo'
  • getReferrerQueryParameters('var', false) == 'foo'
  • getReferrerQueryParameters('var', null) == 'foo'
  • getReferrerQueryParameters('var', true) == ['foo', 'foo2', 'foo']

關聯權限

get_referrer 必須允許 query 元件，且必須在允許的查詢鍵中指定 queryKey (或允許任何查詢鍵)。

getReferrerUrl

針對元件類型，API 會讀取參照網址的文件物件，並傳回代表部分參照網址的字串。如未指定元件，則會傳回完整的參照網址。

語法

getReferrerUrl([component])

參數

參數 類型 說明
component string 要從網址傳回的元件。可以是下列任一值：protocol、host、port、path、query、extension。如果 component 為 undefined、null 或與其中一個元件不符，會傳回完整的網址。

關聯權限

get_referrer 必須允許 query 元件，且必須在允許的查詢鍵中指定 queryKey (或允許任何查詢鍵)。

getTimestamp

已淘汰。建議使用 getTimestampMillis。

傳回數字，代表自 Unix 紀元以來的目前時間 (以毫秒為單位)，由 Date.now() 傳回。

語法

getTimestamp();

關聯權限

無。

getTimestampMillis

傳回數字，代表自 Unix 紀元以來的目前時間 (以毫秒為單位)，由 Date.now() 傳回。

語法

getTimestampMillis();

關聯權限

無。

getType

傳回說明指定值類型的字串。與 typeof 不同，getType 區分 array 和 object。

語法

getType(data.someField)

備忘錄

下表列出每個輸入值傳回的字串。

輸入值 結果
undefined 未定義
null 「null」
true 'boolean'
12 「number」
'string' 「string」
{ a: 3 } 「object」
[ 1, 3 ] 「陣列」
(x) => x + 1 「function」

關聯權限

無。

getUrl

傳回代表目前網址全部或部分字串的字串，並指定元件類型以及一些設定參數。

語法

getUrl(component)

參數

參數 類型 說明
component string 要從網址傳回的元件。必須是 protocol、host、port、path、query、extension、fragment 其中之一。如果元件為 undefined、null 或與這些元件不相符，則會傳回整個 href 值。

關聯權限

get_url

gtagSet

將 gtag set 指令推送至資料層，以便在目前事件和觸發的任何代碼都處理完畢後 (或已達代碼處理逾時)，盡快進行處理。系統一定會先在這個容器中處理更新，再到資料層佇列中的任何項目排入佇列。

舉例來說，如果代碼由依據「同意聲明初始化」觸發，系統會在處理初始化事件前套用更新。範例可以設為 ads_data_redaction 設為 true、false，或是 url_passthrough 設為 true 或 false。

例如：

const gtagSet = require('gtagSet');

gtagSet({
  'ads_data_redaction': true,
  'url_passthrough': true,
});

語法

gtagSet(object)

參數

參數 類型 說明
Object 物體 針對所含屬性更新全域狀態的物件。

關聯權限

write_data_layer 會檢查所有指定金鑰的 dataLayer 寫入權限。如果輸入至 gtagSet 是純物件，API 會檢查該物件中所有合併金鑰的寫入權限 (例如針對 gtagSet({foo: {bar: 'baz'}}))，API 會檢查對 foo.bar 的寫入權限。

如果 gtagSet 的輸入是金鑰和某些非純物件值，API 會檢查該金鑰的寫入權限 (例如，如果是 gtagSet('abc', true) ，API 會檢查對 'abc' 的寫入權限)。

請注意，如果輸入物件中設有循環，則系統只會檢查抵達相同物件前的鍵。

injectHiddenIframe

在網頁中加入隱藏的 iframe。

回呼會以函式執行個體的形式提供，並包裝在 JavaScript 函式中，以便呼叫這些例項。

語法

injectHiddenIframe(url, onSuccess)

參數

參數 類型 說明
url string 要做為 iframe src 屬性值的網址。
onSuccess 功能 影格成功載入時呼叫。

關聯權限

inject_hidden_iframe

injectScript

在網頁上加入指令碼標記，以非同步方式載入指定網址。這些回呼會以函式執行個體的形式提供，並包裝在可呼叫這些函式的 JavaScript 函式中。

語法

injectScript(url, onSuccess, onFailure[, cacheToken])

參數

參數 類型 說明
url string 要插入的指令碼位址。
onSuccess 功能 指令碼成功載入時呼叫。
onFailure 功能 指令碼載入失敗時呼叫。
cacheToken string 用來指出應快取指定網址的選用字串。如果指定這個值，系統只會建立一個指令碼元素來要求 JavaScript。如有任何其他嘗試載入，指定的 onSuccess 和 onFailure 方法都會排入佇列，直到指令碼載入為止。

關聯權限

inject_script

isConsentGranted

如果同意指定的同意聲明類型，則傳回 true。

如果同意聲明類型設為「已授予」或完全不設定，系統會將特定同意聲明類型的同意聲明視為已授予。如果同意聲明類型設為任何其他值，系統就不會將其視為不允許。

代碼管理工具使用者介面提供「一律觸發」選項。如果設為一律啟用的代碼使用此 API，則系統會將同意聲明視為已授予，且無論同意聲明的實際狀態為何，系統都會傳回 true。

範例：

const isConsentGranted = require('isConsentGranted');

if (isConsentGranted('ad_storage')) {
  sendFullPixel();
} else {
  sendPixelWithoutCookies();
}

語法

isConsentGranted(consentType)

參數

參數 類型 說明
consentType string 要檢查狀態的同意聲明類型。

關聯權限

具有同意聲明類型的 access_consent 權限。

JSON

傳回提供 JSON 函式的物件。

parse() 函式會剖析 JSON 字串，以建構字串描述的值或物件。如果無法剖析值 (例如格式錯誤的 JSON)，函式會傳回 undefined。如果輸入值不是字串，系統會將輸入強制轉換為字串。

stringify() 函式會將輸入內容轉換為 JSON 字串。如果系統無法剖析這個值 (例如物件有週期)，該方法會傳回 undefined。

語法

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

參數

JSON.parse

參數 類型 說明
stringInput 任何 要轉換的值。如果值不是字串，系統會將輸入強制轉換為字串。

JSON.stringify

參數 類型 說明
值 任何 要轉換的值。

範例

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

localStorage

以存取本機儲存空間的方法傳回物件。

語法

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

關聯權限

access_local_storage

範例

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

將引數記錄至瀏覽器控制台。

語法

logToConsole(obj1 [, obj2,... objN])

參數

參數 類型 說明
obj1 [, obj2,... objN] 任何 引數

關聯權限

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 中會變為值。

關聯權限

無。

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

參數

數學函式參數會轉換為數字。

關聯權限

無。

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.

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 要剖析的完整網址。

關聯權限

無。

queryPermission

查詢已允許和縮小的權限。傳回boolean：如果獲得權限，則傳回 true，否則傳回 false。

語法

queryPermission(permission, functionArgs*)

參數

參數 類型 說明
permission string 權限的名稱。
functionArgs 任何 函式引數會因查詢的權限而異。請參閱下方的函式引數。

函式引數

sendPixel、injectScript、injectHiddenIframe：第二個參數應為網址字串。

writeGlobals、readGlobals：第二個參數應為寫入或讀取的索引鍵。

readUrl：不需要其他引數即可查詢整個網址是否可以讀取。如要查詢特定元件是否可以讀取，請將元件名稱做為第二個引數傳遞：

if (queryPermission('readUrl','port')) {
  // read the port
}

如要檢查特定查詢鍵是否可讀取，請將查詢金鑰做為第三個參數傳遞：

if (queryPermission('readUrl','query','key')) {
  getUrlComponent(...);
}

關聯權限

無。

readCharacterSet

傳回 document.characterSet 的值。

語法

readCharacterSet()

參數

無。

關聯權限

read_character_set

readTitle

傳回 document.title 的值。

語法

readTitle()

參數

無。

關聯權限

read_title

require

依據名稱匯入內建函式。傳回可從程式呼叫的函式或物件。如果瀏覽器不支援內建函式，則傳回「未定義」。

語法

require(name)

參數

參數 類型 說明
name string 要匯入的函式名稱。

範例

const getUrl = require('getUrl');
const url = getUrl();

關聯權限

無。

sendPixel

向指定網址端點發出 GET 要求。

語法

sendPixel(url, onSuccess, onFailure)

參數

參數 類型 說明
url string 像素的傳送目的地。
onSuccess 功能 像素成功載入時呼叫。注意：即使要求成功傳送，瀏覽器仍可能需要有效的圖片回應，才能成功執行。
onFailure 功能 在像素無法載入時呼叫。注意事項：即使要求成功傳送，如果伺服器未傳回有效的圖片回應，onFailure 可能會執行。

關聯權限

send_pixel

setCookie

設定或刪除具有指定名稱、值和選項的 Cookie。

語法

setCookie(name, value[, options, encode])

參數

參數 類型 說明
name string Cookie 的名稱。
value string Cookie 的值。
options 物體 指定 Domain、Path、expiration、Max-Age、Secure 和 SameSite 屬性。(請參閱下方的「選項」)。
encode boolean 控制 Cookie 值是否使用 JavaScript 的 encodeURIComponent() 編碼。預設值為 true。

  • 網域：由 options['domain'] 屬性設定 (如有)。將這個值設為 'auto'，嘗試根據文件位置，使用範圍最廣的網域寫入 Cookie。如果失敗，就會逐步縮小子網域。如果這些方法都失敗，會嘗試在沒有網域的情況下寫入 Cookie。如未設定任何值，這個動作會嘗試在沒有指定網域的情況下寫入 Cookie。注意：當未指定網域的 Cookie 寫入 document.cookie 時，使用者代理程式會將 Cookie 的網域預設為目前文件位置的主機。
  • 「Path」：由 options['path'] (如果有的話) 設定。將未指定路徑的 Cookie 寫入 document.cookie 時，使用者代理程式會預設將 Cookie 的路徑預設為目前文件位置的路徑。
  • Max-Age：由 options['max-age'] (如果有的話) 設定。
  • 有效期限：由 options['expires'] 設定 (如果有的話)。如有的話，則必須是世界標準時間格式的日期字串。Date.toUTCString() 可用來為這個參數的 Date 設定格式。
  • 安全：由 options['secure'] (如果有的話) 設定。
  • SameSite：由 options['samesite'] (如果有的話) 設定。

關聯權限

set_cookies

setDefaultConsentState

將預設的同意聲明更新推送到資料層，以便在目前事件和其觸發的任何代碼都處理完畢後 (或已達代碼處理逾時)，盡快進行處理。系統保證會先在這個容器中處理更新，再於資料層中處理任何已排入佇列的項目。進一步瞭解同意聲明。

範例：

const setDefaultConsentState = require('setDefaultConsentState');

setDefaultConsentState({
  'ad_storage': 'denied',
  'analytics_storage': 'granted',
  'third_party_storage': 'denied',
  'region': ['US-CA'],
  'wait_for_update': 500
});

語法

setDefaultConsentState(consentSettings)

參數

參數 類型 說明
consentSettings 物體 定義指定同意聲明類型預設狀態的物件。

consentSettings 物件是任意同意聲明類型字串與 'granted' 或 'denied' 之一的對應關係。它支援下列值：

鍵名 類型 說明
consentType string 每種同意聲明類型的值都能設為「授予」或「拒絕」。 「授予」以外的任何值將視為「拒絕」。 將值設為「未定義」並不會影響其先前的值。
region 陣列 選用的區碼陣列，用於指定同意聲明設定要套用的區域。區碼是以 ISO 3166-2 格式，以國家/地區和/或子行政區表示。
wait_for_update 數字 指定毫秒值，控制資料傳送前的等待時間。與以非同步方式載入的同意聲明工具搭配使用。

關聯權限

具備 consentSettings 物件內所有同意聲明類型的 access_consent 權限。

setInWindow

設定 window 中的指定鍵指定值。根據預設，如果已有值，這個方法就不會設定 window 中的值。將 overrideExisting 設為 true，即可設定 window 中的值，無論現有值是否存在。傳回「布林值」boolean：如果值成功設定，就會傳回 true，否則傳回 false。

語法

setInWindow(key, value, overrideExisting)

參數

參數 類型 說明
key string 用於放置值的 window 鍵。
value * 要在 window 中設定的值。
overrideExisting boolean 這個標記表示應在 window 中設定值，無論是否有值。

關聯權限

access_globals

sha256

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

範例：

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

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

語法

sha256(input, onSuccess, onFailure = undefined, options = undefined)

參數

參數 類型 說明
input string 要計算雜湊的字串。
onSuccess 功能 除非 options 物件指定其他輸出編碼，否則使用產生的摘要呼叫，並以 Base64 編碼。
onFailure 功能 如果計算摘要時發生錯誤，或瀏覽器未原生支援 sha256，就會呼叫此方法。系統會使用包含錯誤名稱和訊息的物件呼叫回呼。
options 物體 Optional 選項物件，用於指定輸出編碼。如有指定，物件應包含鍵 outputEncoding，且值為 base64 或 hex。

關聯權限

無。

templateStorage

傳回具有存取範本儲存空間的方法的物件。範本儲存空間可讓您在執行單一範本的所有執行作業之間共享資料。儲存在範本儲存空間中的資料，在網頁的整個生命週期內都會保留下來。

語法

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

關聯權限

access_template_storage

範例

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

toBase64 API 可讓您將字串編碼為 Base64 表示法。

語法

toBase64(input)

參數

參數 類型 說明
input string 要編碼的字串。

範例

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

關聯權限

無

updateConsentState

將同意聲明更新推送到資料層，供系統在目前事件和觸發的任何代碼處理完畢 (或達到代碼處理逾時後) 後盡快進行處理。系統會先在這個容器中處理更新，再於資料層中處理任何已排入佇列的項目。進一步瞭解同意聲明。

範例：

const updateConsentState = require('updateConsentState');

updateConsentState({
  'ad_storage': 'granted',
  'analytics_storage': 'denied',
  'third_party_storage': 'granted',
});

語法

updateConsentState(consentSettings)

參數

參數 類型 說明
consentSettings 物體 可更新指定同意聲明類型狀態的物件。

consentSettings 物件是任意同意聲明類型字串與 'granted' 或 'denied' 之一的對應關係。它支援下列值：

鍵名 類型 說明
consentType string 每種同意聲明類型的值都可以設為「已授予」或「拒絕」。 系統會將「授予」以外的任何值視為「拒絕」。將值設為「未定義」不會對其先前的值產生任何影響。

關聯權限

具備 consentSettings 物件內所有同意聲明類型的 access_consent 權限。

測試 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 值為 undefined、null、false、NaN、0 和「'」(空字串)。
isTruthy() 斷言主旨為強人情。Falsy 值為 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() 斷言主體是空白的陣列或字串 (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'});