自訂範本 API

核心 API

這些 API 可搭配採用沙箱機制的 JavaScript，在 Google Tag Manager 中建立自訂範本。每個 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 function 在指定同意聲明類型的狀態變更時執行的函式。

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

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

關聯權限

access_consent 權限，具有同意類型的讀取權限。

addEventCallback

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

語法

addEventCallback(callback)

參數

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

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

copyFromDataLayer

傳回目前指派至資料層中指定鍵的值：如果指定鍵為基本類型、函式或物件常值，則傳回指定鍵的值；如果不是，則傳回 undefined。

語法

copyFromDataLayer(key[, dataLayerVersion])

參數

參數 類型 說明
key string 以「a.b.c」格式顯示的鍵。
dataLayerVersion number 選用的資料層版本。預設值為 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

透過轉義特殊字元，傳回已編碼的統一資源 ID (URI)。傳回代表以 URI 編碼的提供字串的字串。如果提供無效的輸入內容 (單一代理字)，則會傳回 undefined。

範例：

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

語法

encodeUri(uri)

參數

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

關聯權限

無。

encodeUriComponent

透過轉義特殊字元，傳回已編碼的統一資源 ID (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 number 所傳回整數的潛在最低值。
max number 傳回整數的潛在值上限。

相關權限

無。

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 布林值 控制是否要使用 JavaScript 的 decodeURIComponent() 解碼 Cookie 值。預設值為 true。

相關權限

get_cookies

getQueryParameters

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

語法

getQueryParameters(queryKey[, retrieveAll])

參數

參數 類型 說明
queryKey string 從查詢參數讀取的鍵。
retrieveAll 布林值 是否要擷取所有值。

舉例來說，如果目前的網址為 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 布林值 是否要擷取所有值。

舉例來說，如果參照網址為 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 'undefined'
null 'null'
true 'boolean'
12 'number'
'string' 「string」
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

關聯權限

無。

getUrl

傳回字串，代表目前網址的全部或部分內容，並提供元件類型和一些設定參數。

語法

getUrl(component)

參數

參數 類型 說明
component string 從網址傳回的元件。必須是 protocol、host、port、path、query、extension、fragment 其中之一。如果元件是 undefined、null，或不符合上述任一元件，系統會傳回整個 href 值。

相關權限

get_url

gtagSet

將 gtag 組合指令推送至資料層，以便在目前事件和觸發的任何代碼處理完畢 (或代碼處理逾時) 後盡快處理。系統會保證在資料層佇列中的任何已排隊項目之前，先在這個容器中處理更新。

舉例來說，如果代碼是在同意聲明初始化時觸發，則更新會在初始化事件處理前套用。例如 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 function 成功載入指令碼時會呼叫。
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 any 要轉換的值。如果值不是字串，系統會將輸入內容強制轉換為字串。

JSON.stringify

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

範例

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] any 引數

相關權限

logging

makeInteger

將指定值轉換成數字 (整數)。

語法

makeInteger(value)

參數

參數 類型 說明
value any 要轉換的值。

相關權限

無。

makeNumber

將指定值轉換為數字。

語法

makeNumber(value)

參數

參數 類型 說明
value any 要轉換的值。

相關權限

無。

makeString

以字串形式傳回指定值。

語法

makeString(value)

參數

參數 類型 說明
value any 要轉換的值。

相關權限

無。

makeTableMap

將含有兩個資料欄的簡易表格物件轉換為 Map。這可用於將包含兩個欄的 SIMPLE_TABLE 範本欄位變更為更易於管理的格式。

例如，這個函式可以轉換資料表物件：

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

轉換成地圖：

{
  'k1': 'v1',
  'k2': 'v2'
}

傳回 Object：如果已將鍵/值組合新增至該物件，則傳回已轉換的 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 any 要列舉其鍵的物件。如果輸入內容不是物件，系統會將其強制轉換為物件。

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

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

範例

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

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

查詢允許及限縮的權限。傳回 布林值：如果已授予權限，則為 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

依名稱匯入內建函式。傳回可從程式呼叫的函式或物件。如果瀏覽器不支援內建函式，則會傳回 undefined。

語法

require(name)

參數

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

範例

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

相關權限

無。

sendPixel

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

語法

sendPixel(url, onSuccess, onFailure)

參數

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

相關權限

send_pixel

setCookie

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

語法

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

參數

參數 類型 說明
name string Cookie 的名稱。
value string Cookie 的值。
options 物體 指定網域、路徑、到期時間、Max-Age、Secure 和 SameSite 屬性。(請參閱下方的「選項」)。
encode 布林值 控制是否要使用 JavaScript 的 encodeURIComponent() 編碼 Cookie 值。預設值為 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 的格式。
  • Secure：由 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 每個同意類型的值都可以設為 `"granted" (已同意) 或 `"denied" (拒絕)。除了 `"granted" (已同意) 以外的任何值都會視為 `"denied" (拒絕)。將值設為 `undefined` 不會對其先前的值造成任何影響。
region 陣列 可選的區域代碼陣列，指定同意聲明設定適用的區域。區域代碼會以 ISO 3166-2 格式，使用國家/地區和/或子區域來表示。
wait_for_update number 指定毫秒值，用於控制資料傳送前等待的時間長度。與非同步載入的同意聲明工具搭配使用。

相關權限

access_consent 權限，具備 consentSettings 物件中所有同意聲明類型的寫入權限。

setInWindow

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

語法

setInWindow(key, value, overrideExisting)

參數

參數 類型 說明
key string window 中的索引鍵，用於放置值。
value * 要在 window 中設定的值。
overrideExisting 布林值 此標記表示應在 window 中設定值，無論是否有值皆然。

關聯權限

access_globals

sha256

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

