Interfejsy API szablonów niestandardowych

Podstawowe interfejsy API

Interfejsy API współpracują z JavaScriptem w trybie piaskownicy do tworzenia szablonów niestandardowych w Menedżerze tagów Google. Każdy interfejs API jest dodawany do instrukcji require(), np.

const myAPI = require('myAPI');

addConsentListener

Rejestruje funkcję odbiornika do wykonania w przypadku zmiany stanu określonego typu zgody.

Dany odbiornik będzie wywoływany za każdym razem, gdy stan określonego typu zgody zmieni się z „Odrzucono” na „Przyznano” i „Odrzucono”. Typ zgody bez stanu jest uznawany za przyznany, więc odbiornik nie zostanie wywołany, gdy nieskonfigurowany typ zgody zostanie zmieniony. Za zapewnienie, że kod będzie uruchamiany odpowiednią liczbę razy, odpowiada funkcja detektora.

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 Zmieni się typ zgody, na której nasłuchuje stan.
listener Funkcja Funkcja do uruchomienia w przypadku zmiany stanu określonego typu zgody.

Wywołanie odbiornika powoduje przekazanie zmienionego typu zgody i jej nowej wartości:

Parametr Typ Opis
consentType ciąg znaków zmiana rodzaju zgody,
granted boolean, Wartość logiczna, która ma wartość „prawda”, jeśli określony typ zgody zostanie zmieniony na przyznany.

Powiązane uprawnienia

access_consent z uprawnieniami do odczytu typu zgody.

addEventCallback

Interfejs API addEventCallback umożliwia zarejestrowanie funkcji wywołania zwrotnego, która jest wywoływana na końcu zdarzenia. Wywołanie zwrotne jest wywoływane po wykonaniu wszystkich tagów dla zdarzenia lub gdy upłynie limit czasu zdarzenia na stronie. Wywołanie zwrotne przekazuje 2 wartości – identyfikator kontenera wywołującego funkcję oraz obiekt zawierający informacje o zdarzeniu.

Składnia

addEventCallback(callback)

Parametry

Parametr Typ Opis
callback Funkcja Funkcja, która ma być wywoływana na końcu zdarzenia.

Obiekt eventData zawiera te dane:

Nazwa klucza Typ Opis
tags Tablica Tablica obiektów danych tagów. Każdy tag, który został uruchomiony podczas zdarzenia, będzie zawierać w tej tablicy odpowiedni wpis. Obiekt danych tagu zawiera identyfikator tagu (id), stan wykonania (status) i czas wykonania (executionTime). Dane tagu będą zawierać dodatkowe metadane 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 API aliasInWindow umożliwia utworzenie aliasu (np. window.foo = window.bar), który ułatwia obsługę określonych tagów wymagających aliasów. Przypisuje wartość w obiekcie window znalezionym w fromPath do klucza w obiekcie window w toPath. Zwraca wartość true, jeśli jest udana, false.

Składnia

aliasInWindow(toPath, fromPath)

Parametry

Parametr Typ Opis
toPath ciąg znaków Ścieżka rozdzielana kropkami w obiekcie window, do którego chcesz skopiować wartość. Obiekt w ścieżce do ostatniego komponentu musi już istnieć w obiekcie window.
fromPath ciąg znaków Ścieżka rozdzielana kropkami do wartości window, którą chcesz skopiować. Jeśli wartość nie istnieje, operacja się nie uda.

Przykład

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

Powiązane uprawnienia

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

callInWindow

Umożliwia wywoływanie funkcji ze ścieżki spoza obiektu window w sposób kontrolowany przez zasadę. Wywołuje funkcję w danej ścieżce w window z podanymi argumentami i zwraca wartość. Jeśli określonego typu wywołania nie można bezpośrednio zmapować na typ obsługiwany w kodzie JavaScript w trybie piaskownicy, zwracana jest wartość undefined. W JavaScript w trybie piaskownicy działa 8 typów: null, undefined, boolean, number, string, Array, Object i function. Jeśli podana ścieżka nie istnieje lub nie odwołuje się do funkcji, zostanie zwrócona wartość undefined.

Składnia

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

Parametry

Parametr Typ Opis
pathToFunction ciąg znaków Ścieżka rozdzielana kropkami w funkcji window do wywołania.
args * Argumenty przekazywane do funkcji.

Powiązane uprawnienia

access_globals z włączonymi uprawnieniami execute.

callLater

