自訂範本 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 布林值 如果指定的同意聲明類型已變更，則為 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')

關聯權限

access_globals 必須同時用於 toPath 和 fromPath；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 引數建立全域範圍 (即 window) 的函式 (語意與 createQueue 相同)。函式建立後，這個 API 會接著 使用 arrayKey 在 window 中建立陣列 (如果尚未建立的話) 引數。

呼叫 fnKey 下建立的函式時，函式會推送引數 新增至 arrayKey 底下建立的陣列中API 的傳回值是 函式是在 fnKey 下建立。

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

範例：

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 中建立陣列 (如果尚未建立的話)，並傳回 則能將值推送到該陣列的函式。

這個函式需要對 arrayKey 上的 access_globals 權限。

範例：

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 經過編碼的 URI encodeUri() 或其他方式

關聯權限

無。

decodeUriComponent

將指定 URI 元件中的任何編碼字元解碼。傳回 字串，代表已解碼的 URI 元件。如果符合以下情況，則傳回 undefined 但因輸入內容無效而供應

範例：

const decode = require('decodeUriComponent');

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

語法

decodeUriComponent(encoded_uri_component)

參數

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

關聯權限

無。

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 布林值 控制是否要使用以下方式解碼 Cookie 值： JavaScript decodeURIComponent()。預設值為 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 相同。 ，差別在於此 ID 是在參照網址 (而不是目前的網址) 上使用。傳回第一個或 指定參照網址 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() 傳回的 Epoch 時間。

語法

getTimestamp();

關聯權限

無。

getTimestampMillis

傳回代表目前時間 (以毫秒為單位自 Unix 開始算起) 的數字 Date.now() 傳回的 Epoch 時間。

語法

getTimestampMillis();

關聯權限

無。

getType

傳回描述指定值類型的字串。與 typeof 不同： getType 可區分 array 和 object。

語法

getType(data.someField)

注意事項

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

輸入值 結果
undefined 「未定義」
null 「null」
true 「boolean」
12 「數字」
'string' 「string」
{ a: 3 } 「object」
[ 1, 3 ] 「array」
(x) => x + 1 函式

關聯權限

無。

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。

特定同意聲明類型的同意聲明狀態視同已授予 (如果使用者同意) 類型已設為「granted」或是根本未設定如果同意聲明類型設為 任何其他值均不會視為未授予。

在代碼管理工具的使用者介面中，代碼設定會提供「一律」選項 觸發。如果啟用「一律啟用」的代碼會使用這個 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() 行為它會傳回指定物件本身的列舉屬性陣列 [key, value] 組合的順序與 for...in... 迴圈相同。如果 輸入值不是物件，系統會將其強制轉換為物件。

freeze() 方法會提供標準程式庫 Object.freeze() 行為不能再變更凍結的物件；凍結了物體 避免新增資源、移除現有資源 現有屬性值維持不變freeze() 會傳回 與所傳入的相同物件原始或空值引數會視為 如果是凍結的物件，系統會傳回該物件

delete() 方法提供標準程式庫刪除運算子 行為除非物件凍結，否則現有的鍵會從物件中移除。 和 Standard Library Delete 運算子一樣，如果第一次輸入，會傳回 true 值 (objectInput) 是不會凍結的物件，即使第二次輸入也同樣不會凍結 值 (keyToDelete) 指定的鍵不存在。它會傳回 false 的 在其他情況下。但與 Standard Library Delete 運算子不同 包括：

  • 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

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

語法

require(name)

參數

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

範例

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

關聯權限

無。

sendPixel

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

語法

sendPixel(url, onSuccess, onFailure)

參數

參數 類型 說明
url string 傳送像素的位置。
onSuccess 功能 像素成功載入時呼叫。注意：即使請求 ，瀏覽器可能需要有效的圖片回應，才能 才能順利執行
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 布林值 控制 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 每個同意聲明類型的值都可以設為「granted」或「denied」。 系統會將「granted」以外的任何值視為「denied」。設定 這個值不會對先前的值產生任何影響。
region 陣列 選用的區域代碼陣列，用於指定 同意聲明設定。區碼以國家/地區表示 和/或子群組 (ISO 3166-2 格式)。
wait_for_update 數字 指定毫秒值，控制資料的等待時間長度 已傳送。搭配以非同步載入方式的同意聲明工具使用。

關聯權限

擁有 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

計算輸入的 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 功能 使用產生的摘要來呼叫，且以 base64 編碼，除非 options 物件會指定不同的輸出編碼。
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」 「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 任何 用於流利檢查的值。
opt_message string 斷言失敗時要列印的選用訊息。

比對器

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

範例

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

fail

立即無法執行目前的測試，並顯示指定訊息 (如有提供)。

語法

fail(opt_message);

參數

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

範例

fail('This test has failed.');

mock

mock API 可讓您覆寫沙箱 API 的行為。模擬圖 您可以在範本程式碼中安全地使用 API，但 API 僅能在測試模式中運作。 系統會在每次測試執行前重設模擬畫面。

語法

mock(apiName, returnValue);

參數

參數 類型 說明
apiName string 要模擬的 API 名稱；與傳遞至 require()
returnValue 任何 要傳回給 API 的值或呼叫的函式，以取代 也能使用 Google Cloud CLI 或 Compute Engine API如果 returnValue 是函式，系統會在以下位置呼叫該函式： 來取代沙箱模式如果 returnValue 是任何其他來源 而不是函式，系統就會傳回該值，以取代沙箱模式 也能使用 Google Cloud CLI 或 Compute Engine API

範例

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

mockObject

mockObject API 可讓您覆寫採用沙箱機制的 API 行為， 會傳回物件。您可以在範本程式碼中安全地使用 API，但 API 確實可以運作 。系統會在每次測試執行前重設模擬畫面。

語法

mockObject(apiName, objectMock);

參數

參數 類型 說明
apiName string 要模擬的 API 名稱；與傳遞至 require()
objectMock 物體 要傳回給 API 的值或呼叫的函式，以取代 也能使用 Google Cloud CLI 或 Compute Engine 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'});