Interfejsy API szablonów niestandardowych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Podstawowe interfejsy API

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

const myAPI = require('myAPI');

addConsentListener

Rejestruje funkcję detektora do wykonywania 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” lub „Odrzucono”. Typ zgody bez stanu jest uznawany za przyznany, więc odbiornik nie zostanie wywołany, jeśli nieskonfigurowany typ zgody zostanie przyznany. Za działanie słuchaczy będzie odpowiadała określona liczba wystąpień kodu.

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 zmienia się.
listener funkcja Funkcja do uruchomienia w przypadku zmiany stanu określonego typu zgody.

Po wywołaniu odbiornika przekazuje typ zgody, który jest zmieniany, oraz jego nową wartość:

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

Powiązane uprawnienia

access_consent z uprawnieniami do odczytu dla typu zgody.

addEventCallback

Interfejs addEventCallback API pozwala zarejestrować funkcję wywołania zwrotnego, która zostanie wywołana na końcu zdarzenia. Wywołanie zwrotne zostanie wykonane po wykonaniu wszystkich tagów dla zdarzenia lub po upływie czasu oczekiwania na zdarzenie na stronie. Wywołanie zwrotne jest przekazywane 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ł wpis w tej tablicy. Obiekt danych tagu zawiera identyfikator tagu (id), stan wykonania (status) i czas jego wykonania (executionTime). Dane tagu będą też zawierać dodatkowe metadane tagu skonfigurowane na poziomie 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 pomaga obsługiwać niektóre tagi wymagające aliasów. Powoduje przypisanie wartości w obiekcie window znalezionym w fromPath do klucza obiektu window w obiekcie toPath. Zwraca wartość true, jeśli operacja się powiedzie. false w innym przypadku.

Składnia

aliasInWindow(toPath, fromPath)

Parametry

Parametr Typ Opis
toPath ciąg znaków Ścieżka rozdzielona kropkami do obiektu window, do którego ma zostać skopiowana wartość. W komponencie window wszystkie komponenty na ścieżce do ostatniego komponentu muszą już istnieć.
fromPath ciąg znaków Ścieżka oddzielona kropką do window. Jeśli wartość nie istnieje, operacja się nie uda.

Przykład

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

Powiązane uprawnienia

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

callInWindow

Pozwala wywoływać funkcje ze ścieżki spoza obiektu window w sposób kontrolowany przez zasadę. Wywołuje funkcję w danej ścieżce w window z określonymi argumentami i zwraca wartość. Jeśli typu zwrotu nie można bezpośrednio zmapować na typ obsługiwany w JavaScript w trybie piaskownicy, zwracana jest wartość undefined. JavaScript w trybie piaskownicy obsługuje 8 typów: null, undefined, boolean, number, string, Array, Object i function. Jeśli dana ścieżka nie istnieje lub nie odwołuje się do danej funkcji, zostanie zwrócona wartość undefined.

Składnia

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

Parametry

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

Powiązane uprawnienia

access_globals z włączonym uprawnieniem execute.

callLater

Planuje wywołanie funkcji, która odbywa się asynchronicznie. Funkcja będzie wywoływana po zwróceniu bieżącego kodu. 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ść znalezioną w przypadku danego klucza, jeśli jest to typ podstawowy, funkcja lub literał obiektu. W przeciwnym razie zwraca wartość undefined.

Składnia

copyFromDataLayer(key[, dataLayerVersion])

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w formacie „a.b.c”.
dataLayerVersion liczba Opcjonalna wersja warstwy danych. Wartość 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 window nie można zmapować bezpośrednio na typ obsługiwany w JavaScript w trybie piaskownicy, zostanie zwrócona wartość undefined. Osiem typów obsługiwanych przez kod JavaScript w trybie piaskownicy to null, undefined, boolean, number, string, Array, Object i function. Zwraca wartość pobraną (i wymuszoną).

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ę wypełnioną obiektami argumentów – aby obsługiwać rozwiązania, które ich wymagają.