Planuje wywołanie funkcji w sposób asynchroniczny. Funkcja zostanie wywołana po zwróceniu bieżącego kodu. To odpowiednik setTimeout(<function>, 0).

Składnia

callLater(function)

Parametry

Parametr Typ Opis
function Funkcja Funkcja, która ma być wywoływana.

copyFromDataLayer

Zwraca wartość obecnie przypisaną do danego klucza w warstwie danych: wartość znalezioną w danym kluczu, 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 ma format „a.b.c”.
dataLayerVersion liczba Opcjonalna wersja warstwy danych. Wartość domyślna to 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 bezpośrednio zmapować na typ obsługiwany w JavaScript w trybie piaskownicy, zostanie zwrócona wartość undefined. Osiem typów obsługiwanych przez JavaScript w trybie piaskownicy to null, undefined, boolean, number, string, Array, Object i function. Zwraca wartość pobranych (i wymuszonych)

Składnia

copyFromWindow(key)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w window, aby skopiować wartość.

Powiązane uprawnienia

access_globals

createArgumentsQueue

Tworzy kolejkę zawierającą obiekty z argumentami, która obsługuje rozwiązania, które tego wymagają.

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

Po wywołaniu funkcji utworzonej w funkcji fnKey obiekt jej argumentu jest przekazywany do tablicy utworzonej w elemencie arrayKey. Zwracana wartość interfejsu API to funkcja utworzona w metodzie fnKey.

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

Przykład:

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

Składnia

createArgumentsQueue(fnKey, arrayKey)

Parametry

Parametr Typ Opis
fnKey ciąg znaków Ścieżka w sekcji window, w której funkcja jest ustawiona, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis kropki. Jeśli ścieżka klucza nie istnieje, zostanie zgłoszony wyjątek. Oznacza to, że jeśli fnKey ma wartość 'one.two', zostanie zgłoszony wyjątek.
arrayKey ciąg znaków Ścieżka w window, w której ustawiona jest tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis kropki. 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', zostanie zgłoszony wyjątek.

Powiązane uprawnienia

access_globals

createQueue

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

Ta funkcja wymaga ustawienia access_globals do odczytu i zapisu na poziomie arrayKey.

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 została ustawiona tablica, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis kropki. Jeśli ścieżka klucza nie istnieje, zostanie zgłoszony wyjątek. Jeśli na przykład arrayKey ma wartość 'one.two', a obiekt globalny o nazwie 'one' nie istnieje, zostanie zgłoszony wyjątek.

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, jeśli podano nieprawidłowe dane.

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 identyfikatora URI. Zwraca wartość undefined, jeśli podano nieprawidłowe dane.

Przykład:

const decode = require('decodeUriComponent');

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

Składnia

decodeUriComponent(encoded_uri_component)

Parametry

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

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI (uniwersalny identyfikator zasobu), zmieniając znaczenie znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined, jeśli podano nieprawidłowe dane (samodzielny zastępnik).

Przykład:

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

Składnia

encodeUri(uri)

Parametry

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

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI (uniwersalny identyfikator zasobu), zmieniając znaczenie znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca wartość undefined, jeśli podano nieprawidłowe dane (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 base64. Zwraca wartość undefined, jeśli podano nieprawidłowe dane.

Składnia

fromBase64(base64EncodedString)

Parametry

Parametr Typ Opis
base64EncodedString ciąg znaków Ciąg znaków 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ą) w danym zakresie.

Składnia

generateRandom(min, max)

Parametry

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

Powiązane uprawnienia

Brak.

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwracany obiekt będzie 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() kodu JavaScript. Domyślna wartość to true.

Powiązane uprawnienia

get_cookies

getQueryParameters

Zwraca pierwszy lub wszystkie parametry bieżącego adresu URL (queryKey). Zwraca pierwszą wartość z queryKey lub tablica wartości z queryKey.

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz do odczytu 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:

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

getReferrerQueryParameters

Interfejs API getReferrerQueryParameters działa tak samo jak getQueryParameters, z wyjątkiem działania strony odsyłającej, a nie bieżącego adresu URL. Zwraca pierwszy lub wszystkie parametry queryKey źródła odsyłającej. Zwraca pierwszą wartość z queryKey lub tablica wartości z queryKey.

Składnia

getReferrerQueryParameters(queryKey[, retrieveAll])

Parametry

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

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

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

Powiązane uprawnienia

