Interfejsy API szablonów niestandardowych

Podstawowe interfejsy API

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

const myAPI = require('myAPI');

addConsentListener

Rejestruje funkcję detektora, która ma być wykonywana, gdy zmieni się stan określonego typu zgody.

Podany odbiorca będzie wywoływany za każdym razem, gdy stan określonego typu zgody zmieni się z odmowy na zgodę lub ze zgody na odmowę. Rodzaj zgody bez stanu jest uznawany za przyznany, więc jeśli rodzaj zgody o stanie „nieustawiony” zostanie zaktualizowany do stanu „przyznany”, funkcja nasłuchująca nie zostanie wywołana. Funkcje odbiornika będą odpowiedzialne za zapewnienie, że ich kod zostanie uruchomiony odpowiednią liczbę razy.

Przykład:

const isConsentGranted = require('isConsentGranted');
const addConsentListener = require('addConsentListener');

if (!isConsentGranted('ad_storage')) {
  let wasCalled = false;
  addConsentListener('ad_storage', (consentType, granted) => {
    if (wasCalled) return;
    wasCalled = true;

    const cookies = getMyCookies();
    sendFullPixel(cookies);
  });
}

Składnia

addConsentListener(consentType, listener)

Parametry

Gdy wywoływany jest odbiornik, przekazywany jest do niego typ zgody, który ulega zmianie, oraz nowa wartość tego typu zgody:

Powiązane uprawnienia

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

addEventCallback

Interfejs addEventCallback API umożliwia zarejestrowanie funkcji wywołania zwrotnego, która zostanie wywołana na końcu zdarzenia. Wywołanie zwrotne zostanie wywołane, gdy wszystkie tagi zdarzenia zostaną wykonane lub gdy zostanie osiągnięty limit czasu zdarzenia na stronie. Funkcja zwrotna otrzymuje 2 wartości: identyfikator kontenera, który wywołuje funkcję, oraz obiekt zawierający informacje o zdarzeniu.

Składnia

addEventCallback(callback)

Parametry

Obiekt eventData zawiera te dane:

Przykład

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

Powiązane uprawnienia

read_event_metadata

aliasInWindow

Interfejs aliasInWindow API umożliwia tworzenie aliasów (np. window.foo = window.bar), które pomagają obsługiwać niektóre tagi wymagające aliasowania. Przypisuje wartość w obiekcie window znalezionym w fromPath do klucza w obiekcie window w toPath. Zwraca true, jeśli operacja się uda, a w przeciwnym razie false.

Składnia

aliasInWindow(toPath, fromPath)

Parametry

Przykład

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

Powiązane uprawnienia

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

callInWindow

Umożliwia wywoływanie funkcji ze ścieżki poza obiektem window w sposób kontrolowany przez zasady. Wywołuje funkcję w podanej ścieżce w window z podanymi argumentami i zwraca wartość. Jeśli zwracany typ nie może być bezpośrednio mapowany na typ obsługiwany w piaskownicy JavaScript, zwracana jest wartość undefined. W JavaScript w piaskownicy obsługiwanych jest 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, zwracana jest wartość undefined.

Składnia

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

Parametry

Powiązane uprawnienia

access_globals z włączonym uprawnieniem execute.

callLater

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

Składnia

callLater(function)

Parametry

copyFromDataLayer

Zwraca wartość przypisaną obecnie do danego klucza w warstwie danych: wartość znalezioną przy danym kluczu, jeśli jest to typ prosty, funkcja lub literał obiektu, lub undefined w przeciwnym razie.

Składnia

copyFromDataLayer(key[, dataLayerVersion])

Parametry

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 piaskownicy, zwracana jest wartość undefined. 8 typów obsługiwanych w JavaScript w piaskownicy to null, undefined, boolean, number, string, Array, Object i function. Zwraca pobraną (i przekształconą) wartość.

Składnia

copyFromWindow(key)

Parametry

Powiązane uprawnienia

access_globals

createArgumentsQueue

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

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

Gdy wywoływana jest funkcja utworzona w obszarze fnKey, umieszcza ona obiekt argumentów w tablicy utworzonej w obszarze arrayKey. Wartością zwracaną przez interfejs API jest funkcja utworzona w sekcji fnKey.

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

Przykład:

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

Składnia

createArgumentsQueue(fnKey, arrayKey)

Parametry

Powiązane uprawnienia

access_globals

createQueue

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

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

Przykład:

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

Składnia

createQueue(arrayKey)

Parametry

Powiązane uprawnienia

access_globals

decodeUri