Tworzy funkcję z zakresu globalnego (tj. window) z argumentem fnKey (taką samą semantyką jak createQueue). Po utworzeniu funkcji ten interfejs API tworzy tablicę w komórce window (jeśli jeszcze nie istnieje), używając argumentu arrayKey.

Po wywołaniu funkcji utworzonej w funkcji fnKey obiekt argumentu jest przenoszony do tablicy utworzonej w arrayKey. Wartość zwracana przez API to funkcja utworzona w fnKey.

Ta funkcja wymaga ustawienia fnKey do arrayKey odczytu i zapisu na poziomie 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 window, w której funkcja jest ustawiona, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis kropek. Jeśli ścieżka klucza nie istnieje, zostanie podany wyjątek. To oznacza, że jeśli fnKey to 'one.two', zostanie określony wyjątek.
arrayKey ciąg znaków Ścieżka w window, w której ustawiono tablicę, jeśli jeszcze nie istnieje. Ten argument obsługuje standardowy zapis kropek. Jeśli ścieżka klucza nie istnieje, zostanie podany wyjątek. Oznacza to, że jeśli arrayKey to 'one.two', a obiekt globalny o nazwie 'one' nie istnieje, zostanie utworzony wyjątek.

Powiązane uprawnienia

access_globals

createQueue

Tworzy tablicę w window (jeśli jeszcze nie istnieje) i zwraca funkcję, która będzie przekazywać do niej wartości.

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

Przykład:

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

Składnia

createQueue(arrayKey)

Parametry

Parametr Typ Opis
arrayKey ciąg znaków Klucz w window, w którym została ustawiona tablica, jeśli nie istnieje. Ten argument obsługuje standardowy zapis kropek. Jeśli ścieżka klucza nie istnieje, zostanie podany wyjątek. Jeśli na przykład arrayKey to 'one.two', a nie ma obiektu globalnego o nazwie 'one', zostanie utworzony wyjątek.

Powiązane uprawnienia

access_globals

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym identyfikatorze URI. Zwraca ciąg znaków, który reprezentuje zdekodowany identyfikator URI. Zwraca wartość undefined po podaniu nieprawidłowych danych.

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

Powiązane uprawnienia

Brak.

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie URI. Zwraca ciąg znaków, który reprezentuje zdekodowany komponent URI. Zwraca wartość undefined, jeśli podana wartość jest nieprawidłowa.

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

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier), zmieniając znaczenie znaków specjalnych. Zwraca ciąg znaków, który reprezentuje podany ciąg znaków zakodowany jako identyfikator URI.

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 (Uniform Resource Identifier), zmieniając znaczenie znaków specjalnych. Zwraca ciąg znaków, który reprezentuje podany ciąg znaków zakodowany jako identyfikator URI.

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 została podana z nieprawidłowymi danymi.

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 bieżącego kontenera. 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 wartość logiczna Określa, czy wartości plików cookie mają być dekodowane za pomocą JavaScriptu decodeURIComponent(). Domyślna wartość to true.

Powiązane uprawnienia

get_cookies

getQueryParameters

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

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

Parametr Typ Opis
queryKey ciąg znaków Klucz, który należy odczytać z parametrów zapytania.
retrieveAll wartość logiczna Określa, czy pobrać wszystkie wartości.

Jeśli np. obecny adres URL to https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo, to:

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

Powiązane uprawnienia

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

getReferrerQueryParameters

Interfejs getReferrerQueryParameters API działa tak samo jak getQueryParameters, z wyjątkiem działania strony odsyłającej, a nie obecnego adresu URL. Zwraca pierwszy lub wszystkie parametry elementu queryKey strony 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, który należy odczytać z parametrów zapytania.
retrieveAll wartość logiczna Określa, czy pobrać wszystkie wartości.

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

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

Powiązane uprawnienia

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

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

getTimestamp

Wycofane. Wybierz getTimestampMillis.