get_referrer musi zezwalać na komponent query i musi wskazywać queryKey w dozwolonych kluczach zapytań (lub na dowolny dowolny klucz zapytania).

getReferrerUrl

Biorąc pod uwagę typ komponentu, interfejs API odczytuje obiekt dokumentu dla 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, który ma być zwracany z adresu URL. Dostępne 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 wskazywać queryKey w dozwolonych kluczach zapytań (lub na dowolny dowolny klucz zapytania).

getTimestamp

Wycofane. Wybierz getTimestampMillis.

Zwraca liczbę oznaczającą bieżący czas w milisekundach od czasu uniksowego, zwracany przez funkcję Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę oznaczającą bieżący czas w milisekundach od czasu uniksowego, zwracany przez funkcję 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 getType umożliwia rozróżnianie między array a object.

Składnia

getType(data.someField)

Notes

W tabeli poniżej znajdziesz ciągi tekstowe zwracane w przypadku każdej wartości wejściowej.

Wartość wejściowa Wynik
undefined 'nieokreślony'
null 'null'
true „wartość logiczna”
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 lub część bieżącego adresu URL, z uwzględnieniem typu komponentu i niektórych parametrów konfiguracyjnych.

Składnia

getUrl(component)

Parametry

Parametr Typ Opis
component ciąg znaków Komponent, który ma być 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, zostanie zwrócona cała wartość href.

Powiązane uprawnienia

get_url

gtagSet

Wysyła polecenie zestawu tagów gtag do warstwy danych, które ma zostać przetworzone natychmiast po zakończeniu bieżącego zdarzenia i wprowadzonych przez niego tagach (lub po osiągnięciu limitu przetwarzania tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce warstwy danych.

Jeśli na przykład wywołany jest tag wywołany przez zainicjowanie zgody, aktualizacja zostanie zastosowana przed przetworzeniem zdarzenia inicjowania. Na przykład ads_data_redaction ma wartość true, false, url_passthrough jest 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 w dataLayer uprawnienia do zapisu dla wszystkich określonych kluczy. Jeśli dane wejściowe gtagSet są zwykłym obiektem, API będzie sprawdzać uprawnienia do zapisu dla wszystkich spłaszczonych kluczy w obiekcie, np. gtagSet({foo: {bar: 'baz'}}), w przypadku interfejsu API sprawdza uprawnienie do zapisu dla elementu foo.bar.

Jeśli dane wejściowe gtagSet są kluczem i inną wartością obiektu innego niż zwykły, interfejs API sprawdzi uprawnienia do zapisu tego klucza, np. w przypadku gtagSet('abc', true) będzie sprawdzać uprawnienia do zapisu w interfejsie 'abc'.

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

injectHiddenIframe

Dodaje niewidoczny element iframe do strony.

Wywołania zwrotne są traktowane jako instancje funkcji i są zawarte w funkcjach JavaScriptu, które do nich odwołują się.

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, gdy ramka zostanie wczytana.

Powiązane uprawnienia

inject_hidden_iframe

injectScript

Dodaje do strony tag skryptu, który wczytuje asynchronicznie dany adres URL. Wywołania zwrotne są traktowane jako instancje funkcji i są zawarte w funkcjach JavaScriptu, które do nich odwołują się.

Składnia

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

Parametry

Parametr Typ Opis
url ciąg znaków Adres skryptu, który ma zostać wstrzyknięty.
onSuccess Funkcja Wywoływane po załadowaniu skryptu.
onFailure Funkcja Wywoływane, gdy nie uda się wczytać skryptu.
cacheToken ciąg znaków Opcjonalny ciąg znaków używany do wskazania danego adresu URL w pamięci podręcznej. Jeśli ta wartość jest określona, utworzony zostanie tylko 1 element skryptu, który wysyła żądanie JavaScriptu. Każda kolejna próba ładowania spowoduje, że podane metody onSuccess i onFailure zostaną dodane do kolejki do momentu załadowania skryptu.

Powiązane uprawnienia

inject_script

isConsentGranted

Zwraca wartość „true”, jeśli użytkownik wyraził zgodę na określony typ zgody.

Uznaje się, że określony rodzaj zgody jest udzielany, jeśli ustawiono jako „Przyznano” lub w ogóle go nie ustawiono. Jeśli ustawisz inny typ zgody, nie zostanie ona uznana.

Ustawienia Menedżera tagów w sekcji Ustawienia tagu będą zawsze zawierać opcję uruchomienia. Jeśli tag z włączonym automatycznym uruchamianiem używa tego interfejsu API, zgoda jest uznawana za uzyskaną i zwracana jest true, niezależnie od rzeczywistego stanu zgody użytkownika.

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óry chcesz sprawdzić.

Powiązane uprawnienia

access_consent z uprawnieniami do odczytu typu zgody.

JSON

Zwraca obiekt z funkcjami JSON.

Funkcja parse() analizuje ciąg JSON, tworząc wartość lub obiekt opisany przez ciąg znaków. Jeśli nie można przeanalizować wartości (np. w złym formacie JSON), funkcja zwróci undefined. Jeśli dane wejściowe nie są ciągiem, dane wejściowe zostaną zmienione na 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 ma cykl), metoda zwróci undefined.

