Interfejsy API szablonów niestandardowych

Podstawowe interfejsy API

Te interfejsy API współpracują z JavaScriptem w trybie piaskownicy, aby tworzyć szablony niestandardowe w Menedżerze tagów Google. Każdy interfejs API jest dodawany z instrukcją require(), np.:

const myAPI = require('myAPI');

addConsentListener

Rejestruje funkcję detektora, która jest wykonywana w przypadku zmiany stanu określonego typu zgody.

Dany detektor będzie wywoływany za każdym razem, gdy stan określonego typu zgody zmieni się z „Odmowa” na „Przyznano” na „Odrzucono”. Typ zgody bez stanu jest uważany za udzielony, więc detektor nie będzie wywoływany, jeśli nieskonfigurowany typ zgody zostanie zmieniony na Udzielono. Funkcje nasłuchujące będą odpowiedzialne za zapewnienie, że ich kod uruchamia się 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 nasłuchiwanie zmian stanu.
listener funkcja Funkcja uruchamiana w przypadku zmiany stanu określonego typu zgody.

Po wywołaniu detektor zostanie przekazany na temat typu zgody, który ulega zmianie, oraz nową wartość tego typu zgody:

Parametr Typ Opis
consentType ciąg znaków Rodzaj zgody, który ulega zmianie.
granted boolean Wartość logiczna prawda, jeśli określony typ zgody jest zmieniany na przyznany.

Powiązane uprawnienia

Uprawnienie access_consent z uprawnieniami do odczytu w przypadku tego typu zgody.

addEventCallback

Interfejs addEventCallback API umożliwia zarejestrowanie funkcji wywołania zwrotnego, która będzie wywoływana na końcu zdarzenia. Wywołanie zwrotne jest wywoływane po wykonaniu wszystkich tagów danego zdarzenia lub po osiągnięciu limitu czasu zdarzenia na stronie. W wywołaniu zwrotnym są przekazywane 2 wartości: identyfikator kontenera wywołującego funkcję i obiekt zawierający informacje o tym zdarzeniu.

Składnia

addEventCallback(callback)

Parametry

Parametr Typ Opis
callback funkcja Funkcja do wywołania po zakończeniu zdarzenia.

Obiekt eventData zawiera te dane:

Nazwa klucza Typ Opis
tags Tablica Tablica obiektów danych tagów. Każdy tag uruchomiony podczas zdarzenia będzie miał w tej tablicy wpis. Obiekt danych tagu zawiera identyfikator tagu (id), jego stan wykonania (status) i czas jego wykonania (executionTime). Dane tagu będą też zawierać 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 utworzenie aliasu (np. window.foo = window.bar), który ułatwia obsługę niektórych tagów wymagających aliasu. Przypisuje wartość obiektu window znalezionego w fromPath do klucza w obiekcie window w toPath. W przypadku powodzenia zwraca true, a w przeciwnym razie – false.

Składnia

aliasInWindow(toPath, fromPath)

Parametry

Parametr Typ Opis
toPath ciąg znaków Oddzielona kropkami ścieżka do obiektu window, do którego powinna zostać skopiowana wartość. Wszystkie komponenty w ścieżce do ostatniego komponentu muszą już istnieć w obiekcie window.
fromPath ciąg znaków Oddzielona kropkami ścieżka do elementu window prowadzącego do wartości do skopiowania. Jeśli wartość nie istnieje, operacja zakończy się niepowodzeniem.

Przykład

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

Powiązane uprawnienia

Usługa access_globals jest wymagana zarówno w przypadku pakietu toPath, jak i fromPath. toPath wymaga uprawnień do zapisu, a fromPath – do odczytu.

callInWindow

Umożliwia wywoływanie funkcji ze ścieżki poza obiektem window w sposób kontrolowany przez zasady. Wywołuje funkcję na podanej ścieżce w elemencie window z podanymi argumentami i zwraca wartość. Jeśli nie można bezpośrednio zmapować zwracanego typu na typ obsługiwany w JavaScript w trybie piaskownicy, zwracana jest wartość undefined. Osiem typów obsługiwanych w języku JavaScript w trybie piaskownicy to null, undefined, boolean, number, string, Array, Object i function. Jeśli podana ś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 Oddzielona kropkami ścieżka do funkcji w window, która ma ją wywołać.
args * Argumenty do przekazania do funkcji.

