Interfejsy API szablonów niestandardowych

Podstawowe interfejsy API

Te interfejsy API współpracują z kodem JavaScript w trybie piaskownicy do tworzenia niestandardowych szablonów w Menedżerze tagów Google. Każdy interfejs API jest dodawany za pomocą instrukcji 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 „Odrzucono” na „Przyznano” lub „Odrzucono”. Uznaje się, że typ zgody bez stanu zgody został przyznany, więc detektor nie zostanie wywołany, jeśli nieskonfigurowany typ zgody zostanie zmieniony na stan „Przyznano”. Funkcje nasłuchujące będą zadbać o to, by 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 po zmianie stanu określonego typu zgody.

Po wywołaniu detektor przekaże on zmieniony typ zgody i nową wartość tego typu:

Parametr Typ Opis
consentType ciąg znaków Zmieniany typ zgody.
granted boolean Wartość logiczna prawda, jeśli wybrany 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 po zakończeniu zdarzenia. Wywołanie zwrotne jest wywoływane po wykonaniu wszystkich tagów zdarzenia lub po osiągnięciu limitu czasu zdarzenia na stronie. W wywołaniu zwrotnym przekazywane są 2 wartości: identyfikator kontenera wywołującego funkcję i obiekt zawierający informacje o 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ł wpis w tej tablicy. Obiekt danych tagu zawiera jego identyfikator (id), stan jego wykonania (status) i czas jego wykonania (executionTime). Dane tagu będą zawierać 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 utworzenie aliasu (np. window.foo = window.bar), który ułatwia obsługę niektórych tagów, które wymagają aliasów. Przypisuje wartość w obiekcie window znalezionym 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 Ścieżka do obiektu window oddzielona kropkami, do której ma zostać skopiowana wartość. Wszystkie komponenty w ścieżce do ostatniego komponentu muszą już istnieć w obiekcie window.
fromPath ciąg znaków Rozdzielana kropkami ścieżka do elementu window prowadzącego do wartości do skopiowania. Jeśli wartość nie istnieje, operacja się nie powiedzie.

Przykład

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

Powiązane uprawnienia

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

callInWindow

Umożliwia wywoływanie funkcji ze ścieżki poza obiektem window w sposób kontrolowany przez zasady. Wywołuje funkcję w podanej ścieżce w obiekcie window z podanymi argumentami i zwraca wartość. Jeśli zwracanego typu nie można zmapować bezpośrednio na typ obsługiwany w kodzie JavaScript w trybie piaskownicy, zostanie zwrócona 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 właściwość undefined.

Składnia

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

Parametry

Parametr Typ Opis
pathToFunction ciąg znaków Rozdzielana 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

Planuje wywołanie funkcji asynchronicznie. 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 w danym kluczu, jeśli jest to typ podstawowy, funkcja lub literał obiektu. W przeciwnym razie funkcja 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 window nie można zmapować bezpośrednio na typ obsługiwany w języku JavaScript działającym 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. Zwraca pobraną (i wymuszoną) wartość.

Składnia

copyFromWindow(key)

Parametry

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

Powiązane uprawnienia

access_globals

createArgumentsQueue

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

Tworzy funkcję w zakresie globalnym (tj. window) przy użyciu argumentu fnKey (ta sama semantyka co w przypadku createQueue). Po utworzeniu funkcji ten interfejs API tworzy tablicę w funkcji window (jeśli jeszcze nie istnieje) przy użyciu argumentu arrayKey.

Po wywołaniu funkcji utworzonej pod fnKey następuje wypychanie obiektu argumentów do tablicy utworzonej w kroku arrayKey. Zwracana wartość interfejsu API to 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', zgłasza wyjątek.
arrayKey ciąg znaków Ścieżka w lokalizacji window, w której 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. Oznacza to, że jeśli arrayKey ma wartość 'one.two' i nie ma żadnego obiektu globalnego o nazwie 'one', spowoduje to zgłoszenie wyjątku.