Składnia

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

Parametry

JSON.parse,

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

JSON.stringify,

Parametr Typ Opis
wartość dowolny Wartość 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 dostępem 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 w konsoli przeglądarki argumenty.

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ę (liczbę całkowitą).

Składnia

makeInteger(value)

Parametry

Parametr Typ Opis
value dowolny Wartość konwersji.

Powiązane uprawnienia

Brak.

makeNumber

Konwertuje podaną wartość na liczbę.

Składnia

makeNumber(value)

Parametry

Parametr Typ Opis
value dowolny Wartość 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ść konwersji.

Powiązane uprawnienia

Brak.

makeTableMap

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

Na przykład ta funkcja może przekonwertować obiekt tabeli:

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

do mapy:

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

Zwraca obiekt: przekonwertowana para Map: jeśli zostały do niej dodane pary klucz-wartość, lub null.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametry

Parametr Typ Opis
tableObj Wyświetl listę Obiekt tabeli do przekonwertowania. Jest to lista map, z których każdy Map reprezentuje wiersz w tabeli. Każda nazwa właściwości w obiekcie wiersza to nazwa kolumny, a wartość właściwości jest wartością kolumny w wierszu.
keyColumnName ciąg znaków Nazwa kolumny, której wartości staną się kluczami w przekonwertowanym obiekcie Map.
valueColumnName ciąg znaków Nazwa kolumny, której wartości staną się wartościami w Map po konwersji.

Powiązane uprawnienia

Brak.

Math

Obiekt dostarczają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() udostępnia zachowanie obiektów Object.keys() w Bibliotece standardowej. Zwraca tablicę własnych właściwości liczbowych właściwości danego obiektu w takiej samej kolejności jak pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona zmieniona na obiekt.

Metoda values() udostępnia zachowanie obiektów Object.values() w Bibliotece standardowej. Zwraca tablicę własnych wartości liczbowych właściwości danego obiektu w takiej samej kolejności jak pętla for...in.... Jeśli dane wejściowe nie są obiektami, zostaną zmienione na obiekt.

Metoda entries() udostępnia zachowanie standardowej biblioteki Object.entries(). Zwraca tablicę własnych właściwości liczbowych [key, value] danego obiektu w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie ona zmieniona na obiekt.

Metoda freeze() udostępnia zachowanie standardowej biblioteki Object.rost(). Zablokowanego obiektu nie można już zmienić. Zablokowanie obiektu uniemożliwia dodanie do niego nowych usług, usunięcie istniejących właściwości oraz zmianę istniejących. freeze() zwraca ten sam obiekt, który został przekazany. Argument obiektu podstawowego lub pustego jest traktowany tak, jakby był zablokowany, i zostanie zwrócony.

Metoda delete() udostępnia operator Delete w Bibliotece standardowej. Usuwa on dany klucz z obiektu, chyba że jest on zablokowany. Podobnie jak operator usuwania biblioteki standardowej, zwraca true, jeśli pierwsza wartość wejściowa (objectInput) jest obiektem, który nie zostanie 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 Biblioteki standardowej w następujący sposób:

  • keyToDelete nie może być ciągiem rozdzielanym kropkami określającym klucz zagnieżdżony.
  • Funkcji delete() nie można używać do usuwania elementów z tablicy.
  • delete() nie może służyć do usuwania żadnych właściwości z zakresu globalnego.

Składnia

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

Parametry

Obiekty.keys

Parametr Typ Opis
obiekt wejściowych dowolny Obiekt, którego klucze mają być wyliczane. Jeśli dane wejściowe nie są obiektami, zostaną zmienione na obiekt.