Powiązane uprawnienia

access_globals z włączonym uprawnieniem execute.

callLater

Zaplanuje asynchroniczne wywołanie funkcji. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. Jest to odpowiednik setTimeout(<function>, 0).

Składnia

callLater(function)

Parametry

Parametr Typ Opis
function funkcja Funkcja do wywołania.

copyFromDataLayer

Zwraca wartość obecnie przypisaną do danego klucza w warstwie danych: wartość znaleziona dla danego klucza, jeśli jest to typ podstawowy, funkcja lub literał obiektu. 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 Opcjonalną wersję warstwy danych. Wartością domyślną jest 2. Zdecydowanie odradzamy stosowanie wartości 1.

Powiązane uprawnienia

read_data_layer

copyFromWindow

Kopiuje zmienną z obiektu window. Jeśli wartości w polu window nie można zmapować bezpośrednio na typ obsługiwany przez JavaScript w trybie piaskownicy, zwracana jest wartość undefined. Osiem typów obsługiwanych w trybie JavaScriptu w trybie piaskownicy 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 obiekcie window, z którego chcesz skopiować wartość.

Powiązane uprawnienia

access_globals

createArgumentsQueue

Tworzy kolejkę wypełnioną obiektami argumentów na potrzeby rozwiązań tagów, które jej wymagają.

Tworzy funkcję w zakresie globalnym (np. window) przy użyciu argumentu fnKey (taka sama semantyka jak createQueue). Po utworzeniu funkcji ten interfejs API tworzy następnie tablicę w funkcji window (jeśli jeszcze nie istnieje) przy użyciu argumentu arrayKey.

Wywołanie funkcji utworzonej w ramach funkcji fnKey powoduje wypchnięcie obiektu argumentów na tablicę utworzoną w arrayKey. Zwracaną wartością interfejsu API jest funkcja utworzona w sekcji fnKey.

Ta funkcja wymaga ustawienia odczytu i zapisu dla fnKey i arrayKey w ramach uprawnienia 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 obiekcie window, w której ustawiona jest funkcja, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis z kropkami. Jeśli ścieżka klucza nie istnieje, zostanie zgłoszony wyjątek. Oznacza to, że jeśli fnKey ma wartość 'one.two', spowoduje zgłoszenie wyjątku.
arrayKey ciąg znaków Ścieżka w obiekcie window, w której jest ustawiona tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis z kropkami. Jeśli ścieżka klucza nie istnieje, zostanie zgłoszony wyjątek. Oznacza to, że jeśli arrayKey ma wartość 'one.two' i nie ma obiektu globalnego o nazwie 'one', spowoduje to zgłoszenie wyjątku.

Powiązane uprawnienia

access_globals

createQueue

Tworzy tablicę w funkcji window (jeśli jeszcze nie istnieje) i zwraca funkcję, która wypchnie wartości na tę tablicę.

Ta funkcja wymaga ustawienia odczytu i zapisu dla arrayKey w ramach uprawnienia 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 obiekcie window, w którym ustawiona jest tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis z kropkami. Jeśli ścieżka klucza nie istnieje, zostanie zgłoszony wyjątek. Jeśli na przykład arrayKey ma wartość 'one.two' i nie ma obiektu globalnego o nazwie 'one', spowoduje to zgłoszenie wyjątku.

Powiązane uprawnienia

access_globals

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym identyfikatorze URI. Zwraca ciąg znaków, który reprezentuje zdekodowany identyfikator URI. Zwraca undefined w przypadku wartości z nieprawidłowymi danymi wejściowymi.

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 przez encodeUri() lub w inny sposób.

Powiązane uprawnienia