Dekoduje wszystkie zakodowane znaki w podanym identyfikatorze URI. Zwraca ciąg tekstowy reprezentujący zdekodowany identyfikator URI. Zwraca undefined, gdy otrzyma nieprawidłowe dane wejściowe.

Przykład:

const decode = require('decodeUri');

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

Składnia

decodeUri(encoded_uri)

Parametry

Powiązane uprawnienia

Brak.

decodeUriComponent

Dekoduje wszystkie zakodowane znaki w podanym komponencie URI. Zwraca ciąg tekstowy reprezentujący zdekodowany komponent URI. Zwraca undefined, gdy podane dane wejściowe są nieprawidłowe.

Przykład:

const decode = require('decodeUriComponent');

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

Składnia

decodeUriComponent(encoded_uri_component)

Parametry

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI, w którym znaki specjalne są poprzedzone znakiem ucieczki. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca undefined, gdy otrzyma nieprawidłowe dane wejściowe (samodzielny znak zastępczy).

Przykład:

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

Składnia

encodeUri(uri)

Parametry

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI, w którym znaki specjalne są poprzedzone znakiem ucieczki. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI. Zwraca undefined, gdy otrzyma nieprawidłowe dane wejściowe (samodzielny znak zastępczy).

Przykład:

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

Składnia

encodeUriComponent(str)

Parametry

Powiązane uprawnienia

Brak.

fromBase64

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

Składnia

fromBase64(base64EncodedString)

Parametry

Przykład

const fromBase64 = require('fromBase64');

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

Powiązane uprawnienia

Brak

generateRandom

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

Składnia

generateRandom(min, max)

Parametry

Powiązane uprawnienia

Brak.

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwrócony obiekt zawiera te pola:

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

Przykład

const getContainerVersion = require('getContainerVersion');
const sendPixel = require('sendPixel');

if (query('read_container_data')) {
  const cv = getContainerVersion();

  const pixelUrl = 'https://pixel.com/' +
    '?version=' + cv.version +
    '&envName=' + cv.environmentName +
    '&ctid=' + cv.containerId +
    '&debugMode=' + cv.debugMode +
    '&previewMode=' + cv.previewMode;
  if (query('send_pixel', pixelUrl)) {
    sendPixel(pixelUrl);
  }
}

Składnia

getContainerVersion();

Powiązane uprawnienia

read_container_data

getCookieValues

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

Składnia

getCookieValues(name[, decode])

Parametry

Powiązane uprawnienia

get_cookies

getQueryParameters

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

Składnia

getQueryParameters(queryKey[, retrieveAll])

Parametry

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

getReferrerQueryParameters

Interfejs getReferrerQueryParameters działa tak samo jak getQueryParameters, z tą różnicą, że dotyczy strony odsyłającej, a nie bieżącego adresu URL. Zwraca pierwszy lub wszystkie parametry dla danego odsyłającego queryKey. Zwraca pierwszą wartość z queryKey lub tablicę wartości z queryKey.

Składnia

getReferrerQueryParameters(queryKey[, retrieveAll])

Parametry

Jeśli na przykład adres URL odsyłający 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 określać queryKey w dozwolonych kluczach zapytania (lub zezwalać na dowolny klucz zapytania).

getReferrerUrl

Na podstawie typu komponentu interfejs API odczytuje obiekt dokumentu w celu uzyskania informacji o odsyłającym i zwraca ciąg znaków reprezentujący część odsyłającego. Jeśli nie podano żadnego komponentu, zwracany jest pełny adres URL strony odsyłającej.

Składnia

getReferrerUrl([component])

Parametry

Powiązane uprawnienia

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

getTimestamp

Wycofano. Zalecamy używanie funkcji getTimestampMillis.

Zwraca liczbę reprezentującą bieżący czas w milisekundach od początku epoki systemu Unix, zgodnie z wartością zwracaną przez Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę reprezentującą bieżący czas w milisekundach od początku epoki systemu Unix, zgodnie z wartością zwracaną przez Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

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

Składnia

getType(data.someField)

Uwagi

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

Powiązane uprawnienia

Brak.

getUrl

Zwraca ciąg, który reprezentuje cały bieżący adres URL lub jego część, na podstawie typu komponentu i niektórych parametrów konfiguracji.

Składnia

getUrl(component)

Parametry

Powiązane uprawnienia

get_url

gtagSet

Wysyła do warstwy danych polecenie gtag set, które ma zostać przetworzone jak najszybciej po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich wywołanych przez nie tagów (lub po osiągnięciu limitu czasu przetwarzania tagów). Aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce warstwy danych.