Object.values

Parametr Typ Opis
obiekt wejściowych dowolny Obiekt, którego wartości zostaną obliczone. Jeśli dane wejściowe nie są obiektami, zostaną zmienione na obiekt.

Obiekty.entries

Parametr Typ Opis
obiekt wejściowych dowolny Obiekt, którego pary klucz/wartość do wyliczenia. Jeśli dane wejściowe nie są obiektami, zostaną zmienione na obiekt.

Obiekt.zamrożenie

Parametr Typ Opis
obiekt wejściowych dowolny Obiekt do zablokowania. Jeśli dane wejściowe nie są obiektami, będą traktowane jako zablokowany element.

Object.delete

Parametr Typ Opis
obiekt wejściowych dowolny Obiekt, którego klucz do usunięcia.
Usuwanie klucza 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 komponenty składowe danego adresu URL, podobny do obiektu URL.

Ten interfejs API zwróci błąd undefined w przypadku nieprawidłowego formatu adresu URL. W przypadku prawidłowo sformatowanych adresów URL pola, które nie znajdują się w ciągu adresu URL, będą miały wartość pustego ciągu, a w przypadku searchParams – pusty obiekt.

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

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

Przykład

const parseUrl = require('parseUrl');

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

Składnia

parseUrl(url);

Parametry

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

Powiązane uprawnienia

Brak.

queryPermission

Wyślij zapytanie o uprawnienia dozwolone i zawężone. Zwraca wartość logiczną true, jeśli uprawnienie zostało przyznane, lub false w innym przypadku.

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 poszukiwanego uprawnienia. Zapoznaj się z sekcją Argumenty funkcji poniżej.

Argumenty funkcji

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

writeGlobals, readGlobals: drugi parametr powinien być zapisanym lub odczytanym kluczem.

readUrl: nie trzeba używać dodatkowych argumentów, by sprawdzić, czy można odczytać cały adres URL. Aby wysłać zapytanie, czy określony komponent można odczytać, przekaż jego nazwę 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óre można wywołać z programu. Zwraca wartość undefine, jeśli 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

Powoduje wysłanie żądania 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ływane po załadowaniu piksela. Uwaga: nawet jeśli żądanie zostanie wysłane, przeglądarki do poprawnego działania mogą wymagać prawidłowej odpowiedzi obrazu.
onFailure Funkcja Wywoływane, gdy nie można wczytać piksela. Uwaga: nawet jeśli żądanie zostanie wysłane, narzędzie OnFailure może zostać uruchomione, jeśli serwer nie zwraca 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, Maks. wiek, Bezpieczne i SameSite. (zobacz Opcje poniżej).
encode boolean, Określa, czy wartość pliku cookie ma być kodowana za pomocą encodeURIComponent() kodu JavaScript. Domyślna wartość to true.

Opcje

  • Domena: ustawiona przez właściwość options['domain'] (jeśli istnieje). Ustaw tę wartość na 'auto', aby zapisać plik cookie w jak najszerszej domenie na podstawie lokalizacji dokumentu. Jeśli to się nie uda, spróbuje kolejno kolejne subdomeny. Jeśli nie uda się to zrobić, spróbuje zapisać plik cookie bez domeny. Jeśli nie ustawisz żadnej wartości, spróbuje zapisać plik cookie bez określania domeny. Uwaga: gdy plik cookie bez określonej domeny jest zapisywany w polu document.cookie, klient użytkownika domyślnie ustawia domenę pliku cookie na bieżącą lokalizację dokumentu.
  • Ścieżka: ustawiona przez options['path'], jeśli występuje. Gdy w pliku document.cookie zostanie zapisany plik cookie bez określonej ścieżki, klient użytkownika będzie domyślnie ustawiał ścieżkę do bieżącej lokalizacji dokumentu.
  • Max-Age: wartość ustawiona przez options['max-age'], jeśli występuje.
  • Data ważności: ustawiona przez użytkownika options['expires'] (jeśli występuje). Jeśli jest obecny, musi być ciągiem znaków daty UTC. Date.toUTCString() może służyć do formatowania Date dla tego parametru.
  • Bezpieczna:ustawiona na options['secure'], jeśli występuje.
  • SameSite: ustawiana przez zasadę options['samesite'] (jeśli występuje).

Powiązane uprawnienia

set_cookies

setDefaultConsentState

