Interfejsy API tagowania po stronie serwera

W tym dokumencie opisujemy interfejsy API do tagowania po stronie serwera.

addEventCallback

Rejestruje funkcję wywołania zwrotnego, która zostanie wywołana na końcu zdarzenia. Wywołanie zwrotne zostanie wywołane, gdy zostaną wykonane wszystkie tagi zdarzenia. Funkcja wywołania zwrotnego otrzymuje 2 wartości: identyfikator kontenera, który wywołuje funkcję, oraz obiekt zawierający informacje o zdarzeniu.

Gdy ten interfejs API jest używany w tagu, jest powiązany z bieżącym zdarzeniem. Gdy ten interfejs API jest używany w kliencie, musi być powiązany z konkretnym zdarzeniem za pomocą funkcji bindToEvent interfejsu API runContainer. Więcej informacji znajdziesz w przykładzie.

Składnia

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

Parametry

Obiekt eventData zawiera te dane:

Przykład

W przypadku klienta:

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

W tagu:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

Powiązane uprawnienia

read_event_metadata

callLater

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

Przykład

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

Składnia

callLater(function)

Parametry

Powiązane uprawnienia

Brak.

claimRequest

Użyj tego interfejsu API w kliencie, aby zgłosić żądanie. Gdy żądanie zostanie odebrane, kontener nie uruchamia dodatkowych klientów.

Ten interfejs API zgłasza wyjątek, jeśli zostanie wywołany w tagu lub zmiennej. Ten interfejs API zgłasza wyjątek, jeśli zostanie wywołany po zwróceniu klienta (np. jeśli zostanie wywołany w asynchronicznym wywołaniu zwrotnym, takim jak w funkcji callLater lub runContainer onComplete).

Przed wywołaniem interfejsu API runContainer klient powinien zgłosić żądanie za pomocą tego interfejsu API.

Przykład

const claimRequest = require('claimRequest');

claimRequest();

Składnia

claimRequest();

Powiązane uprawnienia

Brak.

computeEffectiveTldPlusOne

Zwraca skuteczną domenę najwyższego poziomu + 1 (eTLD+1) podanej domeny lub adresu URL. eTLD+1 jest obliczana przez ocenę domeny pod kątem reguł listy sufiksów publicznych. eTLD+1 to zwykle domena najwyższego poziomu, w której możesz ustawić plik cookie.

Jeśli argument ma wartość null lub undefined, zwracana jest jego wartość bez zmian. W przeciwnym razie argument jest przekształcany w ciąg znaków. Jeśli argument nie jest prawidłową domeną lub adresem URL, zwracany jest pusty ciąg znaków. Jeśli serwer nie może pobrać listy sufiksów publicznych, wartość argumentu jest zwracana bez zmian.

Przykład

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

Składnia

computeEffectiveTldPlusOne(domainOrUrl);

Parametry

Powiązane uprawnienia

Brak.

createRegex

Tworzy nową instancję wyrażenia regularnego i zwraca ją opakowaną w obiekt. Nie możesz bezpośrednio uzyskać dostępu do wyrażenia regularnego. Możesz go jednak przekazać do interfejsów API testRegex, String.replace(), String.match() i String.search().

Zwraca null, jeśli wyrażenie regularne jest nieprawidłowe lub Re2 jest niedostępne na serwerze.

Ten interfejs API korzysta z implementacji Re2. Obraz Dockera serwera musi być w 2.0.0 lub nowszej.

Przykład

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Składnia

createRegex(pattern, flags);

Parametry

Powiązane uprawnienia

Brak.

Minimalna wersja graficzna

2.0.0

decodeUri

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

Przykład

const decodeUri = require('decodeUri');

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

Składnia

decodeUri(encoded_uri);

Parametry

Powiązane uprawnienia

Brak.

decodeUriComponent

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

Przykład

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

Składnia

decodeUriComponent(encoded_uri_component);

Parametry

Powiązane uprawnienia

Brak.

encodeUri

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier) przez zastąpienie znaków specjalnych. Zwraca ciąg znaków reprezentujący podany ciąg znaków zakodowany jako identyfikator URI.

Przykład

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

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

Składnia

encodeUri(uri);

Parametry

Powiązane uprawnienia

Brak.

encodeUriComponent

Zwraca zakodowany identyfikator URI (Uniform Resource Identifier) przez pominięcie znaków specjalnych. Zwraca ciąg tekstowy reprezentujący podany ciąg tekstowy zakodowany jako identyfikator URI.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

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