Jeśli np. wywoła go tag uruchomiony w ramach inicjacji zgody, aktualizacja zostanie zastosowana przed przetworzeniem zdarzenia inicjowania. Przykłady: ads_data_redaction ustawione na true lub false, albo url_passthrough ustawione na true lub false.

Przykłady:

const gtagSet = require('gtagSet');

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

Składnia

gtagSet(object)

Parametry

Powiązane uprawnienia

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

Jeśli danymi wejściowymi dla gtagSet jest klucz i pewna wartość, która nie jest zwykłym obiektem, interfejs API sprawdzi uprawnienia do zapisu tego klucza, np. w przypadku gtagSet('abc', true) interfejs API sprawdzi uprawnienia do zapisu 'abc'.

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

injectHiddenIframe

Dodaje do strony niewidoczny element iframe.

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

Składnia

injectHiddenIframe(url, onSuccess)

Parametry

Powiązane uprawnienia

inject_hidden_iframe

injectScript

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

Składnia

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

Parametry

Powiązane uprawnienia

inject_script

isConsentGranted

Zwraca wartość „true”, jeśli przyznano określony rodzaj zgody.

Zgoda na określony rodzaj zgody jest uznawana za udzieloną, jeśli rodzaj zgody ma wartość „Przyznano” lub nie jest w ogóle ustawiony. Jeśli typ zgody ma inną wartość, uznajemy, że zgoda nie została udzielona.

W interfejsie Menedżera tagów w ustawieniach tagu będzie dostępna opcja zawsze uruchamiaj. Jeśli tag z włączoną opcją „Zawsze uruchamiaj” korzysta z tego interfejsu API, zgoda jest uznawana za udzieloną i zwracana jest wartość true, niezależnie od rzeczywistego stanu zgody.

Przykład:

const isConsentGranted = require('isConsentGranted');

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

Składnia

isConsentGranted(consentType)

Parametry

Powiązane uprawnienia

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

JSON

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

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

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

Składnia

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

Parametry

JSON.parse

JSON.stringify

Przykład

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

localStorage

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

Składnia

const localStorage = require('localStorage');

// Requires read access for the key. Returns null if the key does not exist.
localStorage.getItem(key);

// Requires write access for the key. Returns true if successful.
localStorage.setItem(key, value);

// Requires write access for the key.
localStorage.removeItem(key);

Powiązane uprawnienia

access_local_storage

Przykład

const localStorage = require('localStorage');
if (localStorage) {
  const value = localStorage.getItem('my_key');
  if (value) {
    const success = localStorage.setItem('my_key', 'new_value');
    if (success) {
      localStorage.removeItem('my_key');
    }
  }
}

logToConsole

Zapisuje argumenty w konsoli przeglądarki.

Składnia

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

Parametry

Powiązane uprawnienia

logging

makeInteger

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

Składnia

makeInteger(value)

Parametry

Powiązane uprawnienia

Brak.

makeNumber

Konwertuje podaną wartość na liczbę.

Składnia

makeNumber(value)

Parametry

Powiązane uprawnienia

Brak.

makeString

Zwraca podaną wartość jako ciąg tekstowy.

Składnia

makeString(value)

Parametry

Powiązane uprawnienia

Brak.

makeTableMap

Przekształca prosty obiekt tabeli z 2 kolumnami w Map. Służy do przekształcania pola szablonu SIMPLE_TABLE z 2 kolumnami w łatwiejszy w obsłudze format.

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

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

na mapę:

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

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

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parametry

Powiązane uprawnienia

Brak.

Math

Obiekt udostępniający funkcje Math.

Składnia

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

Parametry

Parametry funkcji matematycznych są przekształcane w liczby.

Powiązane uprawnienia

Brak.

Object

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

Metoda keys() zapewnia działanie Object.keys() biblioteki standardowej. Zwraca tablicę nazw własnych właściwości obiektu, które można wyliczyć, w tej samej kolejności, w jakiej zwróciłaby je pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

Metoda values() zapewnia działanie Object.values() z biblioteki standardowej. Zwraca tablicę wartości własnych właściwości obiektu, które można wyliczyć, w tej samej kolejności, w jakiej zwróciłaby je pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

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

Metoda freeze() zapewnia działanie Object.freeze() z biblioteki standardowej. Zamrożonego obiektu nie można już zmieniać. Zamrożenie obiektu uniemożliwia dodawanie do niego nowych właściwości, usuwanie istniejących właściwości i zmianę wartości istniejących właściwości. freeze() zwraca ten sam obiekt, który został przekazany. Argument typu prostego lub argument o wartości null będzie traktowany tak, jakby był zamrożonym obiektem, i zostanie zwrócony.

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

