核心 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);
});
關聯權限
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。 |
關聯權限
copyFromWindow
複製 window
物件中的變數。如果 window
中的值無法直接對應至沙箱 JavaScript 支援的類型,系統就會傳回 undefined
。沙箱 JavaScript 支援的八種類型為 null
、undefined
、boolean
、number
、string
、Array
、Object
和 function
。傳回擷取 (及強制轉換) 的值。
語法
copyFromWindow(key)
參數
參數 | 類型 | 說明 |
---|---|---|
key |
string | 用來複製 window 值的鍵。 |
關聯權限
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' 的全域物件,便會擲回例外狀況。 |
關聯權限
createQueue
在 window
中建立陣列 (如果尚未建立),並傳回可將值推送至該陣列的函式。
這個函式需要 access_globals
權限的 arrayKey
讀取及寫入設定。
範例:
const dataLayerPush = createQueue('dataLayer');
dataLayerPush({'currency': 'USD'}, {'event': 'myConversion'});
語法
createQueue(arrayKey)
參數
參數 | 類型 | 說明 |
---|---|---|
arrayKey |
string | 已設定陣列的 window 金鑰 (如果尚不存在)。這個引數支援標準的點號標記法。如果金鑰的路徑不存在,系統會擲回例外狀況。舉例來說,如果 arrayKey 是 'one.two' ,且沒有名為 'one' 的全域物件,便會擲回例外狀況。 |
關聯權限
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();
關聯權限
getCookieValues
傳回所有含指定名稱的 Cookie 值。
語法
getCookieValues(name[, decode])
參數
參數 | 類型 | 說明 |
---|---|---|
name |
string | Cookie 的名稱。 |
decode |
boolean | 控管是否要使用 JavaScript 的
decodeURIComponent() 解碼 Cookie 值。預設值為 true 。 |
關聯權限
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 值。 |
關聯權限
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 |
功能 | 影格成功載入時呼叫。 |
關聯權限
injectScript
在網頁上加入指令碼標記,以非同步方式載入指定網址。這些回呼會以函式執行個體的形式提供,並包裝在可呼叫這些函式的 JavaScript 函式中。
語法
injectScript(url, onSuccess, onFailure[, cacheToken])
參數
參數 | 類型 | 說明 |
---|---|---|
url |
string | 要插入的指令碼位址。 |
onSuccess |
功能 | 指令碼成功載入時呼叫。 |
onFailure |
功能 | 指令碼載入失敗時呼叫。 |
cacheToken |
string | 用來指出應快取指定網址的選用字串。如果指定這個值,系統只會建立一個指令碼元素來要求 JavaScript。如有任何其他嘗試載入,指定的 onSuccess 和 onFailure 方法都會排入佇列,直到指令碼載入為止。 |
關聯權限
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);
關聯權限
範例
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] |
任何 | 引數 |
關聯權限
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()
參數
無。
關聯權限
readTitle
傳回 document.title
的值。
語法
readTitle()
參數
無。
關聯權限
require
依據名稱匯入內建函式。傳回可從程式呼叫的函式或物件。如果瀏覽器不支援內建函式,則傳回「未定義」。
語法
require(name)
參數
參數 | 類型 | 說明 |
---|---|---|
name |
string | 要匯入的函式名稱。 |
範例
const getUrl = require('getUrl');
const url = getUrl();
關聯權限
無。
sendPixel
向指定網址端點發出 GET 要求。
語法
sendPixel(url, onSuccess, onFailure)
參數
參數 | 類型 | 說明 |
---|---|---|
url |
string | 像素的傳送目的地。 |
onSuccess |
功能 | 像素成功載入時呼叫。注意:即使要求成功傳送,瀏覽器仍可能需要有效的圖片回應,才能成功執行。 |
onFailure |
功能 | 在像素無法載入時呼叫。注意事項:即使要求成功傳送,如果伺服器未傳回有效的圖片回應,onFailure 可能會執行。 |
關聯權限
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']
(如果有的話) 設定。
關聯權限
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 中設定值,無論是否有值。 |
關聯權限
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();
關聯權限
範例
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'});