Składnia

encodeUriComponent(str);

Parametry

Powiązane uprawnienia

Brak.

extractEventsFromMpv1

Tłumaczy przychodzące żądanie Measurement Protocol w wersji 1 na listę zdarzeń w formacie Unified Schema. Zwraca listę wyodrębnionych zdarzeń. Jeśli żądanie nie ma prawidłowego formatu, zgłasza błąd.

Przykład

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Składnia

extractEventsFromMpv1();

Powiązane uprawnienia

Wymaga uprawnienia read_request. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• body
• query parameters

extractEventsFromMpv2

Tłumaczy przychodzące żądanie Measurement Protocol V2 na listę zdarzeń w formacie ujednoliconego schematu. Zwraca listę wyodrębnionych zdarzeń. Jeśli żądanie nie ma prawidłowego formatu, zgłasza błąd.

Przykład

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

Składnia

extractEventsFromMpv2();

Powiązane uprawnienia

Wymaga uprawnienia read_request. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp co najmniej do:

• body
• query parameters

fromBase64

Dekoduje ciąg znaków zakodowany w formacie base64. Zwraca undefined, jeśli dane wejściowe są nieprawidłowe.

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.

Przykład

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Składnia

generateRandom(min, max);

Parametry

Powiązane uprawnienia

Brak.

getAllEventData

Zwraca kopię danych zdarzenia.

Składnia

getAllEventData();

Powiązane uprawnienia

read_event_data

getClientName

Zwraca ciąg tekstowy zawierający nazwę bieżącego klienta.

Składnia

getClientName();

Powiązane uprawnienia

read_container_data

getContainerVersion

Zwraca obiekt zawierający dane o bieżącym kontenerze. Zwrócony 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 containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Składnia

getContainerVersion();

Powiązane uprawnienia

read_container_data

getCookieValues

Zwraca tablicę zawierającą wartości wszystkich plików cookie o podanej nazwie.

Przykład

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

Składnia

getCookieValues(name[, noDecode]);

Parametry

Powiązane uprawnienia

get_cookies

getEventData

Zwraca kopię wartości w podanej ścieżce w danych zdarzenia. Zwraca undefined, jeśli nie ma danych zdarzenia lub jeśli w danej ścieżce nie ma wartości.

Przykład

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Parametry

Składnia

getEventData(keyPath);

Powiązane uprawnienia

read_event_data

getGoogleAuth

Zwraca obiekt autoryzacji, który po użyciu z funkcją sendHttpGet lub sendHttpRequest będzie zawierać nagłówek autoryzacji dla interfejsów Google Cloud API. Ten interfejs API używa domyślnego uwierzytelniania aplikacji do automatycznego znajdowania danych logowania w środowisku serwera.

Przykład

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

Składnia

getGoogleAuth(scopes);

Parametry

Powiązane uprawnienia

Wymaga uprawnienia use_google_credentials. Uprawnienie musi być skonfigurowane z co najmniej 1 dozwolonym zakresem.

getGoogleScript

Pobiera zasób z określonego zestawu skryptów Google i zwraca obietnicę ze skryptem i powiązanymi metadanymi buforowania.

Obiekt Promise zostanie rozwiązany do obiektu zawierającego 2 klucze: script i metadata. Jeśli żądanie się nie powiedzie, obietnica zostanie odrzucona z kluczem reason.

Obiekt metadata będzie zawierać te metadane buforowania na podstawie nagłówków odpowiedzi zasobu. Każde pole będzie obecne tylko wtedy, gdy odpowiedni nagłówek będzie obecny w odpowiedzi zasobu.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

Przykład

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

Składnia

getGoogleScript(script[, options]);

Parametry

Opcje

Nierozpoznane klucze opcji są ignorowane.

Powiązane uprawnienia

Wymaga uprawnienia send_http. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp co najmniej do:

• Zezwalanie na Google Domains

getRemoteAddress

Zwraca ciąg znaków reprezentujący adres IP, z którego pochodzi żądanie, np.12.345.67.890 w przypadku IPv4 lub 2001:0db8:85a3:0:0:8a2e:0370:7334 w przypadku IPv6. Odczytuje nagłówki żądań, takie jak Forwarded i X-Forwarded-For. Uwaga: ten interfejs API podejmuje próbę wykrycia pierwotnego adresu IP, ale nie może zagwarantować, że wynik będzie dokładny.