範例：

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 function 除非 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 每種類型的同意聲明值可設為「授予」或「拒絕」。 系統會將「granted」以外的任何值視為「denied」。將此值設為「未定義」，不會影響先前的值。

關聯權限

access_consent 權限，可對 consentSettings 物件中的所有同意類型提供寫入存取權。

測試 API

這些 API 可搭配沙箱 JavaScript 測試，在 Google 代碼管理工具中建立自訂範本的測試。這些測試 API 不需要 require() 陳述式。進一步瞭解自訂範本測試。

assertApi

傳回比對器物件，可用於流暢地對指定 API 做出斷言。

語法

assertApi(apiName)

參數

參數 類型 說明
apiName string 要檢查的 API 名稱；與傳遞至 require() 的字串相同。

比對器

  • Subject.wasCalled()
  • Subject.wasNotCalled()
  • Subject.wasCalledWith(...expected)
  • Subject.wasNotCalledWith(...expected)

範例

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

assertThat

assertThat API 是以 Google [Truth] 程式庫為範本。它會傳回可用於流暢地對主體值做出斷言的物件。斷言失敗會立即停止測試，並將其標示為失敗。不過，如果某項測試失敗，其他測試案例不會受到影響。

語法

assertThat(actual, opt_message)

參數

參數 類型 說明
actual any 在流暢檢查中使用的值。
opt_message string 斷言失敗時要列印的選用訊息。

比對器

Matcher 說明
isUndefined() 斷言主體為 undefined。
isDefined() 斷言主體不是 undefined。
isNull() 斷言主體為 null。
isNotNull() 斷言主體不是 null。
isFalse() 斷言主體為 false。
isTrue() 斷言主體為 true。
isFalsy() 斷言主體為假值。值為 undefined、null、false、NaN、0 和 '' (空字串) 為假值。
isTruthy() 斷言主旨為「悲劇性」。值為 undefined、null、false、NaN、0 和 '' (空字串) 為假值。
isNaN() 斷言主體為 NaN 值。
isNotNaN() 斷言主體是 NaN 以外的任何值。
isInfinity() 斷言主體是正無窮或負無窮。
isNotInfinity() 斷言主體是正無限大或負無限大以外的任何值。
isEqualTo(expected) 聲明主旨等於指定的值。這是值比較，而非參照比較。物件和陣列的內容會以遞迴方式進行比較。
isNotEqualTo(expected) 斷言主體不等於指定值。此為值比較，而非參照比較。系統會遞迴比較物件和陣列的內容。
isAnyOf(...expected) 聲明主體等於指定值之一。這是值比較，而非參照比較。物件和陣列的內容會以遞迴方式進行比較。
isNoneOf(...expected) 斷言主體不等於任何指定值。這是值比較，而非參照比較。物件和陣列的內容會以遞迴方式進行比較。
isStrictlyEqualTo(expected) 斷言主體與指定值完全相等 (===)。
isNotStrictlyEqualTo(expected) 斷言主體不等於指定值 (!==)。
isGreaterThan(expected) 在有序比較中，斷言主體大於 (>) 指定的值。
isGreaterThanOrEqualTo(expected) 在排序比較中，斷言主體大於或等於 (>=) 指定值。
isLessThan(expected) 在排序比較中，斷言主體小於 (<) 指定的值。
isLessThanOrEqualTo(expected) 在有序比較中，斷言主體小於或等於 (<=) 指定的值。
contains(...expected) 斷言主體是包含任何指定值 (不限順序) 的陣列或字串。這是值比較，而非參照比較。物件和陣列的內容會以遞迴方式比較。
doesNotContain(...expected) 斷言主體是不含任何指定值的陣列或字串。這是值比較，而非參照比較。物件和陣列的內容會以遞迴方式進行比較。
containsExactly(...expected) 斷言主體是陣列，其中包含所有指定值 (以任何順序)，且不包含其他值。這是值比較，而非參照比較。系統會遞迴比較物件和陣列的內容。
doesNotContainExactly(...expected) 斷言主體是陣列，且陣列內的值與指定值不同時，且值的順序不限。這是值比較，而非參照比較。系統會遞迴比較物件和陣列的內容。
hasLength(expected) 斷言主體是具有指定長度的陣列或字串。如果值不是陣列或字串，斷言一律會失敗。
isEmpty() 斷言主體為空白 (長度 = 0) 的陣列或字串。如果值不是陣列或字串，斷言一律會失敗。
isNotEmpty() 斷言主體是陣列或非空字串 (長度 > 0)。如果值不是陣列或字串，斷言一律會失敗。
isArray() 斷言主體的類型為陣列。
isBoolean() 斷言主題的類型為布林值。
isFunction() 斷言主體的類型為函式。
isNumber() 斷言主體的類型為數字。
isObject() 斷言主體的類型為物件。
isString() 斷言主體的類型是字串。

範例

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

立即失敗目前的測試，並顯示指定訊息 (如有提供)。

語法

fail(opt_message);

參數

參數 類型 說明
opt_message string 選用錯誤訊息文字。

範例

fail('This test has failed.');

mock

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

語法

mock(apiName, returnValue);

參數

參數 類型 說明
apiName string 要模擬的 API 名稱；與傳遞至 require() 的字串相同
returnValue 任何 要傳回的 API 值，或代替 API 呼叫的函式。如果 returnValue 是函式，系統會呼叫該函式，而非沙箱 API；如果 returnValue 是函式以外的任何項目，系統會傳回該值，而非沙箱 API。

範例

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

mockObject

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

語法

mockObject(apiName, objectMock);

參數

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

範例

const storage = {};
mockObject('localStorage', {
  setItem: (key, value) => {storage[key] = value;},
  getItem: (key) => storage[key],
});

runCode

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

語法

runCode(data)

參數

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

傳回值

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

範例

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