Wysyła domyślną aktualizację zgody do warstwy danych, która ma zostać przetworzona natychmiast po zakończeniu bieżącego zdarzenia i w przypadku wszystkich uruchamianych przez niego tagów (lub gdy upłynie limit czasu przetwarzania tagów). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce w warstwie danych. Więcej informacji o zgodzie

Przykład:

const setDefaultConsentState = require('setDefaultConsentState');

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

Składnia

setDefaultConsentState(consentSettings)

Parametry

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

Obiekt consentSettings jest odwzorowaniem dowolnych ciągów typów zgody na przetwarzanie danych takich jak 'granted' lub 'denied'. Obsługiwane są te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków W przypadku każdego rodzaju zgody można ustawić wartość „Przyznano” lub „Odrzucono”. Wszystkie wartości inne niż „Przyznano” będą traktowane jako „odrzucone”. Ustawienie wartości „niezdefiniowane” nie będzie miało żadnego wpływu na poprzednią wartość.
region Tablica Opcjonalna tablica kodów regionów określających region, do którego mają zastosowanie ustawienia dotyczące zgody użytkownika. Kody regionów są podawane przy użyciu kraju lub podgrup w formacie ISO 3166-2.
wait_for_update liczba Określa milisekundę, aby określić czas oczekiwania na wysłanie danych. Używane z narzędziami do uzyskiwania zgody, które ładują się asynchronicznie.

Powiązane uprawnienia

access_consent z uprawnieniami do zapisu w przypadku wszystkich typów zgód w obiekcie ConsentSettings.

setInWindow

Ustawia określoną wartość w polu window dla danego klucza. Domyślnie ta metoda nie ustawia wartości w polu window, jeśli masz już określoną wartość. Ustaw overrideExisting na true, aby ustawić wartość w window, niezależnie od obecności istniejącej wartości. Zwraca wartość logiczną (true), jeśli wartość została ustawiona, lub false.

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w języku window umożliwiający umieszczenie wartości.
value * Wartość do ustawienia w zasadzie window.
overrideExisting boolean, Flaga wskazująca, że wartość powinna być ustawiona w window, niezależnie od tego, czy zawiera wartość.

Powiązane uprawnienia

access_globals

sha256

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

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 chcesz obliczyć wartość skrótu.
onSuccess Funkcja Wywołuje się wynikowe kodowanie w formacie base64, chyba że obiekt options określa inne kodowanie danych wyjściowych.
onFailure Funkcja Wywoływane, jeśli podczas obliczania skrótu wystąpił błąd lub przeglądarka nie obsługuje natywnego szyfrowania sha256. Wywołanie zwrotne jest wywoływane z obiektem zawierającym nazwę błędu i komunikat.
options obiekt Opcjonalne, aby określić kodowanie wyjściowe. Jeśli jest określony, obiekt powinien zawierać klucz outputEncoding z wartością base64 lub hex.

Powiązane uprawnienia

Brak.

templateStorage

Zwraca obiekt z metodami uzyskiwania dostępu do magazynu szablonów. Pamięć szablonu umożliwia udostępnianie danych między uruchomieniami jednego szablonu. Dane przechowywane w szablonie 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 postaci reprezentacji 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 aktualizację zgody do warstwy danych w celu przetworzenia tak szybko, jak to możliwe, po zakończeniu bieżącego zdarzenia i wszelkich uruchamianych przez nie tagów (lub gdy osiągnięto limit czasu przetwarzania tagów). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed jakimikolwiek elementami dodanymi do kolejki 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 aktualizujący stan określonych typów zgody.

Obiekt consentSettings jest odwzorowaniem dowolnych ciągów typów zgody na przetwarzanie danych takich jak 'granted' lub 'denied'. Obsługiwane są te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Wartością każdego rodzaju zgody może być „Przyznano” lub „Odrzucono”. Wszystkie wartości inne niż „udzielono” będą traktowane jako „odrzucone”. Ustawienie wartości jako „nieokreślona” nie będzie miało żadnego wpływu na poprzednią wartość.

Powiązane uprawnienia

access_consent z uprawnieniami do zapisu w przypadku wszystkich typów zgód w obiekcie ConsentSettings.

Przetestuj interfejsy API

Interfejsy API współpracują z testami JavaScript w trybie piaskownicy, aby tworzyć testy niestandardowych szablonów 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óry może być płynnie używany do podawania danego interfejsu API.

Składnia

assertApi(apiName)

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API, który należy sprawdzić; ten sam ciąg znaków, który został przekazany do require().