Składnia

getRemoteAddress();

Powiązane uprawnienia

Wymaga uprawnienia read_request. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• Nagłówki Forwarded i X-Forwarded-For
• Zdalny adres IP

getRequestBody

Zwraca treść żądania jako ciąg znaków, jeśli jest obecna, lub undefined w przeciwnym razie.

Składnia

getRequestBody();

Powiązane uprawnienia

read_request

getRequestHeader

Zwraca wartość nazwanego nagłówka żądania jako ciąg tekstowy, jeśli istnieje, lub undefined w przeciwnym razie. Jeśli nagłówek się powtarza, zwrócone wartości są łączone za pomocą znaku ', '.

Przykład

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Składnia

getRequestHeader(headerName);

Parametry

Powiązane uprawnienia

read_request

getRequestMethod

Zwraca metodę żądania, np. 'GET' lub 'POST', jako ciąg tekstowy.

Przykład

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

Składnia

getRequestMethod();

Powiązane uprawnienia

Brak.

getRequestPath

Zwraca ścieżkę żądania bez ciągu zapytania. Jeśli na przykład adres URL to '/foo?id=123', funkcja zwraca '/foo'. Automatycznie usuwa prefiks adresu URL kontenera serwera ze ścieżki. Jeśli np. adres URL kontenera serwera to https://example.com/analytics, a ścieżka żądania to '/analytics/foo', funkcja zwraca wartość '/foo'.

Przykład

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

Składnia

getRequestPath();

Powiązane uprawnienia

read_request

getRequestQueryParameter

Zwraca zdekodowaną wartość nazwanego parametru ciągu zapytania jako ciąg znaków lub undefined, jeśli parametr nie występuje. Jeśli parametr powtarza się w ciągu zapytania, zwracana jest pierwsza wartość, która pojawia się w ciągu zapytania.

Przykład

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

Składnia

getRequestQueryParameter(name);

Parametry

Powiązane uprawnienia

read_request

getRequestQueryParameters

Zwraca parametry zapytania przychodzącego żądania HTTP jako obiekt, który mapuje nazwy parametrów zapytania na odpowiednie wartości. Nazwy i wartości parametrów są dekodowane.

Przykład

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

Składnia

getRequestQueryParameters();

Powiązane uprawnienia

read_request

getRequestQueryString

Zwraca zapytanie żądania jako ciąg znaków bez początkowego znaku zapytania lub pusty ciąg znaków, jeśli adres URL żądania nie zawiera ciągu zapytania.

Przykład

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

Składnia

getRequestQueryString();

Powiązane uprawnienia

read_request

getTimestamp

Wycofano. Zalecamy używanie getTimestampMillis.

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od epoki uniksowej, zwracaną przez funkcję Date.now().

Składnia

getTimestamp();

Powiązane uprawnienia

Brak.

getTimestampMillis

Zwraca liczbę, która reprezentuje bieżący czas w milisekundach od epoki uniksowej, zwracaną przez Date.now().

Składnia

getTimestampMillis();

Powiązane uprawnienia

Brak.

getType

Zwraca ciąg tekstowy opisujący typ danej wartości.

Przykład

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

Składnia

getType(value);

Parametry

Powiązane uprawnienia

Brak.

hmacSha256

Oblicza zakodowany podpis przy użyciu kodu uwierzytelniania wiadomości (HMAC) z SHA-256. Domyślne kodowanie to base64url.

Aby używać tego interfejsu API, ustaw zmienną środowiskową SGTM_CREDENTIALS na serwerze na ścieżkę pliku klucza JSON zakodowanego w UTF-8 w tym formacie:

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

Wartości to klucze HMAC zakodowane w formacie base64. Tekst JSON nie może zaczynać się od znacznika kolejności bajtów.

Przykład

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

Składnia

hmacSha256(data, keyId, options)

Parametry

Opcje

Powiązane uprawnienia

use_custom_private_keys

Minimalna wersja graficzna

1.0.0

isRequestMpv1

Zwraca true, jeśli przychodzące żądanie jest żądaniem Measurement Protocol w wersji 1, lub false w innych przypadkach.

Przykład

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

Składnia

isRequestMpv1();

Powiązane uprawnienia

Brak.

isRequestMpv2

