Interfejsy API szablonów niestandardowych

Podstawowe interfejsy API

Te interfejsy API współpracują z JavaScriptem w trybie piaskownicy, aby tworzyć w Menedżerze tagów Google szablony niestandardowe. Każde API jest dodawane za pomocą instrukcji require(), np.:

const myAPI = require('myAPI');

addConsentListener

Rejestruje funkcję listenera do wykonania, gdy zmieni się stan określonego typu zgody.

Określony odbiorca zostanie wywołany za każdym razem, gdy stan określonego typu zgody zmieni się z odrzuconego na przyznany lub z przyznanego na odrzucony. Typ zgody bez stanu jest uznawany za przyznany, więc nie będzie wywoływany, jeśli typ zgody bez stanu zostanie zaktualizowany do stanu „Przyznano”. Funkcje listenera będą odpowiedzialne za to, aby ich kod był uruchamiany odpowiednią liczbę razy.

Przykład:

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

Składnia

addConsentListener(consentType, listener)

Parametry

Parametr Typ Opis
consentType ciąg znaków Typ zgody, na potrzeby którego aplikacja ma nasłuchiwać zmian stanu.
listener function Funkcja do wykonania po zmianie stanu określonego typu zgody.

Gdy wywołysz listenera, zostanie on przekazany do typu zgody, który ulega zmianie, oraz nowej wartości tego typu zgody:

Parametr Typ Opis
consentType ciąg znaków Typ zgody, który ma zostać zmieniony.
granted wartość logiczna Wartość logiczna, która jest prawdą, jeśli wybrany typ zgody jest zmieniany na „Przyznano”.

Powiązane uprawnienia

Uprawnienie access_consent z dostępem do odczytu dla danego typu zgody.

addEventCallback

Interfejs API addEventCallback umożliwia zarejestrowanie funkcji wywołania zwrotnego, która zostanie wywołana po zakończeniu zdarzenia. Wywołanie zwrotne zostanie wywołane, gdy wszystkie tagi związane ze zdarzeniem zostaną wykonane lub gdy zostanie osiągnięty limit czasu zdarzenia na stronie. Do funkcji wywołania zwrotnego przekazywane są 2 wartości: identyfikator kontenera, który wywołuje funkcję, oraz obiekt zawierający informacje o zdarzeniu.

Składnia

addEventCallback(callback)

Parametry

Parametr Typ Opis
callback function Funkcja do wywołania na końcu zdarzenia.

Obiekt eventData zawiera te dane:

Nazwa klucza Typ Opis
tags Tablica Tablica obiektów danych tagów. Każdy tag, który został uruchomiony podczas zdarzenia, będzie miał w tym tablicy swój wpis. Obiekt danych tagu zawiera identyfikator tagu (id), jego stan wykonania (status) i czas wykonania (executionTime). Dane tagu obejmują też dodatkowe metadane tagu skonfigurowane w tagu.

Przykład

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

Powiązane uprawnienia

read_event_metadata

aliasInWindow

Interfejs aliasInWindow API umożliwia tworzenie aliasów (np. window.foo = window.bar), które ułatwiają obsługę niektórych tagów wymagających tworzenia aliasów. Przypisuje wartość obiektu window znalezionego w miejscu fromPath do klucza obiektu window w miejscu toPath. Zwraca wartość true, jeśli operacja się powiedzie, a w przeciwnym razie – false.

Składnia

aliasInWindow(toPath, fromPath)

Parametry

Parametr Typ Opis
toPath ciąg znaków Ścieżka rozdzielona kropkami do obiektu window, do którego należy skopiować wartość. Wszystkie komponenty na ścieżce do ostatniego komponenta muszą już istnieć w obiekcie window.
fromPath ciąg znaków Ścieżka w window do wartości, którą chcesz skopiować, rozdzielona kropkami. Jeśli takiej wartości nie ma, operacja się nie powiedzie.

Przykład

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

Powiązane uprawnienia

access_globals jest wymagane w przypadku zarówno toPath, jak i fromPath; toPath wymaga dostępu do zapisu, a fromPath wymaga dostępu do odczytu.

callInWindow

Umożliwia wywoływanie funkcji z ścieżki obiektu window w sposób kontrolowany przez zasady. Wywołuje funkcję pod podaną ścieżką w window z podanymi argumentami i zwraca wartość. Jeśli typu zwracanego nie można bezpośrednio mapować na typ obsługiwany w piaskownicy JavaScript, zwracana jest wartość undefined. 8 typów obsługiwanych w bezpiecznej piaskownicy JavaScript to: null, undefined, boolean, number, string, Array, Object i function. Jeśli podany ścieżka nie istnieje lub nie odwołuje się do funkcji, zwracana jest wartość undefined.

Składnia

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

Parametry

Parametr Typ Opis
pathToFunction ciąg znaków Ścieżka do funkcji w window, którą chcesz wywołać, rozdzielona kropkami.
args * Argumenty przekazywane do funkcji.

Powiązane uprawnienia

access_globals z włączonym uprawnieniem execute.

callLater

Zaplanuj wywołanie funkcji do wykonania asynchronicznie. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. Jest to równoważne z setTimeout(<function>, 0).

Składnia

callLater(function)

Parametry

Parametr Typ Opis
function function Funkcja do wywołania.

copyFromDataLayer

Zwraca wartość aktualnie przypisaną do danego klucza w warstwie danych: wartość znaleziona w danym kluczu, jeśli jest to typ prymitywny, funkcja lub literałowy obiekt, w przeciwnym razie undefined.

