自訂範本 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)

參數

系統叫用監聽器時，會將變更的同意聲明類型和該類型的新值傳遞給監聽器：

相關聯的權限

access_consent 權限，並具備同意聲明類型的讀取權限。

addEventCallback

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

語法

addEventCallback(callback)

參數

eventData 物件包含下列資料：

範例

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)

參數

範例

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

參數

相關聯的權限

access_globals，並啟用 execute 權限。

callLater

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

語法

callLater(function)

參數

copyFromDataLayer

傳回目前在資料層中指派給指定鍵的值：如果指定鍵的值是原始型別、函式或物件常值，則傳回該值；否則傳回 undefined。

語法

copyFromDataLayer(key[, dataLayerVersion])

參數

相關聯的權限

read_data_layer

copyFromWindow

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

語法

copyFromWindow(key)

參數

相關聯的權限

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)

參數

相關聯的權限

access_globals

createQueue

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

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

範例：

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

語法

createQueue(arrayKey)

參數

相關聯的權限

access_globals

decodeUri

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

範例：

const decode = require('decodeUri');

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

語法

decodeUri(encoded_uri)

參數

相關聯的權限

無。

decodeUriComponent

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

範例：

const decode = require('decodeUriComponent');

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

語法

decodeUriComponent(encoded_uri_component)

參數

相關聯的權限

無。

encodeUri

傳回已編碼的統一資源 ID (URI)，並逸出特殊字元。傳回代表所提供字串的 字串，該字串已編碼為 URI。如果輸入內容無效 (單一替代字元)，則傳回 undefined。

範例：

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

語法

encodeUri(uri)

參數

相關聯的權限

無。

encodeUriComponent

傳回已編碼的統一資源 ID (URI)，並逸出特殊字元。傳回代表所提供字串的 字串，該字串已編碼為 URI。如果輸入內容無效 (單一替代字元)，則傳回 undefined。

範例：

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

語法

encodeUriComponent(str)

參數

相關聯的權限

無。

fromBase64

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

語法

fromBase64(base64EncodedString)

參數

範例

const fromBase64 = require('fromBase64');

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

相關聯的權限

無

generateRandom

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

語法

generateRandom(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])

參數

相關聯的權限

get_cookies

getQueryParameters

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

語法

getQueryParameters(queryKey[, 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])

參數

舉例來說，如果參照網址為 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])

參數

相關聯的權限

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

getTimestamp

已淘汰。建議使用 getTimestampMillis。

傳回 number，代表自 Unix 紀元以來經過的毫秒數，與 Date.now() 傳回的值相同。

語法

getTimestamp();

相關聯的權限

無。

getTimestampMillis

傳回 number，代表自 Unix 紀元以來經過的毫秒數，與 Date.now() 傳回的值相同。

語法

getTimestampMillis();

相關聯的權限

無。

getType

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

語法

getType(data.someField)

注意事項

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

相關聯的權限

無。

getUrl

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

語法

getUrl(component)

參數

相關聯的權限

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)

參數

相關聯的權限

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)

參數

相關聯的權限

inject_hidden_iframe

injectScript

在網頁中加入指令碼標記，以非同步方式載入指定網址。回呼會以函式例項的形式提供，並包裝在 JavaScript 函式中，透過這些函式呼叫回呼。

語法

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

參數

相關聯的權限

inject_script

isConsentGranted

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

如果同意聲明類型已設為「已授予」或完全未設定，系統會視為已取得該同意聲明類型。如果同意聲明類型設為任何其他值，系統會視為未取得同意。

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

範例：

const isConsentGranted = require('isConsentGranted');

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

語法

isConsentGranted(consentType)

參數

相關聯的權限

access_consent 權限，並具備同意聲明類型的讀取權限。

JSON

傳回提供 JSON 函式的物件。

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

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

語法

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

參數

JSON.parse

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

參數

相關聯的權限

logging