Zwraca true, jeśli przychodzące żądanie jest żądaniem Measurement Protocol w wersji 2, lub false w innych przypadkach.

Przykład

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

Składnia

isRequestMpv2();

Powiązane uprawnienia

Brak.

logToConsole

Zapisuje argumenty w konsoli.

Te logi są widoczne w Eksploratorze logów w konsoli Google Cloud. Uruchom zapytanie logName =~ "stdout" w Eksploratorze logów, aby wyświetlić wpisy logu utworzone przez ten interfejs API.

Przykład

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

Składnia

logToConsole(argument1[, argument2, ...]);

Parametry

Interfejs API przyjmuje co najmniej 1 argument, który w razie potrzeby jest konwertowany na ciąg tekstowy i rejestrowany w konsoli.

Powiązane uprawnienia

logging

makeInteger

Przekształca podaną wartość w liczbę (liczbę całkowitą).

Składnia

makeInteger(value);

Parametry

Powiązane uprawnienia

Brak.

makeNumber

Przekształca podaną wartość w liczbę.

Składnia

makeNumber(value);

Parametry

Powiązane uprawnienia

Brak.

makeString

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

Składnia

makeString(value);

Parametry

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 łatwiej zarządzać.

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

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

na mapę:

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

Zwraca obiekt: dodano do niego przekonwertowane pary klucz-wartość Map lub null.

Składnia

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parametry

Powiązane uprawnienia

Brak.

parseUrl

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

W przypadku nieprawidłowo sformatowanego 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 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.

returnResponse

Usuwa odpowiedź, która została wcześniej ustawiona przez inne szablony za pomocą interfejsów API modyfikujących odpowiedź, w tym setCookie, setPixelResponse, setResponseBody, setResponseHeader i setResponseStatus. Domyślnie jest to kod stanu HTTP 200, pusta treść i brak nagłówków.

Zalecamy używanie tego interfejsu API z szablonu klienta.

Składnia

returnResponse();

Przykład

Zobacz przykład runContainer.

Powiązane uprawnienia

return_response

runContainer

Uruchamia logikę kontenera (zmienne, reguły, tagi) w zakresie zdarzenia. Jeśli ten interfejs API zostanie wywołany podczas wykonywania kontenera, kontener zostanie uruchomiony ponownie.

Wywołania zwrotne onComplete i onStart otrzymują funkcję o nazwie bindToEvent. Użyj bindToEvent, aby uruchomić interfejs API w kontekście zdarzenia. Więcej informacji znajdziesz w przykładzie addEventCallback.

Zalecamy używanie tego interfejsu API w szablonie klienta.

Przykład

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

Składnia

runContainer(event, onComplete, onStart);

Parametry

Powiązane uprawnienia

run_container

sendEventToGoogleAnalytics

Wysyła do Google Analytics pojedyncze zdarzenie, korzystając z wspólnych danych zdarzenia, i zwraca obietnicę, która rozwiązuje się do obiektu z kluczem location lub odrzuca do obiektu z kluczem reason. Miejsce docelowe, czyli Google Analytics, jest określane na podstawie identyfikatora pomiaru w danych zdarzenia.

Pole location jest ustawione na nagłówek location, jeśli jest obecny.

Przykład

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

Składnia

sendEventToGoogleAnalytics(event);

Parametry

Powiązane uprawnienia

Wymaga uprawnienia send_http. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej:

• Zezwalanie na Google Domains

sendHttpGet

Wysyła żądanie GET HTTP na określony adres URL i zwraca obietnicę, która jest realizowana z wynikiem po zakończeniu żądania lub przekroczeniu limitu czasu.

Rozwiązany wynik to obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, niepowodzenie negocjacji SSL itp.), obietnica zostanie odrzucona z błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona i upłynął limit czasu żądania, obietnica zostanie odrzucona z powodu: {reason: 'timed_out'}

Przykład

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

Składnia

sendHttpGet(url[, options]);

Parametry

Opcje

Powiązane uprawnienia

send_http

sendHttpRequest

Wysyła żądanie HTTP na określony adres URL i zwraca obietnicę, która jest realizowana po zakończeniu żądania lub przekroczeniu limitu czasu.

Rozwiązany wynik to obiekt zawierający 3 klucze: statusCode, headers i body. Jeśli żądanie się nie powiedzie (np. nieprawidłowy adres URL, brak trasy do hosta, niepowodzenie negocjacji SSL itp.), obietnica zostanie odrzucona z błędem: {reason: 'failed'}. Jeśli opcja timeout została ustawiona i upłynął limit czasu żądania, obietnica zostanie odrzucona z komunikatem: {reason: 'timed_out'}