Składnia

copyFromDataLayer(key[, dataLayerVersion])

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w formacie „a.b.c”.
dataLayerVersion liczba Opcjonalna wersja warstwy danych. Wartością domyślną jest 2. Zdecydowanie odradzamy używanie wartości 1.

Powiązane uprawnienia

read_data_layer

copyFromWindow

Kopiuje zmienną z obiektu window. Jeśli wartości w window nie można bezpośrednio przypisać do typu obsługiwanego w odizolowanym środowisku JavaScript, zwracana jest wartość undefined. 8 typów obsługiwanych w sandboxie JavaScript to: null, undefined, boolean, number, string, Array, Object i function. Zwraca pobraną (i przekształconą) wartość.

Składnia

copyFromWindow(key)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w elemencie window, którego wartość chcesz skopiować.

Powiązane uprawnienia

access_globals

createArgumentsQueue

Tworzy kolejkę wypełnioną obiektami argumentów, aby obsługiwać rozwiązania tagów, które tego wymagają.

Tworzy funkcję o zakresie globalnym (czyli window) za pomocą argumentu fnKey (o tej samej semantyce co createQueue). Po utworzeniu funkcji interfejs API tworzy tablicę w obrębie window (jeśli jeszcze nie istnieje) za pomocą argumentu arrayKey.

Gdy wywoływana jest funkcja utworzona w ramach fnKey, przesyła ona swoje argumenty obiektu do tablicy utworzonej w ramach arrayKey. Wartość zwracana przez interfejs API to funkcja utworzona w ramach fnKey.

Ta funkcja wymaga ustawienia odczytu i zapisu dla uprawnień fnKey i arrayKey w przypadku uprawnień access_globals.

Przykład:

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

Składnia

createArgumentsQueue(fnKey, arrayKey)

Parametry

Parametr Typ Opis
fnKey ciąg znaków Ścieżka w window, w której jest skonfigurowana funkcja, jeśli jeszcze nie istnieje. Ten argument obsługuje standardową notację kropkową. Jeśli ścieżka klucza nie istnieje, zostanie wygenerowany wyjątek. Oznacza to, że jeśli fnKey = 'one.two', zostanie zgłoszony wyjątek.
arrayKey ciąg znaków Ścieżka w window, w której jest ustawiony tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardową notację kropkową. Jeśli ścieżka klucza nie istnieje, zostanie wygenerowany wyjątek. Oznacza to, że jeśli arrayKey to 'one.two', a nie ma obiektu globalnego o nazwie 'one', zostanie wyjątek.

Powiązane uprawnienia

access_globals

createQueue

Tworzy tablicę w obiekcie window (jeśli jeszcze nie istnieje) i zwraca funkcję, która wskaże wartości do tej tablicy.

Ta funkcja wymaga ustawienia odczytu i zapisu dla uprawnienia arrayKey.access_globals

Przykład:

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

Składnia

createQueue(arrayKey)

Parametry

Parametr Typ Opis
arrayKey ciąg znaków Klucz w window, w którym jest ustawiony tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardową notację kropkową. Jeśli ścieżka klucza nie istnieje, zostanie wygenerowany wyjątek. Jeśli na przykład arrayKey = 'one.two', a nie ma obiektu globalnego o nazwie 'one', zostanie rzucona wyjątek.

Powiązane uprawnienia

access_globals

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym identyfikatorze URI. Zwraca ciąg tekstowy, który reprezentuje odkodowany identyfikator URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowy argument.

Przykład:

const decode = require('decodeUri');

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

Składnia

decodeUri(encoded_uri)

Parametry

Parametr Typ Opis
encoded_uri ciąg znaków Identyfikator URI zakodowany za pomocą funkcji encodeUri()lub w inny sposób.

Powiązane uprawnienia

Brak.

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie URI. Zwraca ciąg reprezentujący odkodowany komponent identyfikatora URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowe dane wejściowe.

Przykład:

const decode = require('decodeUriComponent');

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

Składnia

decodeUriComponent(encoded_uri_component)

Parametry

Parametr Typ Opis
encoded_uri_component ciąg znaków Komponent identyfikatora URI zakodowany przez encodeUriComponent() lub w inny sposób.

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI, uciekając znaki specjalne. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowe dane wejściowe (samodzielny zastępnik).

Przykład:

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

Składnia

encodeUri(uri)

Parametry

Parametr Typ Opis
uri ciąg znaków Pełny identyfikator URI.

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI, uciekając znaki specjalne. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined, gdy otrzyma nieprawidłowe dane wejściowe (samodzielny zastępnik).

Przykład:

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

Składnia

encodeUriComponent(str)

Parametry

Parametr Typ Opis
str ciąg znaków Składnik adresu URI.

Powiązane uprawnienia

Brak.

fromBase64

Interfejs API fromBase64 umożliwia odkodowanie ciągów znaków z reprezentacji w formacie base64. Zwraca wartość undefined, gdy otrzyma nieprawidłowe dane wejściowe.

Składnia

fromBase64(base64EncodedString)

Parametry

Parametr Typ Opis
base64EncodedString ciąg znaków Ciąg zakodowany w formacie Base64.

Przykład

const fromBase64 = require('fromBase64');

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

Powiązane uprawnienia

Brak

generateRandom

Zwraca losową liczbę (liczbę całkowitą) z podanego zakresu.