Brak.

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie URI. Zwraca ciąg znaków, który reprezentuje zdekodowany komponent URI. Zwraca wartość undefined, jeśli podano 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, który został zakodowany przez encodeUriComponent() lub w inny sposób.

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier) przez zmianę znaczenia znaków specjalnych. Zwraca ciąg znaków, który reprezentuje podany ciąg zakodowany jako identyfikator URI. Zwraca wartość undefined z nieprawidłowymi danymi wejściowymi (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 Kompletny identyfikator URI.

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier) przez zmianę znaczenia znaków specjalnych. Zwraca ciąg znaków, który reprezentuje podany ciąg zakodowany jako identyfikator URI. Zwraca wartość undefined z nieprawidłowymi danymi wejściowymi (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 Komponent identyfikatora URI.

Powiązane uprawnienia

Brak.

fromBase64

Interfejs fromBase64 API umożliwia dekodowanie ciągów znaków z ich reprezentacji w standardzie base64. Zwraca wartość undefined w przypadku wartości z nieprawidłowymi danymi wejściowymi.

Składnia

fromBase64(base64EncodedString)

Parametry

Parametr Typ Opis
base64EncodedString ciąg znaków Ciąg zakodowany w standardzie 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 wartość potencjalna zwróconej liczby całkowitej.
max liczba Maksymalna wartość potencjalna zwróconej liczby całkowitej.

Powiązane uprawnienia

Brak.

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwracany obiekt zawiera 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 podanej nazwie.

Składnia

getCookieValues(name[, decode])

Parametry

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

Powiązane uprawnienia

get_cookies

getQueryParameters

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

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz pobierany z parametrów zapytania.
retrieveAll boolean Określa, czy pobrać wszystkie wartości.

Jeśli np. aktualny 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 musi określać wartość queryKey w dozwolonych kluczach zapytania (lub zezwalać na dowolny klucz zapytania).

getReferrerQueryParameters

Interfejs getReferrerQueryParameters API działa tak samo jak getQueryParameters, z tym że działa na stronie odsyłającej, a nie na bieżącym adresie URL. Zwraca pierwszy lub wszystkie parametry elementu queryKey danej strony odsyłającej. Zwraca pierwszą wartość z queryKey lub tablicę wartości z queryKey.

Składnia

getReferrerQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz pobierany z parametrów zapytania.
retrieveAll boolean Określa, czy pobrać wszystkie wartości.

Jeśli na przykład URL strony odsyłającej to https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, to:

  • 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ć wartość queryKey w dozwolonych kluczach zapytania (lub zezwalać na dowolny klucz zapytania).

getReferrerUrl

Przy danym typie komponentu interfejs API odczytuje obiekt dokumentu ze strony odsyłającej i zwraca ciąg znaków reprezentujący część strony odsyłającej. Jeśli nie określono żadnego komponentu, zwracany jest pełny adres URL strony odsyłającej.

Składnia

getReferrerUrl([component])

Parametry

Parametr Typ Opis
component ciąg znaków Komponent zwracany z adresu URL. Możliwe wartości: protocol, host, port, path, query, extension. Jeśli component to 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ć wartość queryKey w dozwolonych kluczach zapytania (lub zezwalać na dowolny klucz zapytania).

getTimestamp

Wycofano. Wolisz getTimestampMillis.

Zwraca liczbę reprezentującą czas w milisekundach od początku epoki uniksowej, zwracany przez Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę reprezentującą czas w milisekundach od początku epoki uniksowej, zwracany przez Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

Zwraca ciąg znaków opisujący typ danej wartości. W odróżnieniu od typeof getType rozróżnia array i object.

Składnia

getType(data.someField)

Notes

Tabela poniżej zawiera listę ciągów znaków zwróconych dla każdej wartości wejściowej.

Wartość wejściowa Wyniki
undefined 'undefined' [nieokreślony]
null „null”
true 'boolean'
12 „liczba”
'string' „ciąg znaków”
{ a: 3 } „object”
[ 1, 3 ] „tablica”
(x) => x + 1 „funkcja”

Powiązane uprawnienia

Brak.

getUrl

Zwraca ciąg znaków reprezentujący cały bieżący adres URL lub jego część, określony typ komponentu i niektóre parametry konfiguracji.

Składnia

getUrl(component)

Parametry

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

Powiązane uprawnienia

get_url

gtagSet

Przekazuje do warstwy danych polecenie zestawu gtag, które zostanie przetworzone, gdy tylko bieżące zdarzenie i wszystkie uruchomione przez niego tagi zostaną przetworzone (lub upłynie czas oczekiwania na przetwarzanie tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed elementami znajdującymi się w kolejce w kolejce warstwy danych.

Jeśli na przykład tag zostanie wywołany podczas inicjacji zgody, aktualizacja zostanie wprowadzona przed przetworzeniem zdarzenia inicjowania. Przykładem może być ustawienie atrybutu ads_data_redaction na true lub false albo url_passthrough z wartością 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 obiekt, Obiekt, który aktualizuje stan globalny swoich właściwości podrzędnych.

Powiązane uprawnienia

write_data_layer sprawdza uprawnienia do zapisu w dataLayer pod kątem wszystkich podanych kluczy. Jeśli dane wejściowe do gtagSet są zwykłym obiektem, interfejs API sprawdzi uprawnienia do zapisu we wszystkich spłaszczonych kluczach wewnątrz obiektu, np. w przypadku gtagSet({foo: {bar: 'baz'}}), API sprawdzi uprawnienia do zapisu w foo.bar.

Jeśli dane wejściowe w funkcji gtagSet są kluczem i nierówną wartością obiektu, interfejs API sprawdzi uprawnienia do zapisu w tym kluczu – np. w przypadku gtagSet('abc', true) – sprawdzi uprawnienia do zapisu w 'abc'.

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

injectHiddenIframe

Dodaje do strony niewidoczny element iframe.

Wywołania zwrotne są przekazywane jako instancje funkcji i są zawarte w funkcjach JavaScript, które do nich się odnoszą.

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 elementu iframe.
onSuccess funkcja Wywoływane po pomyślnym wczytaniu ramki.

Powiązane uprawnienia

inject_hidden_iframe

injectScript

Dodaje na stronie tag skryptu, który pozwala asynchronicznie wczytywać dany adres URL. Wywołania zwrotne są przekazywane jako instancje funkcji i są zawarte w funkcjach JavaScript, które do nich się odnoszą.

Składnia

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

Parametry

Parametr Typ Opis
url ciąg znaków Adres skryptu do wstrzyknięcia.
onSuccess funkcja Wywoływana po pomyślnym wczytaniu skryptu.
onFailure funkcja Wywoływane, gdy nie udało się wczytać skryptu.
cacheToken ciąg znaków Opcjonalny ciąg znaków wskazujący, że dany adres URL powinien być zapisany w pamięci podręcznej. Jeśli podasz tę wartość, zostanie utworzony tylko 1 element skryptu wysyłający żądanie JavaScriptu. Wszelkie dodatkowe próby wczytania spowodują umieszczenie podanych metod onSuccess i onFailure w kolejce, dopóki skrypt nie zostanie wczytany.

Powiązane uprawnienia

inject_script

isConsentGranted

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

Zgoda w przypadku określonego rodzaju zgody jest uznawana za udzielona, jeśli ma ona wartość „przyznano” lub w ogóle nie jest ustawiona. Jeśli typ zgody ma dowolną inną wartość, zostanie uznany za nieudzielony.

Interfejs Menedżera tagów służący do zarządzania ustawieniami tagów umożliwia uruchamianie tagów zawsze. Jeśli tag z włączoną opcją zawsze uruchamiania używa tego interfejsu API, zgoda jest uznawana za udzieloną i zwracana jest właściwość 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órej stan ma zostać sprawdzony.

Powiązane uprawnienia

Uprawnienie access_consent z uprawnieniami do odczytu w przypadku tego typu zgody.

JSON

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

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

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

Składnia

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

Parametry

JSON.parse

Parametr Typ Opis
stringInput dowolny Wartość do konwersji. Jeśli wartość nie jest ciągiem znaków, dane wejściowe zostaną przekształcone w ciąg znaków.

JSON.stringify

Parametr Typ Opis
value dowolny Wartość do konwersji.

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

Konwertuje podaną wartość na liczbę (całkowitą).

Składnia

makeInteger(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do konwersji.

Powiązane uprawnienia

Brak.

makeNumber

Konwertuje podaną wartość na liczbę.

Składnia

makeNumber(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do konwersji.

Powiązane uprawnienia

Brak.

makeString

Zwraca podaną wartość jako ciąg znaków.

Składnia

makeString(value)

Parametry

Parametr Typ Opis
value dowolny Wartość do konwersji.

Powiązane uprawnienia

Brak.

makeTableMap

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

Ta funkcja może na przykład przekonwertować obiekt tabeli:

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

na mapę:

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

Zwraca Object: przekonwertowany element Map, jeśli zostały do niego dodane pary klucz-wartość. W przeciwnym razie zwraca wartość null.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametry

Parametr Typ Opis
tableObj Wyświetl listę Obiekt tabeli do skonwertowania. To lista map, na których każdy element Map reprezentuje wiersz w tabeli. Każda nazwa właściwości w obiekcie wiersza to nazwa kolumny, a wartość właściwości to wartość kolumny w wierszu.
keyColumnName ciąg znaków Nazwa kolumny, której wartości staną się kluczami w przekonwertowanym elemencie Map.
valueColumnName ciąg znaków Nazwa kolumny, której wartości staną się wartościami w przekonwertowanym obiekcie 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() określa działanie Object.keys() biblioteki standardowej. Zwraca tablicę nazw numerycznych właściwości danego obiektu w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda values() określa działanie Object.values() biblioteki standardowej. Zwraca tablicę wartości numerycznych właściwości danego obiektu w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda entries() określa działanie Object.entries() biblioteki standardowej. Zwraca tablicę par właściwości numerycznych [key, value] danego obiektu w tej samej kolejności, w jakiej byłaby pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda freeze() określa działanie Object.freeze() biblioteki standardowej. Zablokowanego obiektu nie można już zmienić. Zablokowanie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie dotychczasowych oraz zmienianie ich wartości. freeze() zwraca ten sam obiekt, który został przekazany. Argument podstawowy lub pusty będzie traktowany tak, jakby był zablokowanym obiektem i zostanie zwrócony.

Metoda delete() określa działanie operatora usuwania z Biblioteki standardowej. Usuwa dany klucz z obiektu, chyba że obiekt jest zablokowany. Podobnie jak operator usuwania z Biblioteki standardowej zwraca true, jeśli pierwsza wartość wejściowa (objectInput) jest obiektem, który nie jest zablokowany, 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ę jednak od operatora usuwania z biblioteki standardowej tym, że:

  • keyToDelete nie może być ciągiem rozdzielanym kropkami, który określa zagnieżdżony klucz.
  • Za pomocą polecenia delete() nie możesz usuwać elementów z tablicy.
  • Za pomocą delete() nie możesz usunąć żadnych 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 do wyliczenia. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.values

Parametr Typ Opis
objectInput dowolny Obiekt, którego wartości do wyliczenia. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.entries

Parametr Typ Opis
objectInput dowolny Obiekt, którego pary klucz/wartość mają zostać wyliczone. Jeśli dane wejściowe nie są obiektem, zostaną przekształcone w obiekt.

Object.freeze

Parametr Typ Opis
objectInput dowolny Obiekt do zablokowania. Jeśli dane wejściowe nie są obiektem, będą traktowane jako zablokowane.

Object.delete

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

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, który zawiera wszystkie części składowe podanego adresu URL, podobnie jak obiekt URL.

Ten interfejs API zwraca kod undefined w przypadku każdego nieprawidłowego adresu URL. W przypadku prawidłowo sformatowanych adresów URL pola, których nie ma w ciągu adresu URL, będą miały wartość pustego ciągu znaków lub, w przypadku searchParams, pustego obiektu.

Zwracany 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 poddany analizie.

Powiązane uprawnienia

Brak.

queryPermission

Wyślij zapytanie o dozwolone i zawężone uprawnienia. Zwraca wartość boolean: true, jeśli uprawnienie zostało przyznane. W przeciwnym razie zwraca wartość false.

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 uprawnienia, którego dotyczy zapytanie. Zobacz Argumenty funkcji poniżej.

Argumenty funkcji

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

writeGlobals, readGlobals: drugi parametr powinien być zapisywanym lub odczytywanym kluczem.

readUrl: żadne dodatkowe argumenty nie są konieczne do sprawdzania, czy można odczytać cały adres URL. Aby sprawdzić, czy dany komponent można odczytać, przekaż nazwę komponentu jako drugi argument:

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

Aby sprawdzić, czy określony klucz zapytania jest czytelny, przekaż 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 wbudowaną funkcję według nazwy. Zwraca funkcję lub obiekt, które można wywołać z programu. Zwraca wartość 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 adresu URL.

Składnia

sendPixel(url, onSuccess, onFailure)

Parametry

Parametr Typ Opis
url ciąg znaków Dokąd chcesz wysłać piksel.
onSuccess funkcja Wywoływana po pomyślnym wczytaniu piksela. Uwaga: nawet jeśli żądanie zostanie wysłane, przeglądarki mogą wymagać prawidłowej odpowiedzi obrazu, aby wykonać żądanie onSuccess.
onFailure funkcja Wywoływane, gdy piksel się nie załaduje. Uwaga: nawet wtedy, gdy żądanie zostanie wysłane, funkcja onFailure może zostać uruchomiona, jeśli serwer nie zwróci prawidłowej odpowiedzi obrazu.

Powiązane uprawnienia

send_pixel

setCookie

Ustawia lub usuwa plik cookie z określoną nazwą, wartością i opcjami.

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 obiekt, Określa atrybuty Domena, Ścieżka, Wygasa, Maksymalny wiek, Zabezpieczenie i SameSite. (Zobacz Opcje poniżej).
encode boolean Określa, czy wartość pliku cookie ma być kodowana za pomocą encodeURIComponent() w JavaScripcie. Domyślna wartość to true.

  • Domena: ustawiona przez usługę options['domain'] (jeśli występuje). Ustaw tę wartość na 'auto', aby spróbować zapisać plik cookie przy użyciu jak najszerszej możliwej domeny (na podstawie lokalizacji dokumentu). W przypadku niepowodzenia próbuje stopniowo przeglądać subdomeny. Jeśli żadne z tych rozwiązań nie powiedzie się, zostanie podjęta próba zapisania pliku cookie bez domeny. Jeśli nie zostanie ustawiona żadna wartość, plik cookie zostanie zapisany bez podanej domeny. Uwaga: gdy plik cookie bez określonej domeny zostanie zapisany pod adresem document.cookie, klient użytkownika domyślnie ustawi domenę pliku cookie na hosta bieżącej lokalizacji dokumentu.
  • Ścieżka: ustawiona przez options['path'] (jeśli występuje). Gdy plik cookie bez określonej ścieżki zostanie zapisany w document.cookie, klient użytkownika domyślnie ustawi ścieżkę pliku cookie na ścieżkę obecnej lokalizacji dokumentu.
  • Max-Age:ustawione przez options['max-age'] (jeśli występuje).
  • Wygasa: ustawione przez użytkownika options['expires'] (jeśli występuje). Jeśli występuje, musi to być ciąg daty w formacie UTC. Date.toUTCString() można użyć do sformatowania Date dla tego parametru.
  • Bezpieczna:ustawiona przez options['secure'] (jeśli występuje).
  • SameSite: ustawione przez options['samesite'] (jeśli występuje).

Powiązane uprawnienia

set_cookies

setDefaultConsentState

Przekazuje do warstwy danych aktualizację domyślnej zgody na przetwarzanie danych, która zostanie przetworzona najwcześniej po zakończeniu bieżącego zdarzenia i wszystkich wywołanych przez niego tagów (lub gdy upłynie czas oczekiwania na przetwarzanie tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed elementami znajdującymi się w kolejce w warstwie danych. Więcej informacji o uzyskiwaniu zgody

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 obiekt, Obiekt określający domyślny stan określonych rodzajów zgody.

Obiekt consentSettings jest mapowaniem dowolnych ciągów znaków dotyczących typu zgody na jeden z tych ciągów: 'granted' lub 'denied'. Obsługuje te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Dla każdego typu zgody można ustawić wartość „przyznano” lub „odrzucono”. Każda wartość inna niż „przyznano” będzie traktowana jako „odrzucona”. Ustawienie wartości „nieokreślona” nie ma wpływu na jej poprzednią wartość.
region Tablica Opcjonalna tablica kodów regionów określająca region, do którego mają zastosowanie ustawienia uzyskiwania zgody. Kody regionów są wyrażane za pomocą krajów lub podziałów w formacie ISO 3166-2.
wait_for_update liczba Określa wartość w milisekundach, która określa, jak długo należy czekać na wysłanie danych. Używana z narzędziami do uzyskiwania zgody użytkowników, które ładują się asynchronicznie.

Powiązane uprawnienia

Uprawnienie access_consent z uprawnieniami do zapisu w przypadku wszystkich typów zgody w obiekcie consentSettings.

setInWindow

Ustawia podaną wartość w funkcji window dla danego klucza. Domyślnie ta metoda nie ustawia wartości w elemencie window, jeśli wartość już istnieje. Ustaw overrideExisting na true, aby ustawić wartość w window niezależnie od obecności istniejącej wartości. Zwraca wartość boolean: true, jeśli wartość została ustawiona prawidłowo. W przeciwnym razie zwraca wartość false.

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w argumencie window, w którym ma zostać umieszczona wartość.
value * Wartość do ustawienia w window.
overrideExisting boolean Flaga wskazująca, że wartość powinna być ustawiona w window niezależnie od tego, czy zawiera ona jakąś wartość.

Powiązane uprawnienia

access_globals

sha256

Oblicza skrót SHA-256 danych wejściowych i wywołuje wywołanie zwrotne ze skrótem zakodowanym w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.

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, dla którego ma zostać obliczony hasz.
onSuccess funkcja Wywoływana z powstałym skrótem zakodowanym w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.
onFailure funkcja Wywoływane, jeśli podczas obliczania podsumowania wystąpi błąd lub jeśli przeglądarka nie ma natywnej obsługi sha256. Wywołanie zwrotne jest wywoływane z obiektem zawierającym nazwę błędu i komunikat.
options obiekt, Opcjonalny obiekt opcji określający kodowanie wyjściowe. Obiekt powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

templateStorage

Zwraca obiekt z metodami dostępu do pamięci szablonów. Miejsce na dane w szablonie umożliwia udostępnianie danych między wykonaniami jednego szablonu. Dane przechowywane w pamięci szablonów są przechowywane przez cały okres 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 toBase64 API umożliwia zakodowanie ciągu znaków w formacie base64.

Składnia

toBase64(input)

Parametry

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

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Powiązane uprawnienia

Brak

updateConsentState

Przekazuje do warstwy danych aktualizację dotyczącą zgody, która ma zostać przetworzona jak najszybciej po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich wywołanych przez niego tagów (lub upłynięcia limitu czasu przetwarzania tagu). Gwarantuje się, że aktualizacja zostanie przetworzona w tym kontenerze przed elementami znajdującymi się 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 obiekt, Obiekt, który aktualizuje stan określonych rodzajów zgody.

Obiekt consentSettings jest mapowaniem dowolnych ciągów znaków dotyczących typu zgody na jeden z tych ciągów: 'granted' lub 'denied'. Obsługuje te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Dla każdego typu zgody można ustawić wartość „przyznano” lub „odmowa”. Każda wartość inna niż „przyznano” będzie traktowana jako „odmowa”. Ustawienie wartości „undefined” nie ma wpływu na jej poprzednią wartość.

Powiązane uprawnienia

Uprawnienie access_consent z uprawnieniami do zapisu w przypadku wszystkich typów zgody w obiekcie consentSettings.

Testuj interfejsy API

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

assertApi

Zwraca obiekt dopasowywania, którego można używać do płynnego zgłaszania asercji 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 require().

Dopasowania

  • 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 assertThat API jest wzorowany na bibliotece [Truth] Google. Zwraca obiekt, za pomocą którego można płynnie formułować stwierdzenia dotyczące wartości podmiotu. Niepowodzenie asercji spowoduje natychmiastowe zatrzymanie testu i oznaczenie go jako nieudanego. Jednak błąd jednego z testów nie będzie miał wpływu na pozostałe przypadki.

Składnia

assertThat(actual, opt_message)

Parametry

Parametr Typ Opis
actual dowolny Wartość do użycia podczas kontroli płynności.
opt_message ciąg znaków Opcjonalna wiadomość do wydrukowania w przypadku niepowodzenia potwierdzenia.

Dopasowania

Dopasowanie Opis
isUndefined() Informuje, że tematem jest undefined.
isDefined() Potwierdza, że podmiotem nie jest undefined.
isNull() Informuje, że tematem jest null.
isNotNull() Potwierdza, że podmiotem nie jest null.
isFalse() Informuje, że tematem jest false.
isTrue() Informuje, że tematem jest true.
isFalsy() Twierdzi, że temat jest fałszywy. Wartości falsy to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isTruthy() Twierdzi, że temat jest prawdziwy. Wartości falsy to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isNaN() Potwierdza, że podmiot jest wartością NaN.
isNotNaN() Wskazuje, że podmiot jest wartością inną niż NaN.
isInfinity() Informuje, że temat jest pozytywny lub negatywny.
isNotInfinity() Wskazuje, że podmiot jest wartością inną niż dodatnia lub ujemna nieskończoność.
isEqualTo(expected) Potwierdza, że podmiot jest równy podanej wartości. To jest porównanie wartości, a nie referencji. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Informuje, że podmiot nie jest równy podanej wartości. To jest porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Informuje, że podmiot jest równy jednej z podanych wartości. To jest porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Informuje, że podmiot nie jest równy żadnej z podanych wartości. To jest porównanie wartości, a nie referencji. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Informuje, że podmiot jest dokładnie równy (===) podanej wartości.
isNotStrictlyEqualTo(expected) Informuje, że podmiot nie jest dokładnie równy (!==) podanej wartości.
isGreaterThan(expected) Informuje, że obiekt jest większy niż (>) podana w porównaniu uporządkowanym.
isGreaterThanOrEqualTo(expected) Informuje, że obiekt jest większy lub równy (>=) podanej wartości w porównaniu uporządkowanym.
isLessThan(expected) Informuje, że obiekt jest mniejszy niż podana w porównaniu uporządkowanym (<) wartość.
isLessThanOrEqualTo(expected) Informuje, że obiekt jest mniejszy lub równy (<=) podanej wartości w porównaniu uporządkowanym.
contains(...expected) Informuje, że podmiotem jest tablica lub ciąg znaków, który zawiera wszystkie podane wartości w dowolnej kolejności. To jest porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Informuje, że podmiotem jest tablica lub ciąg znaków, który nie zawiera żadnej z podanych wartości. To jest porównanie wartości, a nie referencji. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Informuje, że obiekt jest tablicą, która zawiera wszystkie podane wartości w dowolnej kolejności i nie ma żadnych innych wartości. To jest porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Informuje, że podmiot jest tablicą, która zawiera inny zbiór wartości niż podane wartości w dowolnej kolejności. To jest porównanie wartości, a nie odniesienia. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Informuje, że podmiot jest tablicą lub ciągiem znaków o podanej długości. asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isEmpty() Informuje, że obiektem jest tablica lub ciąg znaków, który jest pusty (długość = 0). asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isNotEmpty() Informuje, że podmiotem jest tablica lub ciąg znaków, który nie jest pusty (długość > 0). asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isArray() Informuje, że typem podmiotu jest tablica.
isBoolean() Wskazuje, że typ tematu jest wartością logiczną.
isFunction() Informuje, że typ podmiotu jest funkcją.
isNumber() Potwierdza, że typ tematu jest liczbą.
isObject() Potwierdza, że typ podmiotu jest obiektem.
isString() Potwierdza, ż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 nie zakończy się bieżący test i drukuje określoną wiadomość, jeśli została dostarczona.

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 mock API pozwala zastąpić działanie interfejsów API w trybie piaskownicy. Przykładowy interfejs API można bezpiecznie używać w kodzie szablonu, ale nie działa, gdy znajduje się w trybie testowym. Makiety są resetowane przed każdym testem.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API do pozorowania; ten sam ciąg znaków, który został przekazany do require()
returnValue dowolny Wartość do zwrócenia dla interfejsu API lub funkcji wywołanej w miejscu interfejsu API. Jeśli returnValue jest funkcją, jest ona wywoływana zamiast interfejsu Sandboxed API. Jeśli returnValue jest czymś innym niż funkcja, wartość ta jest zwracana zamiast interfejsu Sandboxed API.

Przykłady

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

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 obiekt, Obiekt danych do użycia w teście.

Zwracana wartość

Zwraca wartość zmiennej dla szablonów zmiennych. Zwraca wartość undefined w przypadku pozostałych typów szablonów.

Przykład

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