Przykład

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

Składnia

sendHttpRequest(url[, options[, body]]);

Parametry

Opcje

Powiązane uprawnienia

send_http

sendPixelFromBrowser

Wysyła do przeglądarki polecenie wczytania podanego adresu URL jako tagu <img>. Ten protokół poleceń jest obsługiwany w tagu Google w przypadku Google Analytics i w tagu internetowym Google Analytics: zdarzenie GA. Musisz skonfigurować adres URL kontenera serwera. Więcej informacji znajdziesz w instrukcjach.

Ten interfejs API zwraca false, jeśli żądanie przychodzące nie obsługuje protokołu poleceń lub jeśli odpowiedź została już opróżniona. W przeciwnym razie ten interfejs API zwraca true.

Przykład:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

Składnia

sendPixelFromBrowser(url)

Parametry

Powiązane uprawnienia

send_pixel_from_browser

setCookie

Ustawia lub usuwa plik cookie z określonymi opcjami.

Aby usunąć plik cookie, należy ustawić plik cookie z tą samą ścieżką i domeną, z którą został utworzony, i przypisać mu wartość wygaśnięcia, która jest w przeszłości, np. "Thu, 01 Jan 1970 00:00:00 GMT".

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, należy wywołać funkcję returnResponse.

Przykład

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

Składnia

setCookie(name, value[, options[, noEncode]]);

Parametry

Opcje

• domain:host, do którego zostanie wysłany plik cookie. Jeśli ustawisz specjalną wartość „auto”, host zostanie automatycznie obliczony przy użyciu tej strategii:

  • eTLD+1 nagłówka Forwarded, jeśli występuje.
  • eTLD+1 nagłówka X-Forwarded-Host, jeśli występuje.
  • eTLD+1 nagłówka Host.

• expires: maksymalny okres ważności pliku cookie. Musi to być ciąg znaków daty w formacie UTC, np. „Sat, 26 Oct 1985 08:21:00 GMT”. Jeśli ustawione są zarówno expires, jak i max-age, pierwszeństwo ma max-age.

• httpOnly: uniemożliwia JavaScriptowi dostęp do pliku cookie, jeśli true.

• max-age: liczba sekund do wygaśnięcia pliku cookie. Zero lub liczba ujemna spowoduje natychmiastowe wygaśnięcie pliku cookie. Jeśli skonfigurowano zarówno zasadę expires, jak i zasadę max-age, pierwszeństwo ma zasada max-age.

• path: ścieżka, która musi występować w żądanym adresie URL, w przeciwnym razie przeglądarka nie wyśle nagłówka Cookie.

• secure: jeśli wartość tego parametru to true, plik cookie jest wysyłany na serwer tylko wtedy, gdy żądanie jest wysyłane z punktu końcowego https:.

• sameSite: potwierdza, że plik cookie nie może być wysyłany z żądaniami współdzielenia. Musi to być 'strict', 'lax' lub 'none'.

Powiązane uprawnienia

set_cookie

setPixelResponse

Ustawia treść odpowiedzi na GIF-a 1 x 1, nagłówek Content-Type na „image/gif”, nagłówki pamięci podręcznej tak, aby klienci użytkownika nie zapisywali odpowiedzi w pamięci podręcznej, a stan odpowiedzi na 200.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, należy wywołać funkcję returnResponse.

Składnia

setPixelResponse();

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• headers – musi zezwalać na te klucze:
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

setResponseBody

Ustawia treść odpowiedzi na argument.

Pamiętaj, że aby odpowiedź została wysłana z powrotem do klienta, należy wywołać funkcję returnResponse.

Składnia

setResponseBody(body[, encoding]);

Parametry

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• body

setResponseHeader

Ustawia nagłówek w zwracanej odpowiedzi. Jeśli nagłówek o tej nazwie (wielkość liter nie jest rozróżniana) został wcześniej ustawiony przez ten interfejs API, późniejsze wywołanie zastąpi lub wyczyści wartość ustawioną przez poprzedni element wywołujący.

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseHeader(name, value);

Parametry

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• headers

setResponseStatus

Ustawia kod stanu HTTP odpowiedzi, która zostanie zwrócona.