Składnia

generateRandom(min, max)

Parametry

Parametr Typ Opis
min liczba Minimalna potencjalna wartość zwracanej liczby całkowitej.
max liczba Maksymalna potencjalna wartość zwracanej liczby całkowitej.

Powiązane uprawnienia

Brak.

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwracany obiekt ma te pola:

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

Przykład

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

Składnia

getContainerVersion();

Powiązane uprawnienia

read_container_data

getCookieValues

Zwraca wartości wszystkich plików cookie o danej nazwie.

Składnia

getCookieValues(name[, decode])

Parametry

Parametr Typ Opis
name ciąg znaków Nazwa pliku cookie.
decode wartość logiczna Określa, czy wartości plików cookie mają być dekodowane za pomocą JavaScriptu: decodeURIComponent(). Domyślna wartość to true.

Powiązane uprawnienia

get_cookies

getQueryParameters

Zwraca pierwszy lub wszystkie parametry bieżącego adresu URL queryKey. Zwraca pierwszą wartość z argumentu queryKey lub tablicę wartości z argumentu queryKey.

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz do odczytania z parametrów zapytania.
retrieveAll wartość logiczna Określa, czy mają zostać pobrane wszystkie wartości.

Jeśli na przykład bieżący adres URL to https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, to:

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

Powiązane uprawnienia

get_url musi zezwalać na komponent query i określać klucz queryKey w sekcji dozwolonych kluczy zapytań (lub zezwalać na dowolny klucz zapytania).

getReferrerQueryParameters

Interfejs getReferrerQueryParameters działa tak samo jak getQueryParameters, z tym że działa na stronie odsyłającej zamiast na bieżącym adresie URL. Zwraca pierwszy lub wszystkie parametry queryKey danego witryny odesłaniającej. Zwraca pierwszą wartość z argumentu queryKey lub tablicę wartości z argumentu queryKey.

Składnia

getReferrerQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz do odczytania z parametrów zapytania.
retrieveAll wartość logiczna Określa, czy mają zostać pobrane wszystkie wartości.

Jeśli np. adres URL strony odsyłającej to 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']

Powiązane uprawnienia

get_referrer musi zezwalać na komponent query i musi określać klucz zapytań queryKey w sekcji dozwolone klucze zapytań (lub zezwalać na dowolny klucz zapytania).

getReferrerUrl

W zależności od typu komponentu interfejs API odczytuje obiekt dokumentu dla odesłania i zwróci ciąg znaków, który reprezentuje część odesłania. Jeśli nie zostanie określony żaden komponent, zwrócony zostanie pełny adres URL strony odsyłającej.

Składnia

getReferrerUrl([component])

Parametry

Parametr Typ Opis
component ciąg znaków Komponent do zwrócenia z adresu URL. Może być jedną z tych wartości:protocol, host, port, path, query, extension. Jeśli parametr component ma wartość undefined, null lub nie pasuje do żadnego z tych komponentów, zwracany jest cały adres URL.

Powiązane uprawnienia

get_referrer musi zezwalać na komponent query i musi określać klucz zapytań queryKey w sekcji dozwolone klucze zapytań (lub zezwalać na dowolny klucz zapytania).

getTimestamp

Wycofany. Używaj funkcji getTimestampMillis.

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od początku epoki Unixa, zwracany przez funkcję Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od początku epoki Unixa, zwracany przez funkcję Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

Zwraca ciąg znaków opisujący typ danej wartości. W przeciwieństwie do typeof funkcja getType rozróżnia wartości array i object.

Składnia

getType(data.someField)

Notes

W tabeli poniżej podano ciągi znaków zwracane dla poszczególnych wartości wejściowych.

Wartość wejściowa Wynik
undefined 'undefined'
null 'null'
true 'boolean'
12 'number'
'string' 'string'
{ a: 3 } 'object'
[ 1, 3 ] 'array'
(x) => x + 1 'function'

Powiązane uprawnienia

Brak.

getUrl

Zwraca ciąg znaków, który reprezentuje cały bieżący adres URL lub jego część, podany typ komponentu oraz niektóre parametry konfiguracji.

Składnia

getUrl(component)

Parametry

Parametr Typ Opis
component ciąg znaków Komponent do zwrócenia z adresu URL. Musi być jedną z tych wartości:protocol, host, port,path, query, extension,fragment. Jeśli komponent to undefined, null lub nie pasuje do żadnego z tych komponentów, zwracana jest cała wartość href.

Powiązane uprawnienia

get_url

gtagSet

Przesyła do warstwy danych polecenie gtag set, które ma zostać przetworzone tak szybko, jak to możliwe po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich wywołanych przez nie tagów (lub po upływie limitu czasu przetwarzania tagów). Zaktualizowana wersja jest przetwarzana w tym kontenerze przed elementami w kolejce na poziomie danych.

Jeśli np. jest wywoływany przez tag uruchamiany po inicjacji zgody, aktualizacja zostanie zastosowana przed przetworzeniem zdarzenia inicjacji. Przykłady: ads_data_redaction ustawiony na true lub false albo url_passthrough ustawiony na true lub false.

Przykłady:

const gtagSet = require('gtagSet');

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

Składnia

gtagSet(object)

Parametry

Parametr Typ Opis
Object object Obiekt, który aktualizuje stan globalny dla swoich właściwości.

Powiązane uprawnienia