• keyToDelete nie może być ciągiem znaków rozdzielonym kropkami, który określa klucz zagnieżdżony.
• Nie można użyć delete() do usunięcia elementów z tablicy.
• Za pomocą parametru delete() nie można usuwać żadnych usług z zakresu globalnego.

Składnia

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

Parametry

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Przykład

const Object = require('Object');

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

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

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

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

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

parseUrl

Zwraca obiekt zawierający wszystkie części składowe danego adresu URL, podobnie jak obiekt URL.

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

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

Powiązane uprawnienia

Brak.

queryPermission

Wysyłanie zapytań o dozwolone i ograniczone uprawnienia. Zwraca wartość logiczną: true, jeśli uprawnienie zostało przyznane, false w przeciwnym razie.

Składnia

queryPermission(permission, functionArgs*)

Parametry

Argumenty funkcji

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

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

readUrl: aby sprawdzić, czy można odczytać cały adres URL, nie są potrzebne żadne dodatkowe argumenty. Aby sprawdzić, czy dany 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ż go jako trzeci parametr:

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

Powiązane uprawnienia

Brak.

readAnalyticsStorage

Pobiera dane przechowywane na potrzeby analizy i zwraca obiekt z client_idi sessions.

• client_id: ciąg znaków reprezentujący identyfikator klienta używany na potrzeby analiz.
• sessions: tablica obiektów zawierających informacje o bieżących sesjach. Każdy obiekt zawiera:
  • measurement_id: ciąg znaków reprezentujący identyfikator pomiaru miejsca docelowego Analytics.
  • session_id: ciąg znaków reprezentujący sygnaturę czasową, która identyfikuje bieżącą sesję.
  • session_number: liczba sesji zainicjowanych przez użytkownika do chwili rozpoczęcia bieżącej sesji.

Składnia

const readAnalyticsStorage = require('readAnalyticsStorage');

const cookieOptions = {
  cookie_prefix: "xyz",
  cookie_domain: "google.com",
  cookie_path: "/",
};

readAnalyticsStorage(cookieOptions);

Parametry

Powiązane uprawnienia

read_analytics_storage

Przykład

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

readCharacterSet

Zwraca wartość document.characterSet.

Składnia

readCharacterSet()

Parametry

Brak.

Powiązane uprawnienia

read_character_set

readTitle

Zwraca wartość document.title.

Składnia

readTitle()

Parametry

Brak.

Powiązane uprawnienia

read_title

require

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

Składnia

require(name)

Parametry

Przykład

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

Powiązane uprawnienia

Brak.

sendPixel

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

Składnia

sendPixel(url, onSuccess, onFailure)

Parametry

Powiązane uprawnienia

send_pixel

setCookie

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

Składnia

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

Parametry

Opcje

• Domena: ustawiana przez właściwość options['domain'], jeśli jest obecna. Ustaw tę wartość na 'auto', aby spróbować zapisać plik cookie w najszerszej możliwej domenie na podstawie lokalizacji dokumentu. Jeśli to się nie uda, będzie próbować kolejno węższych subdomen. Jeśli wszystkie te próby się nie powiodą, spróbuje zapisać plik cookie bez domeny. Jeśli nie ustawisz żadnej wartości, plik cookie zostanie zapisany bez określania domeny. Uwaga: gdy plik cookie bez określonej domeny jest zapisywany w document.cookie, domyślną domeną pliku cookie jest host bieżącej lokalizacji dokumentu.
• Ścieżka: ustawiona przez options['path'], jeśli jest dostępna. Gdy plik cookie bez określonej ścieżki zostanie zapisany w document.cookie, klient użytkownika domyślnie ustawi ścieżkę pliku cookie na ścieżkę bieżącej lokalizacji dokumentu.
• Max-Age: ustawiony przez options['max-age'], jeśli jest obecny.
• Wygasa: ustawione przez options['expires'], jeśli jest dostępne. Jeśli ten atrybut jest obecny, musi zawierać ciąg daty w formacie UTC. Date.toUTCString() można użyć do sformatowania parametru Date.
• Bezpieczne: ustawione przez options['secure'], jeśli jest obecny.
• SameSite: ustawiony przez options['samesite'], jeśli jest obecny.

Powiązane uprawnienia

set_cookies

setDefaultConsentState

Przesyła do warstwy danych domyślną aktualizację zgody użytkownika, która zostanie przetworzona jak najszybciej po zakończeniu bieżącego zdarzenia i wszystkich tagów, które ono wywołało (lub po osiągnięciu limitu czasu przetwarzania tagu). Aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce w warstwie danych. Więcej informacji o uzyskiwaniu zgody

Przykład:

const setDefaultConsentState = require('setDefaultConsentState');

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