Pamiętaj, że aby odpowiedź została odesłana do klienta, musisz wywołać funkcję returnResponse.

Składnia

setResponseStatus(statusCode);

Parametry

Powiązane uprawnienia

Wymaga uprawnienia access_response. Uprawnienie musi być skonfigurowane tak, aby zezwalać na dostęp do co najmniej tych elementów:

• status

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.

Podpis i zachowanie tego interfejsu API są zgodne z interfejsem API sha256 przeznaczonym do kontenerów internetowych. Szablony niestandardowe w kontenerach serwerowych powinny jednak używać interfejsu API sha256Sync, aby kod był prostszy.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

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

Składnia

sha256(input, onSuccess, options = undefined);

Parametry

Powiązane uprawnienia

Brak.

sha256Sync

Oblicza i zwraca skrót SHA-256 danych wejściowych zakodowany w formacie base64, chyba że obiekt options określa inne kodowanie wyjściowe.

Przykład

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

Składnia

sha256Sync(input, options = undefined);

Parametry

Powiązane uprawnienia

Brak.

templateDataStorage

Zwraca obiekt z metodami dostępu do magazynu danych szablonu. Magazyn danych szablonu umożliwia udostępnianie danych w ramach wielu wykonań jednego szablonu. Dane przechowywane w magazynie danych szablonu są trwale przechowywane na serwerze, na którym działa kontener. W większości przypadków kontener jest uruchamiany na wielu serwerach, więc przechowywanie danych w magazynie danych szablonu nie gwarantuje, że każde kolejne żądanie będzie miało do nich dostęp.

Słowo „data” w nazwie „templateDataStorage” odnosi się do faktu, że za pomocą tego interfejsu API można przechowywać tylko zwykłe, niefunkcyjne typy danych. Wszelkie funkcje lub odwołania do funkcji przekazywane do interfejsu API będą przechowywane jako null.

Składnia

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

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

Przykład

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

Powiązane uprawnienia

access_template_storage

testRegex

Sprawdza ciąg znaków pod kątem wyrażenia regularnego utworzonego za pomocą interfejsu API createRegex. Zwraca wartość true, jeśli wyrażenie regularne pasuje. W przeciwnym razie zwraca wartość false.

Wyrażenie regularne utworzone z flagą globalną jest stanowe. Szczegółowe informacje znajdziesz w dokumentacji RegExp.

Przykład

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

Składnia

testRegex(regex, string);

Parametry

Powiązane uprawnienia

Brak.

toBase64

Koduje ciąg znaków w formacie base64 lub base64url. Domyślnie jest to kodowanie base64.

Składnia

toBase64(input, options);

Parametry

Opcje

Przykład

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

Powiązane uprawnienia

Brak.

BigQuery

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

Funkcja BigQuery.insert umożliwia zapisywanie danych w tabeli BigQuery. Zwraca obietnicę, która jest spełniana po pomyślnym wstawieniu lub odrzucana w przypadku błędu.

Gdy wstawianie się powiedzie, obietnica zostanie spełniona bez argumentów.

Jeśli wstawianie się nie powiedzie, obietnica zostanie odrzucona z listą obiektów zawierających przyczynę błędu i ewentualnie obiekt wiersza, jeśli wystąpi błąd. Może się zdarzyć, że część żądania zostanie zrealizowana, a część nie. W tym przypadku obietnica jest odrzucana z listą błędów dla każdego wiersza z obiektem wiersza, aby ułatwić odróżnienie wstawionych wierszy (patrz Przykłady błędów poniżej). Więcej informacji znajdziesz w dokumentacji BigQuery dotyczącej komunikatów o błędach.

Składnia

BigQuery.insert(connectionInfo, rows[, options]);

Parametry

Opcje

Przykłady błędów

Błąd „Nie znaleziono modułu” oznacza, że kontener serwera prawdopodobnie korzysta ze starszej wersji naszego obrazu, która nie zawiera jeszcze modułu BigQuery. Wdróż ponownie kontener serwera z tymi samymi ustawieniami, używając naszego skryptu wdrażania. Moduł zostanie automatycznie uwzględniony po zakończeniu operacji.

Błąd niepowodzenia wstawienia zwykle zawiera 1 obiekt błędu z kluczem reason:

[{reason: 'invalid'}]

Błąd wstawiania może zawierać wiele obiektów błędu z tablicą errors i obiektem row. Oto przykład odpowiedzi z błędem po wstawieniu 2 wierszy, z których tylko 1 zawiera błąd:

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