Zwraca liczbę odpowiadającą aktualnej godzinie w milisekundach od początku epoki uniksowej, zwracaną przez funkcję Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę odpowiadającą aktualnej godzinie w milisekundach od początku epoki uniksowej, zwracaną 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 różni się między array a object.

Składnia

getType(data.someField)

Notes

Poniższa tabela zawiera ciągi tekstowe zwrócone dla każdej wartości wejściowej.

Wartość wejściowa Wynik
undefined „nieokreślony”
null „null”
true „wartość logiczna”
12 „number”
'string' „ciąg”
{ a: 3 } „object”
[ 1, 3 ] „tablica”
(x) => x + 1 „funkcja”

Powiązane uprawnienia

Brak.

getUrl

Zwraca ciąg znaków, który reprezentuje cały adres URL lub jego część, dla danego typu komponentu i określonych 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 tych komponentów, zostanie zwrócona cała wartość href.

Powiązane uprawnienia

get_url

gtagSet

Wysyła polecenie zestawu tagów gtag do warstwy danych w celu przetworzenia, gdy tylko jest to możliwe po zakończeniu bieżącego zdarzenia i wszystkich wywołanych przez niego tagów (lub osiągnięciu limitu czasu przetwarzania tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce warstwy danych.

Jeśli np. tag został wywołany przy użyciu inicjowania zgody, aktualizacja zostanie zastosowana przed przetworzeniem zdarzenia inicjowania. Przykładem może być ustawienie wartości ads_data_redaction jako true, false lub url_passthrough wartości true lub false.

Przykłady:

const gtagSet = require('gtagSet');

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

Składnia

gtagSet(object)

Parametry

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

Powiązane uprawnienia

write_data_layer sprawdza uprawnienia do zapisu dla wszystkich określonych kluczy dataLayer. Jeśli dane wejściowe funkcji gtagSet są zwykłym obiektem, to interfejs API sprawdza uprawnienia do zapisu dla wszystkich spłaszczonych kluczy w tym obiekcie, np. dla gtagSet({foo: {bar: 'baz'}}), API sprawdza uprawnienia do zapisu dla foo.bar.

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

Pamiętaj, że jeśli cykl podlega obiektowi wejściowemu, sprawdzane będą tylko klucze przed dotarciem do tego samego obiektu.

injectHiddenIframe

Dodaje do strony niewidoczny element iframe.

Wywołania zwrotne są wywoływane jako instancje funkcji i opakowane przez funkcje JavaScript, które je wywołują.

Składnia

injectHiddenIframe(url, onSuccess)

Parametry

Parametr Typ Opis
url ciąg znaków Adres URL, który ma być używany jako wartość atrybutu src elementu iframe.
onSuccess funkcja Wywoływana, gdy ramka zostanie wczytana.

Powiązane uprawnienia

inject_hidden_iframe

injectScript

Dodaje do strony tag skryptu, który umożliwia asynchroniczne wczytywanie określonego adresu URL. Wywołania zwrotne są dostarczane jako instancje funkcji i są otoczone funkcjami JavaScript, które je wywołują.

Składnia

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

Parametry

Parametr Typ Opis
url ciąg znaków Adres skryptu, który ma zostać wstrzyknięty.
onSuccess funkcja Wywoływana po załadowaniu skryptu.
onFailure funkcja Wywoływana, gdy nie można wczytać skryptu.
cacheToken ciąg znaków Opcjonalny ciąg znaków używany do wskazania adresu URL w pamięci podręcznej. Jeśli ta wartość jest określona, do utworzenia kodu JavaScript zostanie utworzony tylko jeden element skryptu. Przy kolejnych próbach wczytania określone metody onSuccess i onFailure zostaną dodane do kolejki do momentu załadowania skryptu.

Powiązane uprawnienia

inject_script

isConsentGranted

Zwraca wartość „prawda”, jeśli typ zgody jest określony.

Zgoda w przypadku określonego typu zgody jest uznawana za udzieloną, jeśli typ zgody to „Przyznano” lub w ogóle nie został ustawiony. Jeśli jako rodzaj zgody wybierzesz inną wartość, zostanie ona uznana za nieudzieloną.

Ustawienia Menedżera tagów w interfejsie Menedżera tagów będą zawsze umożliwiały uruchomienie tagu. Jeśli tag z włączonym automatycznym uruchamianiem używa tego interfejsu API, zgoda jest uznawana za udzieloną, a zasada true zostanie zwrócona 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 dla typu zgody.

JSON

Zwraca obiekt z funkcjami JSON.

Funkcja parse() analizuje ciąg znaków JSON, aby utworzyć wartość lub obiekt opisany w tekście. Jeśli nie można przeanalizować wartości (np. uszkodzonych plików JSON), funkcja zwróci undefined. Jeśli dane wejściowe nie są ciągiem, zostaną one przekształcone w ciąg.

Funkcja stringify() konwertuje dane wejściowe na ciąg znaków w formacie 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 ciągu dowolny Wartość do konwersji. Jeśli wartość nie jest ciągiem, wartość wejściowa zostanie zastąpiona ciągiem znaków.

JSON.stringify;

Parametr Typ Opis
wartość 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 uzyskiwania 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ę (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 Map. Służy do zmiany pola szablonu SIMPLE_TABLE z 2 kolumnami na format, którym można łatwiej zarządzać.

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 obiekt: przekonwertowany Map, jeśli został do niego dodany 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, gdzie 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 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 przekonwertowanej komórce Map.

Powiązane uprawnienia

Brak.

Math

Obiekt z funkcjami 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 standardową bibliotekę Object.keys() Biblioteki standardowej. Zwraca tablicę własnych nazw właściwości należących do danego obiektu w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda values() zapewnia zachowanie klasy Object.values() w Bibliotece standardowej. Zwraca tablicę własnych wartości właściwości liczbowych właściwości w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda entries() udostępnia standardową bibliotekę Object.entries() Biblioteki standardowej. Zwraca tablicę we własnej właściwości, którą jest wymienną [key, value] obiektu w tej samej kolejności co pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda freeze() zapewnia zachowanie biblioteki Object.rost() w Bibliotece standardowej. Zablokowanego obiektu nie można już zmienić. Zablokowanie obiektu uniemożliwia dodawanie do niego nowych usług, usuwanie istniejących właściwości i wartości istniejących. freeze() zwraca ten sam obiekt, który został przekazany. Argument podstawowy lub pusty jest traktowany tak, jakby był zamrożonym obiektem i zostanie zwrócony.

Metoda delete() zapewnia operator Biblioteki standardowej usuwania. Usuwa ten 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 jest zablokowany, nawet jeśli druga wartość wejściowa (keyToDelete) określa klucz, który nie istnieje. Zwraca wartość false we wszystkich pozostałych przypadkach. Różni się on jednak od operatora usuwania standardowej biblioteki w następujący sposób:

  • keyToDelete nie może być ciągiem rozdzielanym kropkami wskazującym zagnieżdżony klucz.
  • Funkcji delete() nie można używać do usuwania elementów z tablicy.
  • Nie można użyć właściwości delete() do usunięcia ż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
Obiekt_wejściowy dowolny Obiekt, którego klucze mają być wyliczane. Jeśli dane wejściowe nie są obiektami, zostaną przeniesione do obiektu.

Object.values

Parametr Typ Opis
Obiekt_wejściowy dowolny Obiekt, którego wartości mają być wyliczane. Jeśli dane wejściowe nie są obiektami, zostaną przeniesione do obiektu.

Object.entries

Parametr Typ Opis
Obiekt_wejściowy dowolny Obiekt, którego pary klucz/wartość do wyliczenia. Jeśli dane wejściowe nie są obiektami, zostaną przeniesione do obiektu.

Obiekt.zamrożenie

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

Obiekt.delete

Parametr Typ Opis
Obiekt_wejściowy dowolny Obiekt, którego klucz do usunięcia.
keyToDelete, ciąg znaków Klucz najwyższego poziomu do usunięcia.

Przykład

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

parseUrl

Zwraca obiekt, który zawiera wszystkie części składowe danego adresu URL, podobnie jak obiekt URL.

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

Zwracany obiekt będzie zawierał te pola:

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

Przykład

const parseUrl = require('parseUrl');

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

Składnia

parseUrl(url);

Parametry

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

Powiązane uprawnienia

Brak.

queryPermission

Wysyłanie uprawnień (zawężonych) do uprawnień. Zwraca wartość logiczną: true, jeśli przyznano uprawnienia. W przeciwnym razie 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 poszukiwanego uprawnienia. Zobacz argumenty funkcji poniżej.

Argumenty funkcji

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

writeGlobals, readGlobals: drugi parametr powinien być wartością zapisywaną lub odczytywaną.

readUrl: do określenia, czy można odczytać cały adres URL, nie są potrzebne żadne dodatkowe argumenty. Aby przesłać zapytanie o możliwość odczytania danego komponentu, prześlij jego nazwę jako drugi argument:

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

Aby sprawdzić, czy określony klucz zapytania jest czytelny, przekaż go 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ść nieokreśloną, 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

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ływane po załadowaniu piksela. Uwaga: nawet jeśli żądanie zostanie wysłane, przeglądarki mogą wymagać prawidłowej odpowiedzi z obrazem.
onFailure funkcja Wywoływane, gdy piksel się nie wczytuje. Uwaga: nawet jeśli żądanie zostanie wysłane, żądanie OnFailure może zostać uruchomione, jeśli serwer nie zwróci prawidłowej odpowiedzi graficznej.

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 object Określa atrybuty Domena, Ścieżka, Wygasa, Maks. wiek, Bezpieczne i SameSite. (zobacz poniżej Opcje).
encode wartość logiczna Określa, czy wartość pliku cookie ma być kodowana za pomocą kodu encodeURIComponent() JavaScriptu. Domyślna wartość to true.

Opcje

  • Domena: ustawiona przez właściwość options['domain'] (jeśli istnieje). Ustaw tę wartość na 'auto', by zapisać plik cookie w najszerszej możliwej domenie na podstawie lokalizacji dokumentu. Jeśli to się nie uda, spróbuje kolejno kolejne subdomeny. Jeśli nie uda się zalogować, spróbuje zapisać plik cookie bez domeny. Jeśli nie ustawisz żadnej wartości, spróbujemy zapisać plik cookie bez podawania domeny. Uwaga: gdy plik cookie bez określonej domeny jest zapisany w pliku document.cookie, klient użytkownika domyślnie ustawia domenę tego pliku jako host bieżącej lokalizacji dokumentu.
  • Ścieżka: ustawiona przez options['path'], jeśli występuje. W przypadku zapisania w pliku cookie pliku cookie bez określonej ścieżki document.cookie klient użytkownika ustawi domyślną ścieżkę pliku cookie do 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 jest obecny, musi być to ciąg znaków w formacie UTC. Date.toUTCString() może być używany do formatowania Date dla tego parametru.
  • Bezpieczna: ustawiona przez options['secure'], jeśli występuje.
  • SameSite: wskazuje options['samesite'], jeśli występuje.

Powiązane uprawnienia

set_cookies

setDefaultConsentState

Wysyła domyślną aktualizację zgody na warstwę danych do przetwarzania natychmiast po przetworzeniu bieżącego zdarzenia i wywołanych przez nie tagów (lub osiągnięciu limitu czasu przetwarzania tagu). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed elementami w kolejce w warstwie danych. Więcej informacji o zgodzie

Przykład:

const setDefaultConsentState = require('setDefaultConsentState');

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

Składnia

setDefaultConsentState(consentSettings)

Parametry

Parametr Typ Opis
consentSettings object Obiekt, który określa stan domyślny dla określonych typów zgody

Obiekt consentSettings jest przyporządkowany do dowolnych ciągów typu zgody na wartość 'granted' lub 'denied'. Obsługiwane są te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków Wartością każdego typu zgody może być „Przyznano” lub „Odrzucono”. Wartości inne niż „Przyznano” będą traktowane jako „Nieodebrane”. Ustawienie wartości „nie określono” nie będzie miało wpływu na poprzednią wartość.
region Tablica Opcjonalny tablica kodów regionów określających region, do którego mają zastosowanie ustawienia zgody użytkownika. Kody regionów są wyrażone za pomocą krajów lub podgrup w formacie ISO 3166-2.
wait_for_update liczba Określa milisekundę, aby kontrolować 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 dla wszystkich typów zgody w obiekcie consentSettings.

setInWindow

Ustawia daną wartość w funkcji window w danym kluczu. Domyślnie ta metoda nie ustawia wartości w polu window, jeśli wartość jest już określona. Ustaw overrideExisting jako 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 (w przeciwnym razie).

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Parametr Typ Opis
key ciąg znaków Klucz w window, aby umieścić wartość.
value * Wartość do ustawienia w polu window.
overrideExisting wartość logiczna Flaga wskazująca, że ta wartość powinna być ustawiona w window, niezależnie od tego, czy ma wartość.

Powiązane uprawnienia

access_globals

sha256

Oblicza skrót SHA-256 danych wejściowych i wywołuje wywołanie zwrotne z skrótem 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ływane w wyniku uzyskanego skrótu zakodowane w base64, chyba że obiekt options określa inne kodowanie danych wyjściowych.
onFailure funkcja Wywoływana, gdy 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 object Opcjonalne, aby określić kodowanie danych wyjściowych. Jeśli jest określony, obiekt powinien zawierać klucz outputEncoding o wartości jednej z tych wartości: base64 lub hex.

Powiązane uprawnienia

Brak.

templateStorage

Zwraca obiekt z metodami uzyskiwania dostępu do pamięci szablonu. Przechowywanie szablonów umożliwia udostępnianie danych między wykonaniami 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 do kodowania.

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Powiązane uprawnienia

Brak

updateConsentState

Wysyła aktualizację zgody do warstwy danych w celu przetworzenia jak najszybciej po zakończeniu bieżącego zdarzenia i wywołanych przez niego tagów (lub osiągnięciu limitu czasu przetwarzania tagów). Gwarantujemy, że aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami umieszczonymi w kolejce w warstwie danych. Więcej informacji o zgodzie

Przykład:

const updateConsentState = require('updateConsentState');

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

Składnia

updateConsentState(consentSettings)

Parametry

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

Obiekt consentSettings jest przyporządkowany do dowolnych ciągów typu zgody na wartość 'granted' lub 'denied'. Obsługiwane są te wartości:

Nazwa klucza Typ Opis
consentType ciąg znaków W przypadku każdego typu zgody można ustawić wartość „Przyznano” lub „Odrzucono”. Wartości inne niż „przyznano” będą traktowane jako „odrzucone”. Ustawienie wartości „undefine” nie ma wpływu na poprzednią wartość.

Powiązane uprawnienia

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

Interfejsy API testowania

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órego można używać do płynnego podawania danych 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 przekazany do require().

Pasujące 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 wzorowany na bibliotece [Truth] Google. Zwraca obiekt, który może zostać płynnie udowodniony jako wartość podmiotu. Błąd potwierdzenia spowoduje natychmiastowe zatrzymanie testu i oznaczenie go jako nieudanego. 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ść do sprawdzenia biegłości.
opt_message ciąg znaków Opcjonalna wiadomość do wydrukowania w przypadku niepowodzenia potwierdzenia.

Pasujące dopasowania

Dopasowanie Opis
isUndefined() Stwierdza, że temat to undefined.
isDefined() Stwierdza, że temat nie jest undefined.
isNull() Stwierdza, że temat to null.
isNotNull() Stwierdza, że temat nie jest null.
isFalse() Stwierdza, że temat to false.
isTrue() Stwierdza, że temat to true.
isFalsy() Twierdzi, że temat jest bezsensowny. Wartości faliste to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isTruthy() Stwierdza, że podmiot jest prawdziwy. Wartości faliste to undefined, null, false, NaN, 0 i '' (pusty ciąg znaków).
isNaN() Stwierdza, że obiekt to wartość NaN.
isNotNaN() Stwierdza, że obiekt ma dowolną wartość inną niż NaN.
isInfinity() Stwierdza, że temat jest dodatni lub negatywny.
isNotInfinity() Stwierdza, że temat jest dowolną wartością inną niż dodatnia lub ujemna.
isEqualTo(expected) Stwierdza, że obiekt jest równy danej wartości. To porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isNotEqualTo(expected) Stwierdza, że obiekt nie jest równy danej wartości. To 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 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ówny żadnej z podanych wartości. Jest to porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
isStrictlyEqualTo(expected) Stwierdza, że obiekt (===) jest identyczny z podaną wartością.
isNotStrictlyEqualTo(expected) Stwierdza, że obiekt nie jest ściśle równy !== (wartości).
isGreaterThan(expected) Stwierdza, że temat jest większy niż (>) określona wartość w porównywanym porównaniu.
isGreaterThanOrEqualTo(expected) Stwierdza, że temat jest większy niż lub równy (>=) danej wartości w porównywanym porównaniu.
isLessThan(expected) Stwierdza, że temat jest niższy od (<) podanej wartości w porównywanym porównaniu.
isLessThanOrEqualTo(expected) W porównaniu uporządkowanych danych stwierdza, że obiekt jest mniejszy lub równy (<=).
contains(...expected) Stwierdza, że temat jest tablicą lub ciągiem znaków zawierającym wszystkie wartości w dowolnej kolejności. To porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContain(...expected) Stwierdza, że temat jest tablicą lub ciągiem znaków, który nie zawiera żadnej z podanych wartości. To porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
containsExactly(...expected) Stwierdza, że temat jest tablicą zawierającą wszystkie podane wartości w dowolnej kolejności, bez żadnych innych wartości. To porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
doesNotContainExactly(...expected) Stwierdza, że temat jest tablicą zawierającą inny zestaw wartości od podanych w dowolnej kolejności. To porównanie wartości, a nie porównanie. Zawartość obiektów i tablic jest porównywana rekurencyjnie.
hasLength(expected) Stwierdza, że temat jest tablicą lub ciągiem znaków o określonej długości. Asercja zawsze kończy się niepowodzeniem, jeśli wartość nie jest tablicą ani ciągiem znaków.
isEmpty() Stwierdza, ż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() Stwierdza, że temat jest tablicą lub ciągiem, 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 rodzaj tematu to liczba.
isObject() stwierdza, że typ podmiotu to obiekt.
isString() Twierdzi, że typ podmiotu jest ciągiem.

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

Natychmiastowo kończy się bieżący test i drukuje określoną wiadomość (jeśli została podana).

Składnia

fail(opt_message);

Parametry

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

Przykład

fail('This test has failed.');

mock

Interfejs mock API pozwala zastąpić działanie interfejsów API piaskownicy. Pozorowanie interfejsu API jest bezpieczne w kodzie szablonu, ale nie działa w trybie testowym. Pozorowane testy są resetowane przed uruchomieniem każdego testu.

Składnia

mock(apiName, returnValue);

Parametry

Parametr Typ Opis
apiName ciąg znaków Nazwa interfejsu API do pozorowania; ten sam ciąg znaków, który jest przekazywany do require()
returnValue dowolny Wartość, która ma zostać zwrócona dla interfejsu API lub funkcja wywoływana zamiast interfejsu API. Jeśli returnValue to funkcja, która jest wywoływana zamiast interfejsu Sandbox API. Jeśli returnValue stanowi coś innego niż funkcja, ta wartość jest zwracana 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, czyli zawartość karty Code, w bieżącym środowisku testowym z danym obiektem danych wejściowych.

Składnia

runCode(data)

Parametry

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

Zwrócona wartość

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

Przykład

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