Pasujące

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

Przykłady

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

assertThat

Interfejs API assertThat jest wzorowany na bibliotece Google [Truth]. Zwraca obiekt, który umożliwia płynne przedstawianie wartości obiektu. Nie udało się zatrzymać testu i oznaczyć go jako niepowodzenie. Jednak błąd w jednym teście nie będzie miał wpływu na pozostałe przypadki testowe.

Składnia

assertThat(actual, opt_message)

Parametry

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

Pasujące

Dopasowanie Opis
isUndefined() Twierdzi, że temat to undefined.
isDefined() Twierdzi, że temat to nie undefined.
isNull() Twierdzi, że temat to null.
isNotNull() Twierdzi, że temat to nie null.
isFalse() Twierdzi, że temat to false.
isTrue() Twierdzi, że temat to true.
isFalsy() Twierdzi, że temat jest zniekształcony. Wartości Fals to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isTruthy() Stwierdza, że podmiot jest prawdziwy. Wartości Fals to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isNaN() Twierdzi, że obiekt jest wartością NaN.
isNotNaN() Stwierdza, że podmiot nie ma wartości „NN”.
isInfinity() Twierdzi, że podmiot jest dodatni lub nieskończony.
isNotInfinity() Twierdzi, że podmiotem jest dowolna wartość dodatnia lub ujemna.
isEqualTo(expected) stwierdza, że obiekt jest równy podanej wartości. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Stwierdza, że temat nie jest równy podanej wartości. To jest porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isAnyOf(...expected) Stwierdza, że temat jest równy jednej z podanych wartości. To jest porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNoneOf(...expected) Stwierdza, że temat nie jest równa żadnej z podanych wartości. To jest porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Stwierdza, że temat jest identyczny (===) z podaną wartością.
isNotStrictlyEqualTo(expected) Stwierdza, że temat nie jest ściśle równy !==.
isGreaterThan(expected) Stwierdza, że temat jest większy niż (>) dana wartość w porównaniu porównawczym.
isGreaterThanOrEqualTo(expected) Stwierdza, że temat jest większy lub równy podanej wartości (>=) w porównaniu porównawczym.
isLessThan(expected) Stwierdza, że obiekt jest mniejszy niż (<) podaną wartość w uporządkowanej porównaniu.
isLessThanOrEqualTo(expected) twierdzi, że obiekt jest mniejszy lub równy (<=) danej wartości w uporządkowanej analizie.
contains(...expected) Twierdzi, że temat jest tablicą lub ciągiem znaków zawierającym wszystkie podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Twierdzi, że temat jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Twierdzi, że temat jest tablicą zawierającą wszystkie podane wartości w dowolnej kolejności, bez żadnych innych wartości. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Stwierdza, że temat to tablica zawierająca inny zbiór wartości niż podane wartości w dowolnej kolejności. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Twierdzi, że temat jest tablicą lub ciągiem o określonej długości. Asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isEmpty() Twierdzi, że temat jest tablicą lub ciągiem pustym (length = 0). Asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isNotEmpty() Twierdzi, że temat jest tablicą lub ciągiem 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() Twierdzi, że typ podmiotu to tablica.
isBoolean() Twierdzi, że typ podmiotu jest wartością logiczną.
isFunction() Twierdzi, że typ podmiotu to funkcja.
isNumber() Twierdzi, że typ podmiotu to liczba.
isObject() Twierdzi, że typ podmiotu jest obiektem.
isString() Twierdzi, że typ podmiotu 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

Natychmiastowy test bieżącego wyniku kończy się niepowodzeniem i drukuje podaną wiadomość.

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 piaskownicy. Interfejs API pozornego jest bezpieczny w kodzie szablonu, ale nie działa w trybie testowym. Próby są resetowane przed uruchomieniem każdego testu.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API makiety; ten sam ciąg znaków, który został przekazany do require()
returnValue dowolny Wartość do zwrócenia dla interfejsu API lub funkcja wywoływana zamiast interfejsu API. Jeśli returnValue jest funkcją, która jest używana zamiast interfejsu Sandbox API, ta funkcja jest wywoływana zamiast interfejsu Sandbox API. Jeśli returnValue jest funkcją inną niż ta, zwracana jest wartość zamiast interfejsu Sandbox API.

Przykłady

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

runCode

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

Składnia

runCode(data)

Parametry

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

Wartość zwrotu

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

Przykład

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