write_data_layer sprawdza uprawnienia do zapisu w kluczu dataLayer w przypadku wszystkich określonych kluczy. Jeśli dane wejściowe do gtagSet to zwykły obiekt, interfejs API sprawdzi uprawnienia do zapisu we wszystkich spłaszczonych kluczach w tym obiekcie. Przykładowo w przypadku gtagSet({foo: {bar: 'baz'}}) interfejs API sprawdzi uprawnienia do zapisu w foo.bar.

Jeśli dane wejściowe do gtagSet to klucz i niezwykła wartość obiektu, interfejs API sprawdzi, czy masz uprawnienia do zapisu do tego klucza. Na przykład w przypadku gtagSet('abc', true) interfejs API sprawdzi, czy masz uprawnienia do zapisu do 'abc'.

Pamiętaj, że jeśli w obiekcie wejściowym występuje cykl, sprawdzane są tylko klucze, które prowadzą do tego samego obiektu.

injectHiddenIframe

Dodaje do strony niewidoczny element iframe.

Wywołania zwrotne są podawane jako instancje funkcji i są ujęte w funkcje JavaScriptu, które je wywołują.

Składnia

injectHiddenIframe(url, onSuccess)

Parametry

Parametr Typ Opis
url ciąg znaków Adres URL, który ma być używany jako wartość atrybutu src iframe.
onSuccess function Wywoływany po pomyślnym załadowaniu ramki.

Powiązane uprawnienia

inject_hidden_iframe

injectScript

Dodaje tag skryptu do strony, aby wczytać podany adres URL asynchronicznie. Funkcje wywołania zwrotnego są podawane jako instancje funkcji i opakowane w funkcje JavaScript, które je wywołują.

Składnia

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

Parametry

Parametr Typ Opis
url ciąg znaków Adres skryptu, który ma zostać wstrzyknięty.
onSuccess function Wywoływany po pomyślnym załadowaniu skryptu.
onFailure function Wywoływany, gdy nie uda się załadować skryptu.
cacheToken ciąg znaków Opcjonalny ciąg znaków służący do wskazywania, że dany adres URL powinien zostać zapisany w pamięci podręcznej. Jeśli ta wartość zostanie określona, zostanie utworzony tylko 1 element skryptu, który będzie wysyłać żądanie JavaScript. Każda kolejna próba wczytania spowoduje umieszczenie metod onSuccess i onFailure w kole do wykonania do momentu załadowania skryptu.

Powiązane uprawnienia

inject_script

isConsentGranted

Zwraca wartość „prawda”, jeśli określony typ zgody został przyznany.

Uznaje się, że zgoda na dany typ zgody została udzielona, jeśli dla tego typu zgody ustawiono wartość „Przyznano” lub nie ustawiono jej wcale. Jeśli typ zgody ma dowolną inną wartość, zostanie uznany za niewyrażony.

W interfejsie Menedżera tagów w ustawieniach tagów pojawi się opcja uruchamiania tagu zawsze. Jeśli tag z włączoną opcją zawsze uruchamiaj używa tego interfejsu API, zgoda jest uznawana za udzieloną i zwracana jest wartość true, niezależnie od rzeczywistego stanu zgody.

Przykład:

const isConsentGranted = require('isConsentGranted');

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

Składnia

isConsentGranted(consentType)

Parametry

Parametr Typ Opis
consentType ciąg znaków Typ zgody, którego stan ma być sprawdzany.

Powiązane uprawnienia

Uprawnienie access_consent z dostępem do odczytu dla danego typu zgody.

JSON

Zwraca obiekt, który udostępnia funkcje JSON.

Funkcja parse() analizuje ciąg znaków JSON, aby utworzyć wartość lub obiekt opisany przez ten ciąg. Jeśli nie można przeanalizować wartości (np. ze względu na nieprawidłowy format JSON), funkcja zwróci wartość undefined. Jeśli wartość wejściowa nie jest ciągiem znaków, zostanie ona przekonwertowana na ciąg znaków.

Funkcja stringify() konwertuje dane wejściowe na ciąg znaków w formacie JSON. Jeśli nie można przeanalizować wartości (np. obiekt zawiera cykl), metoda zwróci wartość undefined.

Składnia

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

Parametry

JSON.parse

Parametr Typ Opis
stringInput dowolny Wartość do przekonwertowania. Jeśli wartość nie jest ciągiem znaków, dane wejściowe zostaną skonwertowane na ciąg znaków.

JSON.stringify

Parametr Typ Opis
wartość dowolny Wartość do przekonwertowania.

Przykład

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

Zwraca obiekt z metodami dostępu do pamięci lokalnej.

Składnia

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

Powiązane uprawnienia

access_local_storage

Przykład

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

Loguje argumenty w konsoli przeglądarki.

Składnia

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

Parametry

Parametr Typ Opis
obj1 [, obj2,... objN] dowolny Argumenty

Powiązane uprawnienia

logging

makeInteger

Przekształca podawaną wartość na liczbę (liczbę całkowitą).

Składnia