Przykład

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

Powiązane uprawnienia

access_bigquery

Firestore

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

Ten interfejs API obsługuje tylko Firestore w trybie natywnym, a nie Firestore w trybie Datastore. Interfejs API obsługuje też tylko domyślną bazę danych.

Firestore.read

Funkcja Firestore.read odczytuje dane z dokumentu Firestore i zwraca obietnicę, która rozwiązuje się do obiektu zawierającego 2 klucze: id i data. Jeśli dokument nie istnieje, obietnica zostanie odrzucona z obiektem zawierającym klucz reason równy not_found.

Składnia

Firestore.read(path[, options]);

Parametry

Opcje

Przykład

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

Funkcja Firestore.write zapisuje dane w dokumencie lub kolekcji Firestore. Jeśli ścieżka prowadzi do kolekcji, zostanie utworzony dokument z losowo wygenerowanym identyfikatorem. Jeśli ścieżka prowadzi do dokumentu, który nie istnieje, zostanie on utworzony. Ten interfejs API zwraca obietnicę, która jest rozwiązywana do identyfikatora dodanego lub zmodyfikowanego dokumentu. Jeśli używana jest opcja transakcji, interfejs API nadal zwraca obietnicę, ale nie będzie ona zawierać identyfikatora, ponieważ zapisy są grupowane.

Składnia

Firestore.write(path, input[, options]);

Parametry

Opcje

Przykład

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

Funkcja Firestore.query wysyła zapytanie do danej kolekcji i zwraca obietnicę, która rozwiązuje się do tablicy dokumentów Firestore spełniających warunki zapytania. Obiekt dokumentu Firestore jest taki sam jak opisany powyżej w sekcji Firestore.read. Jeśli nie ma dokumentów spełniających warunki zapytania, zwrócona obietnica zostanie rozwiązana do pustej tablicy.

Składnia

Firestore.query(collection, queryConditions[, options]);

Parametry

Opcje

Przykład

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

Funkcja Firestore.runTransaction umożliwia użytkownikowi niepodzielny odczyt i zapis w Firestore. Jeśli wystąpi jednoczesny zapis lub inny konflikt transakcji, transakcja zostanie ponowiona maksymalnie 2 razy. Jeśli po 3 próbach nie uda się go zrealizować, interfejs API odrzuci je i zwróci błąd. Ten interfejs API zwraca obietnicę, która w przypadku powodzenia transakcji jest rozwiązywana jako tablica identyfikatorów dokumentów dla każdej operacji zapisu, a w przypadku niepowodzenia jest odrzucana z błędem.

Składnia

Firestore.runTransaction(callback[, options]);

Parametry

Opcje

Przykład

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Przykładowy błąd

Błędy są dostępne w każdej funkcji Firestore i będą odrzucane z obiektem zawierającym klucz reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

Przyczyny błędów mogą obejmować m.in. kody błędów interfejsu Firestore REST API.

Powiązane uprawnienia

access_firestore

JSON

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

Funkcja parse() analizuje ciąg 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 zwróci wartość undefined.

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'});

Składnia

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

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.

Messages

Te interfejsy API współpracują ze sobą, aby umożliwić przekazywanie wiadomości między różnymi częściami kontenera.

addMessageListener

Dodaje funkcję, która nasłuchuje wiadomości określonego typu. Gdy wiadomość tego typu jest wysyłana za pomocą interfejsu sendMessage API (zwykle przez tag), wywołanie zwrotne jest uruchamiane synchronicznie. Wywołanie zwrotne jest uruchamiane z 2 parametrami:

1. messageType:string
2. message:Object

Jeśli wywołanie zwrotne zostanie dodane w kliencie, będzie otrzymywać wiadomości ze wszystkich zdarzeń utworzonych przez tego klienta. Jeśli wywołanie zwrotne ma otrzymywać wiadomości tylko z określonego zdarzenia, powiąż ten interfejs API ze zdarzeniem za pomocą bindToEvent w funkcji onStart interfejsu API runContainer. Zobacz przykład.

Składnia

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

Parametry

Przykład

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

Powiązane uprawnienia

Wymaga uprawnienia use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalać na co najmniej:

• Typ wiadomości z Usage o wartości listen lub listen_and_send.

hasMessageListener