makeInteger

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

語法

makeInteger(value)

參數

相關聯的權限

無。

makeNumber

將指定值轉換為數字。

語法

makeNumber(value)

參數

相關聯的權限

無。

makeString

以字串形式傳回指定值。

語法

makeString(value)

參數

相關聯的權限

無。

makeTableMap

將含有兩欄的簡單表格物件轉換為 Map。這項功能可將兩欄的 SIMPLE_TABLE 範本欄位轉換為更易於管理的格式。

舉例來說，這個函式可以轉換表格物件：

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

地圖：

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

傳回 Object：如果已將鍵/值組合新增至 Map，則傳回轉換後的 Map，否則傳回 null。

語法

makeTableMap(tableObj, keyColumnName, valueColumnName)

參數

相關聯的權限

無。

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() 方法提供標準程式庫 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

Object.values

Object.entries

Object.freeze

Object.delete

範例

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

參數

相關聯的權限

無。

queryPermission

查詢允許和縮減的權限。傳回 boolean：如果已授予權限，則為 true；否則為 false。

語法

queryPermission(permission, functionArgs*)

參數

函式引數

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

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

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

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

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

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

相關聯的權限

無。

readAnalyticsStorage

擷取儲存的 Analytics 資料，並傳回含有 client_id 和 sessions 的物件。

• client_id：代表用於 Analytics 的用戶端 ID 的字串。
• sessions：物件陣列，內含目前工作階段的相關資訊。每個物件都包含：
  • measurement_id：代表 Analytics 目的地評估 ID 的字串。
  • session_id：代表時間戳記的字串，用於識別目前的工作階段。
  • session_number：代表使用者在目前工作階段之前啟動的工作階段數。

語法

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

參數

相關聯的權限

read_analytics_storage

範例

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

傳回 document.characterSet 的值。

語法

readCharacterSet()

參數

無。

相關聯的權限

read_character_set

readTitle

傳回 document.title 的值。

語法

readTitle()

參數

無。

相關聯的權限

read_title

require

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

語法

require(name)

參數

範例

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

相關聯的權限

無。

sendPixel

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

語法

sendPixel(url, onSuccess, onFailure)

參數

相關聯的權限

send_pixel

setCookie

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

語法

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

參數

選項

• 網域：由 options['domain'] 屬性設定 (如有)。將這個值設為 'auto'，即可根據文件位置，嘗試使用盡可能廣泛的網域寫入 Cookie。如果失敗，系統會嘗試較窄的子網域。如果上述方法都失敗，系統會嘗試寫入不含網域的 Cookie。如未設定任何值，系統會嘗試寫入 Cookie，但不指定網域。注意：如果寫入 document.cookie 的 Cookie 未指定網域，使用者代理程式會將 Cookie 的網域預設為目前文件位置的主機。
• 路徑：由 options['path'] 設定 (如有)。如果寫入 document.cookie 的 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 物件會將任意同意聲明類型字串對應至 'granted' 或 'denied'。支援的值如下：

相關聯的權限

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

setInWindow

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

語法

setInWindow(key, value, overrideExisting)

參數

相關聯的權限

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)

參數

相關聯的權限

無。

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)

參數

範例

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 物件會將任意同意聲明類型字串對應至 'granted' 或 'denied'。支援的值如下：

相關聯的權限

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

測試 API

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

assertApi

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

語法

assertApi(apiName)

參數

比對器

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

參數

比對器

範例

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

參數

範例

fail('This test has failed.');

mock

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

語法

mock(apiName, returnValue);

參數

範例

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

mockObject

mockObject API 可讓您覆寫傳回物件的 Sandboxed API 行為。您可以在範本程式碼中使用這個 API，但只能在測試模式下運作。系統會在每次執行測試前重設模擬。

語法

mockObject(apiName, objectMock);

參數

範例

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

runCode

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

語法

runCode(data)

參數

傳回值

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

範例

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