makeInteger(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeNumber

Przekształca podawaną wartość na liczbę.

Składnia

makeNumber(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeString

Zwraca podana wartość jako ciąg tekstowy.

Składnia

makeString(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do przekonwertowania.

Powiązane uprawnienia

Brak.

makeTableMap

Konwertuje prosty obiekt tabeli z 2 kolumnami na Map. Służy on do zmiany pola szablonu SIMPLE_TABLE z 2 kolumnami na format łatwiejszy do zarządzania.

Funkcja ta może na przykład konwertować obiekt tabeli:

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

na mapie:

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

Zwraca obiekt: przekonwertowany obiekt Map, jeśli dodano do niego pary klucz-wartość, lub null w przeciwnym razie.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametry

Parametr Typ Opis
tableObj Wyświetl listę Obiekt tabeli do przekonwertowania. To lista map, w której każdy wiersz tabeli odpowiada jednemu elementowiMap. Każda nazwa właściwości w obiekcie wiersza jest nazwą kolumny, a wartość właściwości jest wartością kolumny w wierszu.
keyColumnName ciąg znaków Nazwa kolumny, której wartości staną się kluczami w przekształconym pliku.Map
valueColumnName ciąg znaków Nazwa kolumny, której wartości staną się wartościami w konwertowanej kolumnie Map.

Powiązane uprawnienia

Brak.

Math

Obiekt udostępniający funkcje Math.

Składnia

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

Parametry

Parametry funkcji matematycznych są konwertowane na liczby.

Powiązane uprawnienia

Brak.

Object

Zwraca obiekt, który udostępnia metody Object.

Metoda keys() zapewnia zachowanie standardowej biblioteki Object.keys(). Zwraca tablicę nazw właściwości zliczalnych danego obiektu w tym samym porządku, w jakim występuje w pętli for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie skonwertowana na obiekt.

Metoda values() zapewnia zachowanie standardowej biblioteki Object.values(). Zwraca tablicę wartości własnych właściwości zliczalnych danego obiektu w tym samym porządku, w jakim występuje w pętli for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona skonwertowana na obiekt.

Metoda entries() zapewnia zachowanie standardowej biblioteki Object.entries(). Zwraca tablicę par własności enumerable [key, value] danego obiektu w tym samym porządku, w jakim działa pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona skonwertowana na obiekt.

Metoda freeze() zapewnia zachowanie funkcji Object.freeze() z biblioteki standardowej. Obiekt zamrożony nie może już zostać zmieniony. Zamrożenie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących właściwości oraz zmianę wartości istniejących właściwości. freeze() zwraca ten sam obiekt, który został przekazany. Argument typu prymitywnego lub null zostanie potraktowany jak zamrożony obiekt i zwrócony.

Metoda delete() zapewnia zachowanie operatora usuwania biblioteki standardowej. Usuwa z obiektu podany klucz, chyba że obiekt jest zablokowany. Podobnie jak operator usuwania z standardowej biblioteki zwraca true, jeśli pierwsza wartość wejściowa (objectInput) jest obiektem, który nie jest zamrożony, nawet jeśli druga wartość wejściowa (keyToDelete) określa klucz, który nie istnieje. W pozostałych przypadkach zwraca wartość false. Różni się on jednak od operatora usuwania z standardowej biblioteki pod następującymi względami:

  • Wartość keyToDelete nie może być ciągiem znaków oddzielonych kropkami, który określa klucz zagnieżdżony.
  • Funkcji delete() nie można używać do usuwania elementów z tablicy.
  • Za pomocą polecenia delete() nie można usuwać usług z zakresu globalnego.

Składnia

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

Parametry

Object.keys

Parametr Typ Opis
objectInput dowolny Obiekt, którego klucze mają być zliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane do obiektu.

Object.values

Parametr Typ Opis
objectInput dowolny Obiekt, którego wartości mają być zliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane na obiekt.

Object.entries

Parametr Typ Opis
objectInput dowolny Obiekt, którego pary klucz-wartość mają być wyliczane. Jeśli dane wejściowe nie są obiektem, zostaną skonwertowane na obiekt.

Object.freeze

Parametr Typ Opis
objectInput dowolny Obiekt do zamrożenia. Jeśli dane wejściowe nie są obiektem, zostaną potraktowane jako zamrożone.

Object.delete

Parametr Typ Opis
objectInput dowolny Obiekt, którego klucz ma zostać usunięty.
keyToDelete ciąg znaków Klucz najwyższego poziomu, który chcesz usunąć.

Przykład

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

Zwraca obiekt zawierający wszystkie elementy składowe danego adresu URL, podobnie jak obiekt URL.

Ten interfejs API zwróci wartość undefined w przypadku dowolnego nieprawidłowego adresu URL. W przypadku prawidłowo sformatowanych adresów URL pola, których nie ma w ciągu znaków adresu URL, będą miały wartość pustego ciągu znaków. W przypadku pola searchParams będzie to pusty obiekt.

Zwrócony obiekt będzie zawierać te pola:

{
  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,
}

Przykład

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Składnia

parseUrl(url);

Parametry

Parametr Typ Opis
url ciąg znaków Pełny adres URL, który zostanie przeanalizowany.

Powiązane uprawnienia

Brak.

queryPermission

Przeszukaj dozwolone i zawężone uprawnienia. Zwraca wartość logiczną: true, jeśli udzielono uprawnienia, false w przeciwnym razie.

Składnia

queryPermission(permission, functionArgs*)

Parametry

Parametr Typ Opis
permission ciąg znaków Nazwa uprawnienia.
functionArgs dowolny Argumenty funkcji różnią się w zależności od zapytanego uprawnienia. Poniżej znajdziesz argumenty funkcji.

Argumenty funkcji

sendPixel, injectScript, injectHiddenIframe: drugi parametr powinien być ciągiem znaków adresu URL.

writeGlobals, readGlobals: drugim parametrem powinien być klucz, który ma być zapisywany lub odczytywany.

readUrl: nie trzeba podawać żadnych dodatkowych argumentów, aby sprawdzić, czy można odczytać cały adres URL. Aby sprawdzić, czy można odczytać dany komponent, prześlij nazwę komponentu jako drugi argument:

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

Aby sprawdzić, czy określony klucz zapytania jest czytelny, prześlij klucz zapytania jako trzeci parametr:

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

Powiązane uprawnienia

Brak.

readCharacterSet

Zwraca wartość document.characterSet.

Składnia

readCharacterSet()

Parametry

Brak.

Powiązane uprawnienia

read_character_set

readTitle

Zwraca wartość document.title.

Składnia

readTitle()

Parametry

Brak.

Powiązane uprawnienia

read_title

require

Importuje funkcję wbudowaną według nazwy. Zwraca funkcję lub obiekt, które można wywołać z programu. Zwraca undefined, gdy przeglądarka nie obsługuje wbudowanej funkcji.

Składnia

require(name)

Parametry

Parametr Typ Opis
name ciąg znaków Nazwa funkcji do zaimportowania.

Przykład

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

Powiązane uprawnienia

Brak.

sendPixel

Wysyła żądanie GET do określonego punktu końcowego URL.

Składnia

sendPixel(url, onSuccess, onFailure)

Parametry

Parametr Typ Opis
url ciąg znaków Dokąd wysłać piksel.
onSuccess function Jest wywoływany po pomyślnym załadowaniu pliku obrazu. Uwaga: nawet jeśli żądanie zostanie wysłane, przeglądarki mogą wymagać prawidłowej odpowiedzi obrazu, aby wykonać onSuccess.
onFailure function Wywoływany, gdy nie uda się załadować pikselu. Uwaga: nawet jeśli żądanie zostało wysłane pomyślnie, metoda onFailure może zostać wykonana, jeśli serwer nie zwróci prawidłowej odpowiedzi dotyczącej obrazu.

Powiązane uprawnienia

send_pixel

setCookie

Ustawia lub usuwa plik cookie o określonej nazwie, wartości i opcjach.

Składnia

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

Parametry

Parametr Typ Opis
name ciąg znaków Nazwa pliku cookie.
value ciąg znaków Wartość pliku cookie.
options object Określa atrybuty Domain, Path, Expires, Max-Age, Secure i SameSite. (patrz sekcja Opcje poniżej).
encode wartość logiczna Określa, czy wartość pliku cookie ma być kodowana za pomocą funkcji JavaScript encodeURIComponent(). Domyślna wartość to true.

Opcje

  • Domena: wartość określona przez właściwość options['domain'] (jeśli jest dostępna). Aby spróbować zapisać plik cookie w najszerszej możliwej domenie na podstawie lokalizacji dokumentu, ustaw tę wartość na 'auto'. Jeśli to się nie uda, spróbuje kolejnych, bardziej zawężonych subdomen. Jeśli wszystkie te próby zakończą się niepowodzeniem, plik cookie zostanie zapisany bez domeny. Jeśli nie zostanie ustawiona żadna wartość, plik cookie zostanie zapisany bez określonej domeny. Uwaga: gdy plik cookie bez określonej domeny jest zapisywany jako document.cookie, agent użytkownika domyślnie ustawia domenę pliku cookie na hosta bieżącej lokalizacji dokumentu.
  • Ścieżka: ustawiana przez options['path'], jeśli występuje. Jeśli plik cookie bez określonej ścieżki zostanie zapisany w miejscu document.cookie, klient użytkownika domyślnie ustawi ścieżkę pliku cookie na ścieżkę bieżącej lokalizacji dokumentu.
  • Maks. wiek: ustawiany przez options['max-age'], jeśli występuje.
  • Wygasa: ustawiany przez options['expires'], jeśli jest dostępny. Jeśli występuje, musi być to ciąg znaków z datą w formacie UTC. Parametru Date.toUTCString() można używać do formatowania wartości Date.
  • Bezpieczeństwo: ustawione przez options['secure'], jeśli jest dostępne.
  • SameSite: ustawiony przez options['samesite'], jeśli występuje.

Powiązane uprawnienia

set_cookies

setDefaultConsentState

Przesyła domyślną aktualizację zgody do warstwy danych w celu przetworzenia tak szybko, jak to możliwe po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich tagów, które zostały przez nie uruchomione (lub po upływie limitu czasu przetwarzania tagów). Aktualizacja jest przetwarzana w tym kontenerze przed elementami w kolejce w warstwie danych. Więcej informacji o zgodzie

Przykład:

const setDefaultConsentState = require('setDefaultConsentState');

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

Składnia

setDefaultConsentState(consentSettings)

Parametry

Parametr Typ Opis
consentSettings object Obiekt definiujący domyślny stan dla określonych typów zgody.

Obiekt consentSettings to mapowanie dowolnych ciągów znaków typu zgody na 'granted' lub 'denied'. Obsługuje te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Wartość każdego typu zgody może być ustawiona na „granted” (zgoda) lub „denied” (brak zgody). Każda wartość inna niż „granted” (zgoda) będzie traktowana jako „denied” (brak zgody). Ustawienie wartości na „undefined” (nieokreślona) nie będzie miało wpływu na jej poprzednią wartość.
region Tablica Opcjonalny tablica kodów regionów określająca, w którym regionie mają obowiązywać ustawienia zgody. Kody regionów są wyrażane za pomocą kodów krajów lub ich podjednostek w formacie ISO 3166-2.
wait_for_update liczba Określa wartość w milisekundach, która określa czas oczekiwania na wysłanie danych. Używane w przypadku narzędzi do uzyskiwania zgody, które wczytują się asynchronicznie.

Powiązane uprawnienia

Uprawnienia access_consent z dostępem do zapisu w przypadku wszystkich typów zgód w obiekcie consentSettings.

setInWindow

Ustawia określoną wartość w elementach window pod danym kluczem. Domyślnie ta metoda nie wyzeruje wartości w elementach window, jeśli wartość już istnieje. Aby ustawić wartość w polu window niezależnie od obecności wartości, ustaw overrideExisting na true. Zwraca wartość logiczną: true, jeśli wartość została ustawiona, a w przeciwnym razie false.

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w window, w którym ma zostać umieszczona wartość.
value * Wartość do ustawienia w window.
overrideExisting wartość logiczna Oznaczenie, że wartość powinna być ustawiona w polu window, niezależnie od tego, czy jest tam jakaś wartość.

Powiązane uprawnienia

access_globals

sha256

Oblicza skrót SHA-256 danych wejściowych i wywołuje funkcję wywołania zwrotnego z skrótem zakodowanym w formacie Base64, chyba że obiekt options określa inny kod wyjściowy.

Przykład:

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

Składnia

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

Parametry

Parametr Typ Opis
input ciąg znaków Ciąg znaków, dla którego ma zostać obliczony hasz.
onSuccess function Jest wywoływany z wynikiem digest zakodowanym w formacie base64, chyba że obiekt options określa inny kod wyjściowy.
onFailure function Jest wywoływany, gdy podczas obliczania skrótu wystąpi błąd lub przeglądarka nie obsługuje natywnie algorytmu sha256. Wywołanie zwrotne jest wywoływane z obiektem zawierającym nazwę błędu i komunikat.
options object Opcjonalny obiekt options do określania kodowania wyjściowego. Jeśli jest określony, obiekt powinien zawierać klucz outputEncoding o wartości base64 lub hex.

Powiązane uprawnienia

Brak.

templateStorage

Zwraca obiekt z metodami dostępu do magazynu szablonów. Pamięć szablonów umożliwia udostępnianie danych w ramach poszczególnych wykonań pojedynczego szablonu. Dane przechowywane w miejscu na szablony są dostępne przez cały czas istnienia strony.

Składnia

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Powiązane uprawnienia

access_template_storage

Przykład

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

Interfejs API toBase64 umożliwia kodowanie ciągu w formacie base64.

Składnia

toBase64(input)

Parametry

Parametr Typ Opis
input ciąg znaków Ciąg do zakodowania.

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Powiązane uprawnienia

Brak

updateConsentState

Przesyła do warstwy danych aktualizację zgody, która zostanie przetworzona tak szybko, jak to możliwe, po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich tagów, które zostały przez nie wywołane (lub po upływie limitu czasu przetwarzania tagów). Zaktualizowanie danych w tym kontenerze jest gwarantowane przed przetworzeniem dowolnych elementów oczekujących w kolejce w warstwie danych. Więcej informacji o zgodzie

Przykład:

const updateConsentState = require('updateConsentState');

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

Składnia

updateConsentState(consentSettings)

Parametry

Parametr Typ Opis
consentSettings object Obiekt, który aktualizuje stan dla określonych typów zgody.

Obiekt consentSettings to mapowanie dowolnych ciągów znaków typu zgody na 'granted' lub 'denied'. Obsługuje te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Wartość dla każdego typu zgody może być ustawiona na „Przyznano” lub „Odrzucono”. Wartość inna niż „granted” (przyznany) będzie traktowana jako „denied” (odmowa). Ustawienie wartości „undefined” („nieokreślony”) nie będzie miało wpływu na jej poprzednią wartość.

Powiązane uprawnienia

Uprawnienia access_consent z dostępem do zapisu w przypadku wszystkich typów zgód w obiekcie consentSettings.

Testowanie interfejsów API

Te interfejsy API współpracują z testami JavaScript w piaskownicy, aby tworzyć testy niestandardowych szablonów w Menedżerze tagów Google. Te testowe interfejsy API nie wymagają oświadczenia require(). Więcej informacji o testach szablonów niestandardowych

assertApi

Zwraca obiekt dopasowujący, który może służyć do płynnego formułowania twierdzeń dotyczących danego interfejsu API.

Składnia

assertApi(apiName)

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API do sprawdzenia; ten sam ciąg znaków, który został przekazany do funkcji require().

Dopasowywacze

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

Przykłady

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

assertThat

Interfejs API assertThat jest wzorowany na bibliotece [Truth] firmy Google. Zwraca obiekt, który można wykorzystać do płynnego formułowania twierdzeń dotyczących wartości tematu. Nieudane założenie spowoduje natychmiastowe przerwanie testu i oznaczenie go jako nieudanego. Niepowodzenie jednego testu nie wpłynie jednak na inne przypadki testowe.

Składnia

assertThat(actual, opt_message)

Parametry

Parametr Typ Opis
actual dowolny Wartość do użycia w testach płynności.
opt_message ciąg znaków Opcjonalny komunikat do wydrukowania, jeśli asercja się nie powiedzie.

Dopasowywacze

Dopasowywanie Opis
isUndefined() Twierdzi, że temat to undefined.
isDefined() Twierdzi, że temat nie jest undefined.
isNull() Twierdzi, że temat to null.
isNotNull() Twierdzi, że temat nie jest null.
isFalse() Twierdzi, że temat to false.
isTrue() Twierdzi, że temat to true.
isFalsy() Twierdzi, że temat jest fałszywy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isTruthy() Potwierdza, że temat jest prawdziwy. Wartości fałszywe to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isNaN() Sprawdza, czy temat ma wartość NaN.
isNotNaN() Sprawdza, czy argument jest dowolną wartością inną niż NaN.
isInfinity() Określa, czy argument jest dodatnią lub ujemną nieskończonością.
isNotInfinity() Określa, że argument jest dowolną wartością oprócz dodatniej lub ujemnej nieskończoności.
isEqualTo(expected) Twierdzi, że temat jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic porównywana jest rekurencyjnie.
isNotEqualTo(expected) Twierdzenie, że argument subject nie jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Twierdzi, że podmiot jest równy jednej z podanych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Twierdzenie, że argument subject nie jest równy żadnej z podanych wartości. To jest porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Twierdzi, że podmiot jest ściśle równy (===) podanej wartości.
isNotStrictlyEqualTo(expected) Twierdzenie, że podmiot nie jest ściśle równy (!==) danej wartości.
isGreaterThan(expected) Twierdzi, że argument jest większy niż (>) podana wartość w uporządkowanym porównaniu.
isGreaterThanOrEqualTo(expected) Twierdzenie, że podmiot jest większy lub równy (>=) danej wartości w uporządkowanym porównaniu.
isLessThan(expected) Określa, że argument jest mniejszy (<) od podanej wartości w porównywaniu uporządkowanym.
isLessThanOrEqualTo(expected) Zakłada, że argument jest mniejszy lub równy (<=) podanej wartości w uporządkowanym porównaniu.
contains(...expected) Sprawdza, czy argument jest tablicą lub ciągiem znaków zawierającym wszystkie podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Określa, że argument jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Określa, że argument jest tablicą zawierającą wszystkie podane wartości w dowolnej kolejności i bez innych wartości. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Twierdzi, że argument jest tablicą zawierającą inny zbiór wartości niż podany w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie z wartością referencyjną. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Zakłada, że argument jest tablicą lub ciągiem znaków o określonej długości. Jeśli wartość nie jest tablicą ani ciągiem znaków, assercja zawsze kończy się niepowodzeniem.
isEmpty() Sprawdza, czy argument jest tablicą lub ciągiem znaków, który jest pusty (długość = 0). Założenie zawsze zawodzi, jeśli wartość nie jest tablicą lub ciągiem znaków.
isNotEmpty() Sprawdza, czy argument jest tablicą lub ciągiem znaków, który nie jest pusty (długość > 0). Założenie zawsze zawodzi, jeśli wartość nie jest tablicą lub ciągiem znaków.
isArray() Zakłada, że typ tematu to tablica.
isBoolean() Zakłada, że typ tematu to wartość logiczna.
isFunction() Twierdzi, że typ tematu to funkcja.
isNumber() Sprawdza, czy typ tematu jest liczbą.
isObject() Zakłada, że typ podmiotu to obiekt.
isString() Zakłada, że typ tematu jest ciągiem znaków.

Przykłady

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

natychmiast kończy bieżący test i wypisuje podany komunikat (jeśli został podany).

Składnia

fail(opt_message);

Parametry

Parametr Typ Opis
opt_message ciąg znaków Opcjonalny tekst komunikatu o błędzie.

Przykład

fail('This test has failed.');

mock

Interfejs API mock umożliwia zastąpienie działania interfejsów API w sandboksie. Mock API można bezpiecznie używać w kodzie szablonu, ale działa ono tylko w trybie testowym. Przed każdym testem symulacje są resetowane.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API, który ma być symulowany; ten sam ciąg znaków, który został przekazany do funkcji require()
returnValue dowolny Wartość do zwrócenia dla interfejsu API lub funkcji wywoływanej zamiast interfejsu API. Jeśli returnValue to funkcja, to jest ona wywoływana zamiast interfejsu API w piaskownicy. Jeśli returnValue to cokolwiek innego niż funkcja, zwracana jest ta wartość zamiast interfejsu API w piaskownicy.

Przykłady

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

mockObject

Interfejs API mockObject umożliwia zastąpienie działania interfejsów API w piaskownicy, które zwracają obiekt. Interfejs API jest bezpieczny do użycia w kodzie szablonu, ale działa tylko w trybie testowym. Przed każdym testem symulacje są resetowane.

Składnia

mockObject(apiName, objectMock);

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API, który ma być symulowany; ten sam ciąg znaków, który został przekazany do funkcji require()
objectMock object Wartość do zwrócenia dla interfejsu API lub funkcji wywoływanej zamiast interfejsu API. Musi to być obiekt.

Przykłady

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

runCode

Uruchamia kod szablonu, czyli zawartość karty Kod, w bieżącym środowisku testowym z danym obiektem danych wejściowych.

Składnia

runCode(data)

Parametry

Parametr Typ Opis
data object Obiekt danych, który ma być użyty w teście.

Zwracana wartość

Zwraca wartość zmiennej w przypadku szablonów zmiennych; zwraca undefined w przypadku wszystkich innych typów szablonów.

Przykład

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