Zwraca wartość „true”, jeśli dla danego typu wiadomości dodano detektor wiadomości. W przeciwnym razie zwraca wartość „false” („fałsz”).

Składnia

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Powiązane uprawnienia

Brak.

sendMessage

Wysyła wiadomość określonego typu do zarejestrowanego odbiorcy. Można go używać do wysyłania wiadomości z tagu z powrotem do klienta, który uruchomił kontener.

Składnia

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

Parametry

Powiązane uprawnienia

Wymaga uprawnienia use_message. Uprawnienie musi być skonfigurowane tak, aby zezwalać na co najmniej:

• Typ wiadomości z Usage o wartości listen_and_send lub send.

Object

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

Metoda keys() zapewnia działanie biblioteki standardowej Object.keys(). Zwraca tablicę nazw własnych właściwości danego 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 biblioteki standardowej Object.values(). Zwraca tablicę wartości własnych właściwości wyliczalnych danego obiektu w takiej samej kolejności jak pętla for...in.... Jeśli wartość wejściowa nie jest obiektem, zostanie przekształcona w obiekt.

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

Metoda freeze() zapewnia zachowanie metody Object.freeze() z biblioteki standardowej. Zamrożonego obiektu nie można już zmienić. 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 jako zamrożony obiekt i zostanie zwrócony.

Metoda delete() zapewnia działanie operatora usuwania biblioteki standardowej. Usuwa dany klucz z obiektu, chyba że obiekt jest zamrożony. Podobnie jak operator usuwania biblioteki standardowej, zwraca 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. We wszystkich innych przypadkach zwraca wartość false. Różni się jednak od operatora usuwania z biblioteki standardowej pod tymi względami:

• keyToDelete nie może być ciągiem znaków rozdzielonym kropkami, który określa zagnieżdżony klucz.
• Za pomocą funkcji delete() nie można usuwać elementów z tablicy.
• Nie można użyć delete() do usunięcia 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

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.

Promise

Zwraca obiekt, który udostępnia metody interakcji z obietnicami.

Obiekty Promise są funkcjonalnie równoważne obiektom Promise w JavaScripcie. Każda instancja ma 3 metody, które zwracają obiekt Promise, co umożliwia dalsze działanie po rozstrzygnięciu obietnicy:

• .then() – obsługuje zarówno rozwiązane, jak i odrzucone zgłoszenia. Jako parametry przyjmuje 2 wywołania zwrotne: jedno dla przypadku powodzenia i jedno dla przypadku niepowodzenia.
• .catch() – obsługuje tylko odrzucone zgłoszenia. Przyjmuje jedno wywołanie zwrotne jako parametr.
• .finally() – umożliwia uruchomienie kodu niezależnie od tego, czy obietnica została spełniona czy odrzucona. Przyjmuje jedno wywołanie zwrotne jako parametr, który jest wywoływany bez argumentu.

Zmienna, która zwraca obietnicę, jest równa rozwiązanej wartości obietnicy lub false, jeśli obietnica zostanie odrzucona.

Przykład

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

Zwraca obietnicę, która:

• zostanie rozwiązana, gdy wszystkie dane wejściowe zostaną rozwiązane, lub
• odrzuca, gdy którekolwiek z danych wejściowych zostanie odrzucone.

Składnia

Promise.all(inputs);

Parametry

Przykład

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

Powiązane uprawnienia

Brak.

Promise.create

Tworzy obietnicę, która jest funkcjonalnie równoważna obietnicy JavaScriptu.

Składnia

Promise.create(resolver);

Parametry

Przykład

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

Powiązane uprawnienia

Brak.

Testowanie interfejsów API

Te interfejsy API działają z testami JavaScript w 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 dopasowujący, którego można używać 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 podmiotu. Niepowodzenie asercji spowoduje natychmiastowe zatrzymanie testu i oznaczenie go jako nieudanego. Niepowodzenie jednego testu nie wpłynie jednak na inne elementy testowania.

Składnia

assertThat(actual, opt_message)

Parametry

Dopasowania

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. Można bezpiecznie używać makiety interfejsu API w kodzie szablonu, ale działa ona tylko w trybie testowym. Przed uruchomieniem każdego testu makiety są resetowane.

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. Interfejsu API można bezpiecznie używać w kodzie szablonu, ale działa on tylko w trybie testowym. Przed każdym testem makiety są resetowane.

Składnia

mockObject(apiName, objectMock);

Parametry