Powiązane uprawnienia

access_globals

createQueue

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

Ta funkcja wymaga ustawienia odczytu i zapisu dla funkcji arrayKey z uprawnieniem 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 lokalizacji window, w którym tablica jest ustawiona, 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 żadnego 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 reprezentujący zdekodowany identyfikator URI. Zwraca wartość undefined, gdy podano nieprawidłowe dane wejściowe.

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, który został 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 reprezentujący zdekodowany komponent URI. Zwraca wartość undefined, gdy 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 przez zmianę znaczenia znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined w przypadku podania nieprawidłowych danych wejściowych (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 przez zmianę znaczenia znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined w przypadku podania nieprawidłowych danych wejściowych (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 base64. Zwraca wartość undefined, gdy podano nieprawidłowe dane wejściowe.

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ę (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ą skryptu decodeURIComponent() w języku JavaScript. Domyślna wartość to true.

Powiązane uprawnienia

get_cookies

getQueryParameters

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

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

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

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

getReferrerQueryParameters

Interfejs getReferrerQueryParameters API działa tak samo jak getQueryParameters. Jedyna różnica jest taka, że działa na stronie odsyłającej zamiast bieżącego adresu URL. Zwraca pierwszy lub wszystkie parametry queryKey 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 odczytywany z parametrów zapytania.
retrieveAll boolean Określa, czy chcesz 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:

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

getReferrerUrl

Przy podanym typie komponentu interfejs API odczytuje obiekt dokumentu dla strony odsyłającej i zwraca ciąg znaków reprezentujący część tego elementu. 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, który ma zostać zwrócony z adresu URL. Dostępne wartości: protocol, host, port, path, query, extension. Jeśli component to undefined, null lub nie pasuje do któregoś z tych komponentów, zwracany jest cały adres URL.

Powiązane uprawnienia

get_referrer musi zezwalać na komponent query i musi określać queryKey w dozwolonych kluczach zapytania (lub zezwalać na dowolny klucz zapytania).

getTimestamp

Wycofane. Preferuj getTimestampMillis.

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

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

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

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

Zwraca ciąg znaków opisujący typ podanej wartości. W przeciwieństwie do typeof właściwość getType rozróżnia wartości array i object.

Składnia

getType(data.someField)

Notes

W tabeli poniżej znajdziesz ciągi znaków zwrócone dla poszczególnych wartości wejściowych.

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

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, który ma zostać zwrócony 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 tych komponentów, zwracana jest cała wartość href.

Powiązane uprawnienia

get_url

gtagSet

Przesyła do warstwy danych polecenie „Set gtag” w celu ich przetworzenia od razu po wystąpieniu bieżącego zdarzenia i po zakończeniu przetwarzania przez nie wszystkich uruchomionych przez nie tagów (lub gdy minie czas oczekiwania na przetworzenie tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed innymi elementami znajdującymi się w kolejce w kolejce warstwy danych.

Jeśli na przykład wywołanie tagu wywołanego przez tag inicjacji zgody spowoduje, że aktualizacja zostanie zastosowana przed przetworzeniem zdarzenia inicjowania. Na przykład ads_data_redaction ma wartość true lub false albo url_passthrough ma wartość 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.

Powiązane uprawnienia

write_data_layer sprawdza uprawnienia do zapisu w dataLayer w przypadku 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 tego obiektu, np. w przypadku gtagSet({foo: {bar: 'baz'}}), API sprawdzi uprawnienia do zapisu w foo.bar.

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

Pamiętaj, że po wystąpieniu cyklu 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 się do nich odwoł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 elementu iframe.
onSuccess funkcja Wywoływana po pomyślnym wczytaniu ramki.

Powiązane uprawnienia

inject_hidden_iframe

injectScript

Dodaje do strony tag skryptu, który pozwala asynchronicznie wczytywać dany adres URL. Wywołania zwrotne są przekazywane jako instancje funkcji i ujęte w funkcje JavaScript, które się do nich wywołują.

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ływana, gdy nie udało się wczytać skryptu.
cacheToken ciąg znaków Opcjonalny ciąg wskazujący, że dany adres URL powinien być przechowywany w pamięci podręcznej. Jeśli podasz tę wartość, zostanie utworzony tylko 1 element skryptu do żądania JavaScriptu. Wszelkie dodatkowe próby wczytania spowodują umieszczenie podanych metod onSuccess i onFailure w kolejce do momentu załadowania skryptu.

Powiązane uprawnienia

inject_script

isConsentGranted

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

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

Interfejs Menedżera tagów, w którym znajdują się ustawienia tagów, udostępnia opcję ich uruchamiania. Jeśli z tego interfejsu API jest włączony tag z włączonym zawsze uruchamianiem, zgoda jest uważana 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 Rodzaj 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 udostępniający funkcje JSON.

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

Funkcja stringify() konwertuje dane wejściowe na ciąg znaków JSON. Jeśli wartości nie można przeanalizować (np. gdy obiekt jest objęty cyklem), 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, 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 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 Map, jeśli zostały do niego dodane pary klucz-wartość. W przeciwnym razie zwraca null.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametry

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

Metoda freeze() działa w standardowej bibliotece Object.freeze(). Zablokowanego obiektu nie można już zmienić. Zablokowanie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących i zmianę 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 w standardowej bibliotece, 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ę on jednak od operatora usuwania z biblioteki standardowej tym, że:

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

Object.freeze

Parametr Typ Opis
objectInput dowolny Obiekt do zamrożenia. Jeśli dane wejściowe nie są obiektem, są traktowane jak 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 zawierający wszystkie części składowe podanego adresu URL, podobnie jak obiekt URL.

Ten interfejs API zwróci błąd undefined w przypadku każdego nieprawidłowego adresu URL. W przypadku prawidłowo sformatowanych adresów URL pola, które nie występują w ciągu adresu URL, będą miały wartość pustą. W przypadku parametru searchParams jest 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 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: nie są wymagane żadne dodatkowe argumenty do sprawdzenia, 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 dany klucz zapytania jest czytelny, przekaż ten klucz 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óry można wywołać z programu. Zwraca wartość undefine, 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 Gdzie 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 do wykonania operacji onSuccess.
onFailure funkcja Wywoływana, gdy nie uda się wczytać piksela. Uwaga: nawet jeśli żądanie zostanie wysłane, kod onFailure może zostać uruchomiony, 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 Domain, Path, Expires, Max-Age, Secure i SameSite. (Zobacz Opcje poniżej).
encode boolean Określa, czy wartość pliku cookie ma być kodowana za pomocą encodeURIComponent() w JavaScript. 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 domeny (na podstawie lokalizacji dokumentu). W przypadku niepowodzenia próbuje stopniowo powiększać subdomeny. Jeśli to nie zadziała, spróbuje zapisać plik cookie bez domeny. Jeśli nie zostanie ustawiona żadna wartość, plik cookie zostanie zapisany bez podanej domeny. Uwaga: gdy plik cookie bez podanej domeny zostanie zapisany pod adresem document.cookie, klient użytkownika domyślnie ustawi jego domenę na hosta bieżącej lokalizacji dokumentu.
  • Ścieżka: ustawiona przez options['path'] (jeśli występuje). Gdy w adresie document.cookie zostanie zapisany plik cookie bez określonej ścieżki, klient użytkownika domyślnie ustawi ścieżkę pliku cookie na ścieżkę bieżącej lokalizacji dokumentu.
  • Max-Age: ustawiony 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ć, aby sformatować Date dla tego parametru.
  • Zabezpieczona: ustawiona przez zasadę 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 domyślną aktualizację zgody na przetwarzanie danych w celu jej przetworzenia od razu po wystąpieniu bieżącego zdarzenia i zakończeniu przetwarzania wszystkich wywołanych przez nie tagów (lub upłynięciu czasu oczekiwania na przetwarzanie tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed innymi elementami znajdującymi się w kolejce w warstwie danych. Więcej informacji o uzyskiwaniu zgody na wykorzystanie danych

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 typów zgody.

Obiekt consentSettings mapuje dowolne ciągi znaków typu zgody na jeden z tych elementó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ą podawane z wykorzystaniem krajów lub podziałów w formacie ISO 3166-2.
wait_for_update liczba Określa wartość milisekundową określającą czas oczekiwania na wysłanie danych. Używane z narzędziami do uzyskiwania zgody użytkowników, które ładują się asynchronicznie.

Powiązane uprawnienia

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

setInWindow

Ustawia wartość w parametrze window w danym kluczu. Domyślnie ta metoda nie ustawia wartości w elemencie window, jeśli wartość już istnieje. Ustaw overrideExisting na true, aby ustawić wartość window niezależnie od obecności wartości. Zwraca wartość boolean: true, jeśli wartość została ustawiona, lub false, jeśli wartość została ustawiona.

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w obiekcie 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 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 wynikowym skrótem zakodowanym w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.
onFailure funkcja Wywoływana, jeśli podczas obliczania skrótu wystąpi błąd lub jeśli przeglądarka nie obsługuje natywnej funkcji SHA256. Wywołanie zwrotne jest wywoływane z obiektem zawierającym nazwę błędu i komunikat.
options obiekt Opcjonalne obiekt opcji, który pozwala określić kodowanie wyjściowe. Jeśli został 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 pamięci szablonów. Miejsce na dane szablonu umożliwia udostępnianie danych między wykonaniami jednego szablonu. Dane przechowywane w pamięci szablonu pozostają dostępne 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 API toBase64 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 użytkownika, która zostanie przetworzona jak najszybciej po bieżącym zdarzeniu i po zakończeniu przetwarzania przez niego wywołanych przez niego tagach (lub po upływie czasu oczekiwania na przetwarzanie tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed innymi elementami znajdującymi się w kolejce w warstwie danych. Więcej informacji o uzyskiwaniu zgody

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 mapuje dowolne ciągi znaków typu zgody na jeden z tych elementów 'granted' lub 'denied'. Obsługuje te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Dla każdego rodzaju zgody można ustawić wartość „przyznano” lub „odrzucona”. Każda wartość inna niż „przyznana” będzie traktowana jako „odrzucona”. Ustawienie wartości „nieokreślona” nie będzie miało wpływu na jej poprzednią wartość.

Powiązane uprawnienia

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

Testowe interfejsy API

Te interfejsy API współpracują z testami JavaScript w trybie piaskownicy przy tworzeniu testów szablonów niestandardowych w Menedżerze tagów Google. Te testowe interfejsy API nie wymagają instrukcji require(). Więcej informacji o testach szablonów niestandardowych

assertApi

Zwraca obiekt dopasowania, którego można używać do płynnego formułowania 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 API assertThat jest modelowany na podstawie biblioteki Google [Truth]. Zwraca obiekt, którego można używać do płynnego formułowania twierdzeń na temat wartości podmiotu. Błąd asercji spowoduje natychmiastowe zatrzymanie testu i oznaczenie go jako nieudanego. Niepowodzenie w jednym teście nie będzie jednak mieć wpływu na pozostałe przypadki.

Składnia

assertThat(actual, opt_message)

Parametry

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

Dopasowania

Dopasowanie Opis
isUndefined() Wskazuje, że temat to undefined.
isDefined() Informuje, że tematem nie jest undefined.
isNull() Wskazuje, że temat to null.
isNotNull() Informuje, że tematem nie jest null.
isFalse() Wskazuje, że temat to false.
isTrue() Wskazuje, że temat to true.
isFalsy() Twierdzą, że temat jest zmyślony. Błędne wartości to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isTruthy() Twierdzą, że temat jest prawdziwy. Błędne wartości to undefined, null, false, NaN, 0 i „” (pusty ciąg znaków).
isNaN() Wskazuje, że obiekt jest wartością NaN.
isNotNaN() Wskazuje, że podmiot ma dowolną wartość poza NaN.
isInfinity() Twierdzi, że podmiot jest nieskończoność lub ujemną.
isNotInfinity() Wskazuje, że podmiot jest wartością inną niż dodatnia i ujemna Nieskończoność.
isEqualTo(expected) Wskazuje, że podmiot jest równy podanej wartości. Chodzi o porównanie wartości, a nie z danymi referencyjnymi. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Wskazuje, że podmiot nie jest równy podanej wartości. Chodzi o porównanie wartości, a nie z danymi referencyjnymi. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Wskazuje, że podmiot jest równy jednej z podanych wartości. Chodzi o porównanie wartości, a nie z danymi referencyjnymi. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Wskazuje, ż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) Wskazuje, że podmiot jest dokładnie równy (===) podanej wartości.
isNotStrictlyEqualTo(expected) Wskazuje, że podmiot nie jest ściśle równy (!==) podanej wartości.
isGreaterThan(expected) Wskazuje, że podmiot jest większy niż (>) podana wartość w porównaniu uporządkowanym.
isGreaterThanOrEqualTo(expected) Wskazuje, że obiekt jest większy lub równy (>=) podanej wartości w porównaniu uporządkowanym.
isLessThan(expected) Wskazuje, że obiekt jest mniejszy niż podana wartość (<) w uporządkowanym porównaniu.
isLessThanOrEqualTo(expected) Wskazuje, że obiekt jest mniejszy lub równy (<=) podanej wartości w porównaniu uporządkowanym.
contains(...expected) Informuje, że temat jest tablicą lub ciągiem znaków, który zawiera wszystkie podane wartości w dowolnej kolejności. Chodzi o porównanie wartości, a nie danych referencyjnych. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Wskazuje, że obiekt jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. Chodzi o porównanie wartości, a nie danych referencyjnych. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Wskazuje, że obiekt jest tablicą, która zawiera wszystkie podane wartości w dowolnej kolejności i nie zawiera żadnych innych wartości. Chodzi o porównanie wartości, a nie z danymi referencyjnymi. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Wskazuje, że obiekt jest tablicą, która zawiera inny zestaw wartości od podanych wartości w dowolnej kolejności. Chodzi o porównanie wartości, a nie z danymi referencyjnymi. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Wskazuje, że temat jest tablicą lub ciągiem znaków o podanej długości. Potwierdzenie kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isEmpty() Informuje, że obiekt jest tablicą lub ciągiem znaków, który jest pusty (długość = 0). Potwierdzenie kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isNotEmpty() Informuje, że podmiot jest tablicą lub ciągiem znaków, który nie jest pusty (długość > 0). Potwierdzenie kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isArray() Wskazuje, że typem podmiotu jest tablica.
isBoolean() Wskazuje, że typ tematu jest wartością logiczną.
isFunction() Wskazuje, że typ podmiotu jest funkcją.
isNumber() Wskazuje, że rodzaj tematu jest liczbą.
isObject() Wskazuje, że typ podmiotu jest obiektem.
isString() Wskazuje, ż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 przejdzie bieżącego testu i drukuje daną 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 API mock umożliwia zastąpienie działania interfejsów API w trybie piaskownicy. Przykładowy interfejs API można bezpiecznie używać w kodzie szablonu, ale nie działa, gdy nie jest 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 co przekazywany do require()
returnValue dowolny Wartość do zwrócenia dla interfejsu API lub funkcji wywoływanej w jego miejsce. Jeśli returnValue jest funkcją, jest ona wywoływana zamiast interfejsu API w trybie piaskownicy. Jeśli returnValue jest czymś innym niż funkcją, 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 wejściowym obiektem danych.

Składnia

runCode(data)

Parametry

Parametr Typ Opis
data obiekt Obiekt danych do użycia w teście.

Zwracana wartość

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

Przykład

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