Składnia

setDefaultConsentState(consentSettings)

Parametry

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

Powiązane uprawnienia

Uprawnienie access_consent z dostępem do zapisu dla wszystkich typów zgody w obiekcie consentSettings.

setInWindow

Ustawia podaną wartość w window pod podanym kluczem. Domyślnie ta metoda nie ustawia wartości w window, jeśli jest już tam jakaś wartość. Ustaw wartość overrideExisting na true, aby ustawić wartość w polu window niezależnie od tego, czy istnieje już wartość. Zwraca wartość logiczną: true, jeśli wartość została ustawiona prawidłowo, a w przeciwnym razie false.

Składnia

setInWindow(key, value, overrideExisting)

Parametry

Powiązane uprawnienia

access_globals

sha256

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

Przykład:

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure);

sha256('inputString', (digest) => {
  sendPixel('https://example.com/collect?id=' + digest);
  data.gtmOnSuccess();
}, data.gtmOnFailure, {outputEncoding: 'hex'});

Składnia

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

Parametry

Powiązane uprawnienia

Brak.

templateStorage

Zwraca obiekt z metodami dostępu do pamięci szablonu. Pamięć szablonu umożliwia udostępnianie danych w ramach różnych wykonań jednego szablonu. Dane przechowywane w pamięci szablonu są dostępne przez cały okres istnienia strony.

Składnia

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Powiązane uprawnienia

access_template_storage

Przykład

const templateStorage = require('templateStorage');
const sendPixel = require('sendPixel');

// Ensure sendPixel is called only once per page.
if (templateStorage.getItem('alreadyRan')) {
  data.gtmOnSuccess();
  return;
}

templateStorage.setItem('alreadyRan', true);

sendPixel(
  data.oncePerPagePixelUrl,
  data.gtmOnSuccess,
  () => {
    templateStorage.setItem('alreadyRan', false);
    data.gtmOnFailure();
  });

toBase64

Interfejs toBase64 API umożliwia zakodowanie ciągu znaków w formacie base64.

Składnia

toBase64(input)

Parametry

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Powiązane uprawnienia

Brak

updateConsentState

Wysyła do warstwy danych aktualizację stanu zgody użytkownika, która ma być przetworzona jak najszybciej po zakończeniu przetwarzania bieżącego zdarzenia i wszystkich wywołanych przez nie tagów (lub po osiągnięciu limitu czasu przetwarzania tagu). Aktualizacja zostanie przetworzona w tym kontenerze przed wszystkimi elementami w kolejce w warstwie danych. Więcej informacji o uzyskiwaniu zgody

Przykład:

const updateConsentState = require('updateConsentState');

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

Składnia

updateConsentState(consentSettings)

Parametry

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

Powiązane uprawnienia

Uprawnienie access_consent z dostępem do zapisu dla wszystkich typów zgody w obiekcie consentSettings.

Testowanie interfejsów API

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

assertApi

Zwraca obiekt dopasowania, którego można użyć do płynnego tworzenia asercji dotyczących danego interfejsu API.

Składnia

assertApi(apiName)

Parametry

Dopasowywanie

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

Przykłady

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

assertThat

Interfejs assertThat API jest wzorowany na bibliotece [Truth] Google. Zwraca obiekt, którego można użyć do płynnego tworzenia asercji dotyczących wartości obiektu. Błąd asercji natychmiast zatrzyma test i oznaczy go jako nieudany. Niepowodzenie w jednym teście nie wpłynie jednak na inne przypadki testowe.

Składnia

assertThat(actual, opt_message)

Parametry

Dopasowywanie

Przykłady

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

Natychmiast przerywa bieżący test i wyświetla podany komunikat (jeśli został podany).

Składnia

fail(opt_message);

Parametry

Przykład

fail('This test has failed.');

mock

Interfejs mock API umożliwia zastępowanie działania interfejsów API w piaskownicy. Interfejs Mock API można bezpiecznie stosować w kodzie szablonu, ale działa on tylko w trybie testowym. Makiety są resetowane przed uruchomieniem każdego testu.

Składnia

mock(apiName, returnValue);

Parametry

Przykłady

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

mockObject

Interfejs mockObject API umożliwia zastąpienie działania interfejsów Sandboxed API, które zwracają obiekt. Interfejs API można bezpiecznie stosować w kodzie szablonu, ale działa on tylko w trybie testowym. Makiety są resetowane przed uruchomieniem każdego testu.

Składnia

mockObject(apiName, objectMock);

Parametry

Przykłady

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

runCode

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

Składnia

runCode(data)

Parametry

Zwracana wartość

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

Przykład

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