APIs für serverseitiges Tagging

In diesem Dokument werden die APIs für das serverseitige Tagging beschrieben.

addEventCallback

Registriert eine Callback-Funktion, die am Ende eines Ereignisses aufgerufen wird. Der Rückruf wird aufgerufen, wenn alle Tags für das Ereignis ausgeführt wurden. Dem Rückruf werden zwei Werte übergeben: die ID des Containers, der die Funktion aufruft, und ein Objekt mit Informationen zum Ereignis.

Wenn diese API in einem Tag verwendet wird, wird sie dem aktuellen Ereignis zugeordnet. Wenn diese API in einem Client verwendet wird, muss sie mithilfe der bindToEvent-Funktion der runContainer API an ein bestimmtes Ereignis gebunden werden. Weitere Informationen finden Sie im Beispiel.

Syntax

const addEventCallback = require('addEventCallback');

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

Parameter

Das eventData-Objekt enthält die folgenden Daten:

Beispiel

In einem Client:

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

In einem Tag:

const addEventCallback = require('addEventCallback');

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

Verknüpfte Berechtigungen

read_event_metadata

callLater

Hiermit wird ein asynchroner Aufruf einer Funktion geplant. Die Funktion wird aufgerufen, nachdem der aktuelle Code zurückgegeben wurde. Dies entspricht setTimeout(<function>, 0).

Beispiel

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

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

Syntax

callLater(function)

Parameter

Verknüpfte Berechtigungen

Keine.

claimRequest

Verwende diese API in einem Client, um den Anspruch auf die Anfrage geltend zu machen. Sobald eine Anfrage beansprucht wurde, werden im Container keine zusätzlichen Clients ausgeführt.

Diese API löst eine Ausnahme aus, wenn sie in einem Tag oder einer Variablen aufgerufen wird. Diese API wirft eine Ausnahme, wenn sie nach der Rückgabe des Clients aufgerufen wird (z.B. in einem asynchronen Callback wie in callLater oder in der Funktion runContainer onComplete).

Ein Kunde sollte die Anfrage mit dieser API geltend machen, bevor er die runContainer API aufruft.

Beispiel

const claimRequest = require('claimRequest');

claimRequest();

Syntax

claimRequest();

Verknüpfte Berechtigungen

Keine.

computeEffectiveTldPlusOne

Gibt die effektive Top-Level-Domain + 1 (eTLD+1) der angegebenen Domain oder URL zurück. Die eTLD+1 wird berechnet, indem die Domain anhand der Regeln der Liste öffentlicher Suffixe ausgewertet wird. Die eTLD+1 ist in der Regel die Domain auf der höchsten Ebene, auf der Sie ein Cookie setzen können.

Wenn das Argument null oder nicht definiert ist, wird der Argumentwert unverändert zurückgegeben. Andernfalls wird das Argument in einen String umgewandelt. Wenn das Argument keine gültige Domain oder URL ist, wird ein leerer String zurückgegeben. Wenn der Server die öffentliche Suffixliste nicht abrufen kann, wird der Argumentwert unverändert zurückgegeben.

Beispiel

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

Syntax

computeEffectiveTldPlusOne(domainOrUrl);

Parameter

Verknüpfte Berechtigungen

Keine.

createRegex

Erstellt eine neue reguläre Ausdrucks-Instanz und gibt sie in einem Objekt zurück. Sie können nicht direkt auf den regulären Ausdruck zugreifen. Sie können sie jedoch an die testRegex API, String.replace(), String.match() und String.search() übergeben.

Gibt null zurück, wenn der reguläre Ausdruck ungültig ist oder Re2 auf dem Server nicht verfügbar ist.

Diese API verwendet eine Re2-Implementierung. Das Docker-Image des Servers muss Version 2.0.0 oder höher haben.

Beispiel

const createRegex = require('createRegex');

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

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

Syntax

createRegex(pattern, flags);

Parameter

Verknüpfte Berechtigungen

Keine.

Mindestversion des Bildes

2.0.0

decodeUri

Decodiert alle codierten Zeichen im angegebenen URI. Gibt einen String zurück, der den decodierten URI darstellt. Gibt undefined zurück, wenn eine ungültige Eingabe bereitgestellt wird.

Beispiel

const decodeUri = require('decodeUri');

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

Syntax

decodeUri(encoded_uri);

Parameter

Verknüpfte Berechtigungen

Keine.

decodeUriComponent

Decodiert alle codierten Zeichen in der angegebenen URI-Komponente. Gibt einen String zurück, der die decodierte URI-Komponente darstellt. Gibt undefined zurück, wenn eine ungültige Eingabe vorliegt.

Beispiel

const decodeUriComponent = require('decodeUriComponent');

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

Syntax

decodeUriComponent(encoded_uri_component);

Parameter

Verknüpfte Berechtigungen

Keine.

encodeUri

Gibt einen codierten Uniform Resource Identifier (URI) zurück, indem Sonderzeichen mit einem Escape-Zeichen versehen werden. Gibt einen String zurück, der den angegebenen String als URI codiert darstellt.

Beispiel

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

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

Syntax

encodeUri(uri);

Parameter

Verknüpfte Berechtigungen

Keine.

encodeUriComponent

Gibt einen codierten Uniform Resource Identifier (URI) zurück, indem Sonderzeichen mit einem Escape-Zeichen versehen werden. Gibt einen String zurück, der den angegebenen String als URI codiert darstellt.

Beispiel

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

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

Syntax

encodeUriComponent(str);

Parameter

Verknüpfte Berechtigungen

Keine.

extractEventsFromMpv1

Eine eingehende Measurement Protocol V1-Anfrage in eine Liste von Ereignissen im Unified Schema-Format umwandelt. Liste der extrahierten Ereignisse zurückgeben Es wird ein Fehler ausgegeben, wenn die Anfrage nicht im richtigen Format ist.

Beispiel

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.
  }
}

Syntax

extractEventsFromMpv1();

Verknüpfte Berechtigungen

Erfordert die Berechtigung read_request. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• body
• query parameters

extractEventsFromMpv2

Eine eingehende Measurement Protocol V2-Anfrage in eine Liste von Ereignissen im Unified Schema-Format umwandelt. Liste der extrahierten Ereignisse zurückgeben Es wird ein Fehler ausgegeben, wenn die Anfrage nicht im richtigen Format ist.

Beispiel

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.
  }
}

Syntax

extractEventsFromMpv2();

Verknüpfte Berechtigungen

Erfordert die Berechtigung read_request. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• body
• query parameters

fromBase64

Decodiert einen base64-codierten String. Gibt undefined zurück, wenn die Eingabe ungültig ist.

Syntax

fromBase64(base64EncodedString);

Parameter

Beispiel

const fromBase64 = require('fromBase64');

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

Verknüpfte Berechtigungen

Keine.

generateRandom

Gibt eine zufällige Zahl (Ganzzahl) innerhalb des angegebenen Bereichs zurück.

Beispiel

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Syntax

generateRandom(min, max);

Parameter

Verknüpfte Berechtigungen

Keine.

getAllEventData

Gibt eine Kopie der Ereignisdaten zurück.

Syntax

getAllEventData();

Verknüpfte Berechtigungen

read_event_data

getClientName

Gibt einen String zurück, der den Namen des aktuellen Clients enthält.

Syntax

getClientName();

Verknüpfte Berechtigungen

read_container_data

getContainerVersion

Gibt ein Objekt mit Daten zum aktuellen Container zurück. Das zurückgegebene Objekt enthält die folgenden Felder:

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

Beispiel

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Syntax

getContainerVersion();

Verknüpfte Berechtigungen

read_container_data

getCookieValues

Gibt ein Array mit den Werten aller Cookies mit dem angegebenen Namen zurück.

Beispiel

const getCookieValues = require('getCookieValues');

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

Syntax

getCookieValues(name[, noDecode]);

Parameter

Verknüpfte Berechtigungen

get_cookies

getEventData

Gibt eine Kopie des Werts am angegebenen Pfad in den Ereignisdaten zurück. Gibt undefined zurück, wenn keine Ereignisdaten vorhanden sind oder wenn für den angegebenen Pfad kein Wert vorhanden ist.

Beispiel

const getEventData = require('getEventData');

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

Parameter

Syntax

getEventData(keyPath);

Verknüpfte Berechtigungen

read_event_data

getGoogleAuth

Gibt ein Autorisierungsobjekt zurück, das bei Verwendung mit sendHttpGet oder sendHttpRequest einen Autorisierungsheader für Google Cloud APIs enthält. Diese API verwendet Standardanmeldedaten für Anwendungen, um Anmeldedaten automatisch aus der Serverumgebung zu finden.

Beispiel

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

Syntax

getGoogleAuth(scopes);

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung use_google_credentials. Die Berechtigung muss mit einem oder mehreren zulässigen Zugriffsbereichen konfiguriert sein.

getGoogleScript

Ruft eine Ressource aus einer vordefinierten Gruppe von Google-Scripts ab und gibt ein Promise mit dem Script und den zugehörigen Caching-Metadaten zurück.

Das Promise wird in ein Objekt aufgelöst, das zwei Schlüssel enthält: script und metadata. Wenn die Anfrage fehlschlägt, wird das Versprechen mit dem Schlüssel reason abgelehnt.

Das metadata-Objekt enthält die folgenden Cache-Metadaten, die auf den Headern der Ressourcenantwort basieren. Jedes Feld ist nur vorhanden, wenn der entsprechende Header in der Ressourcenantwort vorhanden ist.

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

Beispiel

const getGoogleScript = require('getGoogleScript');

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

Syntax

getGoogleScript(script[, options]);

Parameter

Optionen

Nicht erkannte Optionen werden ignoriert.

Verknüpfte Berechtigungen

Erfordert die Berechtigung send_http. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens folgende Elemente zulässig ist:

• Google Domains zulassen

getRemoteAddress

Gibt eine Stringdarstellung der IP-Adresse zurück, von der die Anfrage stammt, z. B. 12.345.67.890 für IPv4 oder 2001:0db8:85a3:0:0:8a2e:0370:7334 für IPv6. Dazu werden Anfrageheader wie „Forwarded“ und „X-Forwarded-For“ gelesen. Hinweis: Diese API versucht zwar, die IP-Adresse des Ursprungs zu ermitteln, kann aber nicht garantieren, dass das Ergebnis korrekt ist.

Syntax

getRemoteAddress();

Verknüpfte Berechtigungen

Erfordert die Berechtigung read_request. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• Überschriften Forwarded und X-Forwarded-For
• Remote-IP-Adresse

getRequestBody

Gibt den Anfragetext als String zurück, falls vorhanden, andernfalls undefined.

Syntax

getRequestBody();

Verknüpfte Berechtigungen

read_request

getRequestHeader

Gibt den Wert des benannten Anfrageheaders als String zurück, sofern vorhanden, andernfalls undefined. Wenn der Header wiederholt wird, werden die zurückgegebenen Werte mit ', ' zusammengeführt.

Beispiel

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Syntax

getRequestHeader(headerName);

Parameter

Verknüpfte Berechtigungen

read_request

getRequestMethod

Gibt die Anfragemethode, z. B. 'GET' oder 'POST', als String zurück.

Beispiel

const getRequestMethod = require('getRequestMethod');

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

Syntax

getRequestMethod();

Verknüpfte Berechtigungen

Keine.

getRequestPath

Gibt den Anfragepfad ohne den Abfragestring zurück. Wenn die URL beispielsweise '/foo?id=123' lautet, wird '/foo' zurückgegeben. Entfernt automatisch das Präfix der Servercontainer-URL aus dem Pfad. Wenn die Servercontainer-URL beispielsweise https://example.com/analytics und der Anfragepfad '/analytics/foo' lautet, wird '/foo' zurückgegeben.

Beispiel

const getRequestPath = require('getRequestPath');

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

Syntax

getRequestPath();

Verknüpfte Berechtigungen

read_request

getRequestQueryParameter

Gibt den decodierten Wert des benannten Suchstringparameters als String zurück oder undefined, wenn der Parameter nicht vorhanden ist. Wenn der Parameter im Abfragestring wiederholt wird, wird der erste Wert zurückgegeben, der im Abfragestring erscheint.

Beispiel

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Syntax

getRequestQueryParameter(name);

Parameter

Verknüpfte Berechtigungen

read_request

getRequestQueryParameters

Gibt die Abfrageparameter der eingehenden HTTP-Anfrage als Objekt zurück, das Abfrageparameternamen den entsprechenden Werten zuordnet. Die Parameternamen und ‑werte werden decodiert.

Beispiel

const getRequestQueryParameters = require('getRequestQueryParameters');

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

Syntax

getRequestQueryParameters();

Verknüpfte Berechtigungen

read_request

getRequestQueryString

Gibt die Abfrage als String zurück, ohne das vorangestellte Fragezeichen, oder einen leeren String, wenn die Anfrage-URL keinen Abfragestring enthält.

Beispiel

const getRequestQueryString = require('getRequestQueryString');

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

Syntax

getRequestQueryString();

Verknüpfte Berechtigungen

read_request

getTimestamp

Veraltet. Verwenden Sie stattdessen getTimestampMillis.

Gibt eine Zahl zurück, die die aktuelle Zeit in Millisekunden seit der Unix-Epoche angibt, wie von Date.now() zurückgegeben.

Syntax

getTimestamp();

Verknüpfte Berechtigungen

Keine.

getTimestampMillis

Gibt eine Zahl zurück, die die aktuelle Zeit in Millisekunden seit der Unix-Epoche angibt, wie von Date.now() zurückgegeben.

Syntax

getTimestampMillis();

Verknüpfte Berechtigungen

Keine.

getType

Gibt einen String zurück, der den Typ des angegebenen Werts beschreibt.

Beispiel

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

Syntax

getType(value);

Parameter

Verknüpfte Berechtigungen

Keine.

hmacSha256

Berechnet eine codierte Signatur mit dem Hash-basierten Message Authentication Code (HMAC) mit SHA-256. Die Standardeinstellung ist die base64url-Codierung.

Wenn Sie diese API verwenden möchten, legen Sie die Umgebungsvariable SGTM_CREDENTIALS auf dem Server auf den Pfad einer UTF-8-codierten JSON-Schlüsseldatei mit dem folgenden Format fest:

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

Die Werte sind base64-codierte HMAC-Schlüssel. Der JSON-Text darf nicht mit einer Bytereihenfolge-Marke beginnen.

Beispiel

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;

Syntax

hmacSha256(data, keyId, options)

Parameter

Optionen

Verknüpfte Berechtigungen

use_custom_private_keys

Mindestversion des Bildes

1.0.0

isRequestMpv1

Gibt true zurück, wenn es sich bei der eingehenden Anfrage um eine Measurement Protocol V1-Anfrage handelt. Andernfalls wird false zurückgegeben.

Beispiel

const isRequestMpv1 = require('isRequestMpv1');

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

Syntax

isRequestMpv1();

Verknüpfte Berechtigungen

Keine.

isRequestMpv2

Gibt true zurück, wenn es sich bei der eingehenden Anfrage um eine Measurement Protocol V2-Anfrage handelt, andernfalls false.

Beispiel

const isRequestMpv2 = require('isRequestMpv2');

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

Syntax

isRequestMpv2();

Verknüpfte Berechtigungen

Keine.

logToConsole

Die Argumente werden in der Konsole protokolliert.

Diese Logs sind im Log-Explorer in der Google Cloud Console sichtbar. Führen Sie im Log-Explorer die Abfrage logName =~ "stdout" aus, um die von dieser API erstellten Logeinträge aufzurufen.

Beispiel

const logToConsole = require('logToConsole');

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

Syntax

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

Parameter

Die API nimmt ein oder mehrere Argumente entgegen, die bei Bedarf in einen String umgewandelt und in der Konsole protokolliert werden.

Verknüpfte Berechtigungen

logging

makeInteger

Wandelt den angegebenen Wert in eine Zahl (Ganzzahl) um.

Syntax

makeInteger(value);

Parameter

Verknüpfte Berechtigungen

Keine.

makeNumber

Wandelt den angegebenen Wert in eine Zahl um.

Syntax

makeNumber(value);

Parameter

Verknüpfte Berechtigungen

Keine.

makeString

Gibt den angegebenen Wert als String zurück.

Syntax

makeString(value);

Parameter

Verknüpfte Berechtigungen

Keine.

makeTableMap

Wandelt ein einfaches Tabellenobjekt mit zwei Spalten in eine Map um. So können Sie ein SIMPLE_TABLE-Vorlagesfeld mit zwei Spalten in ein übersichtlicheres Format umwandeln.

Mit dieser Funktion kann beispielsweise ein Tabellenobjekt konvertiert werden:

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

in eine Karte:

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

Gibt ein Objekt zurück: Die konvertierte Map der Schlüssel/Wert-Paare wurde diesem Objekt hinzugefügt. Andernfalls wird null zurückgegeben.

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parameter

Verknüpfte Berechtigungen

Keine.

parseUrl

Gibt ein Objekt zurück, das alle Komponenten einer bestimmten URL enthält, ähnlich wie das URL-Objekt.

Diese API gibt für jede fehlerhafte URL undefined zurück. Bei korrekt formatierten URLs haben Felder, die nicht im URL-String vorhanden sind, den Wert einer leeren Zeichenfolge oder im Fall von searchParams einen leeren Objektwert.

Das zurückgegebene Objekt enthält die folgenden Felder:

{
  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,
}

Beispiel

const parseUrl = require('parseUrl');

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

Syntax

parseUrl(url);

Parameter

Verknüpfte Berechtigungen

Keine.

returnResponse

Die Antwort wird gelöscht, die zuvor von anderen Vorlagen mithilfe der APIs festgelegt wurde, die die Antwort ändern, einschließlich setCookie, setPixelResponse, setResponseBody, setResponseHeader und setResponseStatus. Standardmäßig wird der HTTP-Statuscode 200, ein leerer Textkörper und keine Header verwendet.

Es wird empfohlen, diese API über eine Clientvorlage zu verwenden.

Syntax

returnResponse();

Beispiel

Siehe runContainer-Beispiel.

Verknüpfte Berechtigungen

return_response

runContainer

Führt die Containerlogik (Variablen, Trigger, Tags) im Rahmen eines Ereignisses aus. Wenn diese API während der Containerausführung aufgerufen wird, wird der Container noch einmal ausgeführt.

Die Callbacks onComplete und onStart erhalten eine Funktion namens bindToEvent. Mit bindToEvent können Sie eine API im Kontext des Ereignisses ausführen. Weitere Informationen finden Sie im Beispiel addEventCallback.

Es wird empfohlen, diese API über eine Clientvorlage zu verwenden.

Beispiel

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());

Syntax

runContainer(event, onComplete, onStart);

Parameter

Verknüpfte Berechtigungen

run_container

sendEventToGoogleAnalytics

Es wird ein einzelnes Ereignis mit gemeinsamen Ereignisdaten an Google Analytics gesendet und ein Promise zurückgegeben, das auf ein Objekt mit einem location-Schlüssel verweist oder ein Objekt mit einem reason-Schlüssel zurückweist. Das Ziel, Google Analytics 4, basiert auf der Mess-ID in den Ereignisdaten.

Das Feld location ist auf den Header location gesetzt, sofern vorhanden.

Beispiel

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

Syntax

sendEventToGoogleAnalytics(event);

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung send_http. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens folgende Elemente zulässig ist:

• Google Domains zulassen

sendHttpGet

Stellt eine HTTP-GET-Anfrage an die angegebene URL und gibt ein Promise zurück, das mit dem Ergebnis abgeschlossen wird, sobald die Anfrage abgeschlossen ist oder eine Zeitüberschreitung auftritt.

Das aufgelöste Ergebnis ist ein Objekt mit drei Schlüsseln: statusCode, headers und body. Wenn die Anfrage fehlgeschlagen ist (z. B. ungültige URL, keine Route zum Host, SSL-Verhandlung fehlgeschlagen), wird das Promise mit {reason: 'failed'} abgelehnt. Wenn die Option timeout festgelegt wurde und die Anfrage eine Zeitüberschreitung verursacht hat, wird das Versprechen mit der Meldung {reason: 'timed_out'} abgelehnt.

Beispiel

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

Syntax

sendHttpGet(url[, options]);

Parameter

Optionen

Verknüpfte Berechtigungen

send_http

sendHttpRequest

Stellt eine HTTP-Anfrage an die angegebene URL und gibt ein Versprechen zurück, das mit der Antwort abgeschlossen wird, sobald die Anfrage abgeschlossen ist oder die Zeitüberschreitung eintritt.

Das aufgelöste Ergebnis ist ein Objekt mit drei Schlüsseln: statusCode, headers und body. Wenn die Anfrage fehlgeschlagen ist (z. B. ungültige URL, keine Route zum Host, SSL-Verhandlung fehlgeschlagen), wird das Promise mit {reason: 'failed'} abgelehnt. Wenn die Option timeout festgelegt wurde und die Anfrage eine Zeitüberschreitung verursacht hat, wird das Versprechen mit der Meldung {reason: 'timed_out'} abgelehnt.

Beispiel

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

Syntax

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

Parameter

Optionen

Verknüpfte Berechtigungen

send_http

sendPixelFromBrowser

Sendet einen Befehl an den Browser, die angegebene URL als <img>-Tag zu laden. Dieses Befehlsprotokoll wird vom Google-Tag für GA4 und den Web-Tags Google Analytics: GA-Ereignis unterstützt. Sie müssen die URL des Servercontainers konfigurieren. Weitere Informationen finden Sie in der Anleitung.

Diese API gibt false zurück, wenn die eingehende Anfrage das Befehlsprotokoll nicht unterstützt oder die Antwort bereits geflusht wurde. Andernfalls gibt diese API true zurück.

Beispiel:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Syntax

sendPixelFromBrowser(url)

Parameter

Verknüpfte Berechtigungen

send_pixel_from_browser

setCookie

Setzt oder löscht ein Cookie mit den angegebenen Optionen.

Um ein Cookie zu löschen, muss ein Cookie mit demselben Pfad und derselben Domain wie das ursprüngliche Cookie erstellt und ihm ein Ablaufdatum in der Vergangenheit zugewiesen werden, z. B. "Thu, 01 Jan 1970 00:00:00 GMT".

Hinweis: returnResponse muss aufgerufen werden, damit die Antwort an den Client zurückgesendet wird.

Beispiel

const setCookie = require('setCookie');

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

Syntax

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

Parameter

Optionen

• domain: Der Host, an den das Cookie gesendet wird. Bei der speziellen Einstellung „Auto“ wird der Host automatisch anhand der folgenden Strategie berechnet:

  • eTLD+1 des Forwarded-Headers, falls vorhanden.
  • eTLD+1 des X-Forwarded-Host-Headers, falls vorhanden.
  • eTLD+1 der Host-Kopfzeile.

• expires: Die maximale Lebensdauer des Cookies. Dies muss ein Datumsstring im UTC-Format sein, z. B. „Samstag, 26. Oktober 1985 08:21:00 GMT“. Wenn sowohl expires als auch max-age festgelegt sind, hat max-age Vorrang.

• httpOnly: JavaScript darf nicht auf das Cookie zugreifen, wenn true.

• max-age: Anzahl der Sekunden, bis das Cookie abläuft. Bei einer Null oder einer negativen Zahl läuft das Cookie sofort ab. Wenn sowohl expires als auch max-age festgelegt sind, hat max-age Vorrang.

• path: Ein Pfad, der in der angeforderten URL vorhanden sein muss. Andernfalls sendet der Browser den Cookie-Header nicht.

• secure: Wenn diese Option auf true gesetzt ist, wird das Cookie nur an den Server gesendet, wenn eine Anfrage von einem https:-Endpunkt erfolgt.

• sameSite: Hiermit wird angegeben, dass ein Cookie nicht mit plattformübergreifenden Anfragen gesendet werden darf. Muss 'strict', 'lax' oder 'none' sein.

Verknüpfte Berechtigungen

set_cookie

setPixelResponse

Hier wird der Antworttext auf ein 1x1-GIF festgelegt, der Content-Type-Header auf „image/gif“, Cache-Header so, dass User-Agents die Antwort nicht im Cache speichern, und der Antwortstatus auf 200.

Hinweis: returnResponse muss aufgerufen werden, damit die Antwort an den Client zurückgesendet wird.

Syntax

setPixelResponse();

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• headers – Folgende Schlüssel müssen zulässig sein
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

setResponseBody

Legt den Antworttext auf das Argument fest.

Hinweis: returnResponse muss aufgerufen werden, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseBody(body[, encoding]);

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• body

setResponseHeader

Legt einen Header in der Antwort fest, die zurückgegeben wird. Wenn ein Header mit diesem Namen (ohne Berücksichtigung der Groß- und Kleinschreibung) zuvor von dieser API festgelegt wurde, wird der Wert des vorherigen Aufrufers durch den letzten Aufruf überschrieben oder gelöscht.

Hinweis: returnResponse muss aufgerufen werden, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseHeader(name, value);

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• headers

setResponseStatus

Legt den HTTP-Statuscode der zurückzugebenden Antwort fest.

Hinweis: returnResponse muss aufgerufen werden, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseStatus(statusCode);

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes zulässig ist:

• status

sha256

Er berechnet den SHA-256-Digest der Eingabe und ruft einen Rückruf mit dem Base64-codierten Digest auf, sofern im options-Objekt keine andere Ausgabecodierung angegeben ist.

Diese API-Signatur und dieses Verhalten stimmen mit der sha256 API für Webcontainer überein. Bei benutzerdefinierten Vorlagen in Servercontainern sollte jedoch die sha256Sync API verwendet werden, um den Code zu vereinfachen.

Beispiel

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

Syntax

sha256(input, onSuccess, options = undefined);

Parameter

Verknüpfte Berechtigungen

Keine.

sha256Sync

Der SHA-256-Digest der Eingabe wird berechnet und in Base64 zurückgegeben, sofern im options-Objekt keine andere Ausgabecodierung angegeben ist.

Beispiel

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

Syntax

sha256Sync(input, options = undefined);

Parameter

Verknüpfte Berechtigungen

Keine.

templateDataStorage

Gibt ein Objekt mit Methoden für den Zugriff auf den Vorlagendatenspeicher zurück. Mit dem Vorlagendatenspeicher können Daten für mehrere Ausführungen einer einzelnen Vorlage freigegeben werden. Daten, die im Vorlagendatenspeicher gespeichert sind, bleiben auf dem Server erhalten, auf dem der Container ausgeführt wird. In den meisten Fällen werden Container auf mehreren Servern ausgeführt. Wenn Sie Daten also im Vorlagendatenspeicher speichern, ist nicht garantiert, dass jede nachfolgende Anfrage Zugriff auf die Daten hat.

Das „Daten“ in „templateDataStorage“ bezieht sich darauf, dass mit dieser API nur einfache, nicht funktionale Datentypen gespeichert werden können. Alle Funktionen oder Verweise auf Funktionen, die an die API übergeben werden, werden stattdessen als null gespeichert.

Syntax

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();

Beispiel

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

Verknüpfte Berechtigungen

access_template_storage

testRegex

Vergleicht einen String mit einem regulären Ausdruck, der über die createRegex API erstellt wurde. Gibt true zurück, wenn der reguläre Ausdruck übereinstimmt. Andernfalls wird false zurückgegeben.

Ein mit dem globalen Flag erstellter regulärer Ausdruck ist zustandsabhängig. Weitere Informationen finden Sie in der RegExp-Dokumentation.

Beispiel

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

Syntax

testRegex(regex, string);

Parameter

Verknüpfte Berechtigungen

Keine.

toBase64

Codiert einen String als Base64 oder Base64url. Standardmäßig wird die Base64-Codierung verwendet.

Syntax

toBase64(input, options);

Parameter

Optionen

Beispiel

const toBase64 = require('toBase64');

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

Verknüpfte Berechtigungen

Keine.

BigQuery

Gibt ein Objekt zurück, das BigQuery-Funktionen bereitstellt.

Mit der Funktion BigQuery.insert können Daten in eine BigQuery-Tabelle geschrieben werden. Sie gibt ein Versprechen zurück, das bei einer erfolgreichen Einfügung erfüllt oder bei einem Fehler abgelehnt wird.

Wenn die Einfügung erfolgreich ist, wird das Versprechen ohne Argumente aufgelöst.

Wenn die Einfügung fehlschlägt, wird das Versprechen mit einer Liste von Objekten abgelehnt, die den Fehlergrund und gegebenenfalls ein Zeilenobjekt enthalten. Es ist möglich, dass ein Teil der Anfrage erfolgreich abgeschlossen wird, andere Teile aber nicht. In diesem Fall wird das Promise mit einer Liste von Fehlern für jede Zeile mit einem Zeilenobjekt abgelehnt, um zu unterscheiden, welche Zeilen eingefügt wurden. Weitere Informationen finden Sie unten unter Fehlerbeispiele. Weitere Informationen finden Sie in der BigQuery-Dokumentation zu Fehlermeldungen.

Syntax

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

Parameter

Optionen

Fehlerbeispiele

Wenn der Fehler „Modul nicht gefunden“ auftritt, wird in Ihrem Servercontainer wahrscheinlich eine ältere Version unseres Images ausgeführt, die das BigQuery-Modul noch nicht enthält. Bitte stellen Sie Ihren Servercontainer mit denselben Einstellungen mit unserem Bereitstellungsskript wieder bereit. Das Modul wird automatisch eingeschlossen, sobald der Vorgang abgeschlossen ist.

Ein Fehler, der nicht auf das Einfügen zurückzuführen ist, hat in der Regel ein Fehlerobjekt mit dem Schlüssel reason:

[{reason: 'invalid'}]

Ein Einfügungsfehler kann mehrere Fehlerobjekte mit einem errors-Array und einem row-Objekt enthalten. Im folgenden Beispiel wird eine Fehlerantwort beim Einfügen von zwei Zeilen angezeigt, bei der nur eine Zeile einen Fehler enthält:

[
  {
    "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
    }
  }
]

Beispiel

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

Verknüpfte Berechtigungen

access_bigquery

Firestore

Gibt ein Objekt zurück, das Firestore-Funktionen bereitstellt.

Diese API unterstützt nur Firestore im nativen Modus, nicht Firestore im Datastore-Modus. Außerdem unterstützt die API nur die Verwendung der Standarddatenbank.

Firestore.read

Die Funktion Firestore.read liest Daten aus einem Firestore-Dokument und gibt ein Promise zurück, das in ein Objekt mit zwei Schlüsseln aufgelöst wird: id und data. Wenn das Dokument nicht vorhanden ist, wird das Versprechen mit einem Objekt abgelehnt, das einen reason-Schlüssel mit dem Wert not_found enthält.

Syntax

Firestore.read(path[, options]);

Parameter

Optionen

Beispiel

const Firestore = require('Firestore');

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

Firestore.write

Die Funktion Firestore.write schreibt Daten in ein Firestore-Dokument oder eine Firestore-Sammlung. Wenn der Pfad zu einer Sammlung führt, wird ein Dokument mit einer zufällig generierten ID erstellt. Wenn der Pfad zu einem Dokument führt, das nicht vorhanden ist, wird es erstellt. Diese API gibt ein Versprechen zurück, das auf die ID des hinzugefügten oder geänderten Dokuments verweist. Wenn die Transaktionsoption verwendet wird, gibt die API weiterhin ein Promise zurück, das aber keine ID enthält, da die Schreibvorgänge in einem Batch ausgeführt werden.

Syntax

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

Parameter

Optionen

Beispiel

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

Die Funktion Firestore.query fragt die angegebene Sammlung ab und gibt ein Versprechen zurück, das in ein Array von Firestore-Dokumenten aufgelöst wird, die den Abfragebedingungen entsprechen. Das Firestore-Dokumentobjekt ist mit dem oben in Firestore.read aufgeführten identisch. Wenn keine Dokumente gefunden werden, die den Abfragebedingungen entsprechen, wird das zurückgegebene Versprechen in ein leeres Array aufgelöst.

Syntax

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

Parameter

Optionen

Beispiel

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

Mit der Funktion Firestore.runTransaction können Nutzer atomare Lese- und Schreibvorgänge in Firestore ausführen. Wenn ein gleichzeitiger Schreibvorgang oder ein anderer Transaktionskonflikt auftritt, wird die Transaktion bis zu zweimal wiederholt. Wenn der Vorgang nach drei Versuchen fehlschlägt, lehnt die API die Anfrage mit einem Fehler ab. Diese API gibt für jeden Schreibvorgang ein Versprechen zurück, das in ein Array von Dokument-IDs aufgelöst wird, wenn die Transaktion erfolgreich ist. Andernfalls wird der Fehler zurückgegeben.

Syntax

Firestore.runTransaction(callback[, options]);

Parameter

Optionen

Beispiel

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

Fehlerbeispiel

Fehler sind in jeder Firestore-Funktion verfügbar und werden mit einem Objekt abgelehnt, das einen reason-Schlüssel enthält:

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

Zu den Fehlerursachen können unter anderem Firestore REST API-Fehlercodes gehören.

Verknüpfte Berechtigungen

access_firestore

JSON

Gibt ein Objekt zurück, das JSON-Funktionen bereitstellt.

Die Funktion parse() analysiert einen JSON-String, um den vom String beschriebenen Wert oder das vom String beschriebene Objekt zu erstellen. Wenn der Wert nicht geparst werden kann (z.B. fehlerhaftes JSON), gibt die Funktion undefined zurück. Wenn der Eingabewert kein String ist, wird er in einen String umgewandelt.

Die Funktion stringify() wandelt die Eingabe in einen JSON-String um. Wenn der Wert nicht analysiert werden kann (z.B. wenn das Objekt einen Zyklus enthält), gibt die Methode undefined zurück.

Beispiel

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

Syntax

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

Verknüpfte Berechtigungen

Keine.

Math

Ein Objekt mit Math-Funktionen.

Syntax

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

Parameter

Parameter von mathematischen Funktionen werden in Zahlen umgewandelt.

Verknüpfte Berechtigungen

Keine.

Messages

Die folgenden APIs arbeiten zusammen, um Nachrichten zwischen verschiedenen Teilen eines Containers zu übergeben.

addMessageListener

Fügt eine Funktion hinzu, die auf eine Nachricht eines bestimmten Typs wartet. Wenn eine Nachricht dieses Typs über die sendMessage API gesendet wird (in der Regel über ein Tag), wird der Rückruf synchron ausgeführt. Der Callback wird mit zwei Parametern ausgeführt:

1. messageType:string
2. message:Object

Wenn der Callback in einem Client hinzugefügt wird, erhält er Nachrichten für alle vom Client erstellten Ereignisse. Wenn der Callback nur Nachrichten von einem bestimmten Ereignis erhalten soll, binde diese API mit bindToEvent in der onStart-Funktion der runContainer API an das Ereignis. Siehe Beispiel.

Syntax

const addMessageListener = require('addMessageListener');

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

Parameter

Beispiel

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

Verknüpfte Berechtigungen

Erfordert die Berechtigung use_message. Die Berechtigung muss so konfiguriert sein, dass mindestens Folgendes zulässig ist:

• Ein Nachrichtentyp mit Usage von listen oder listen_and_send.

hasMessageListener

Gibt „true“ zurück, wenn für den angegebenen Nachrichtentyp ein Nachrichtenempfänger hinzugefügt wurde. Andernfalls wird „false“ zurückgegeben.

Syntax

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Verknüpfte Berechtigungen

Keine.

sendMessage

Sendet eine Nachricht des angegebenen Typs an einen registrierten Listener. So können Nachrichten von einem Tag an den Client zurückgesendet werden, auf dem der Container ausgeführt wurde.

Syntax

const sendMessage = require('sendMessage');

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

Parameter

Verknüpfte Berechtigungen

Erfordert die Berechtigung use_message. Die Berechtigung muss so konfiguriert sein, dass mindestens Folgendes zulässig ist:

• Ein Nachrichtentyp mit Usage von listen_and_send oder send.

Object

Gibt ein Objekt zurück, das Object-Methoden bereitstellt.

Die keys()-Methode bietet das Verhalten der Standardbibliothek Object.keys(). Es gibt ein Array mit den eigenen zählbaren Property-Namen eines bestimmten Objekts in derselben Reihenfolge zurück wie eine for...in...-Schleife. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode values() bietet das Verhalten Object.values() der Standardbibliothek. Es gibt ein Array der eigenen zählbaren Attributwerte eines bestimmten Objekts in derselben Reihenfolge zurück wie eine for...in...-Schleife. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode entries() bietet das Verhalten Object.entries() der Standardbibliothek. Es gibt ein Array der eigenen zählbaren Property eines bestimmten Objekts zurück, also [key, value]-Paare in derselben Reihenfolge wie bei einer for...in...-Schleife. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode freeze() bietet das Verhalten Object.freeze() der Standardbibliothek. Ein eingefrorenes Objekt kann nicht mehr geändert werden. Durch das Einfrieren eines Objekts wird verhindert, dass ihm neue Eigenschaften hinzugefügt, vorhandene Eigenschaften entfernt und die Werte vorhandener Eigenschaften geändert werden. freeze() gibt dasselbe Objekt zurück, das übergeben wurde. Ein primitives oder Nullargument wird behandelt, als wäre es ein eingefrorenes Objekt, und wird zurückgegeben.

Die Methode delete() bietet das Verhalten des delete-Operators der Standardbibliothek. Der angegebene Schlüssel wird aus dem Objekt entfernt, es sei denn, das Objekt ist eingefroren. Wie der Löschoperator der Standardbibliothek gibt er true zurück, wenn der erste Eingabewert (objectInput) ein Objekt ist, das nicht eingefroren ist, auch wenn der zweite Eingabewert (keyToDelete) einen nicht vorhandenen Schlüssel angibt. In allen anderen Fällen wird false zurückgegeben. Er unterscheidet sich jedoch in folgenden Punkten vom Löschoperator der Standardbibliothek:

• keyToDelete darf kein durch Punkte getrennter String sein, der einen verschachtelten Schlüssel angibt.
• Mit delete() können keine Elemente aus einem Array entfernt werden.
• Mit delete() können keine Properties aus dem globalen Gültigkeitsbereich entfernt werden.

Syntax

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

Parameter

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

Beispiel

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

Gibt ein Objekt zurück, das Methoden zum Interagieren mit Versprechen bietet.

Promises sind funktional mit JavaScript-Promises identisch. Jede Instanz hat drei Methoden, die ein Promise zurückgeben, das weitere Aktionen ermöglicht, wenn ein Promise erfüllt wird:

• .then(): Hier werden sowohl gelöste als auch abgelehnte Fälle bearbeitet. Es nimmt zwei Callbacks als Parameter entgegen: einen für den Erfolgsfall und einen für den Fehlerfall.
• .catch() – Nur abgelehnte Fälle werden bearbeitet. Nimmt einen Callback als Parameter an.
• .finally(): Bietet eine Möglichkeit, Code auszuführen, unabhängig davon, ob das Versprechen erfüllt oder abgelehnt wurde. Nimmt einen Callback als Parameter an, der ohne Argument aufgerufen wird.

Eine Variable, die ein Versprechen zurückgibt, entspricht dem aufgelösten Wert des Versprechens oder false, wenn das Versprechen abgelehnt wird.

Beispiel

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

Gibt ein Versprechen zurück, das entweder:

• wird aufgelöst, wenn alle Eingaben aufgelöst wurden, oder
• wird abgelehnt, wenn eine der Eingaben abgelehnt wird

Syntax

Promise.all(inputs);

Parameter

Beispiel

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

Verknüpfte Berechtigungen

Keine.

Promise.create

Erstellt ein Versprechen, das funktional einem JavaScript-Versprechen entspricht.

Syntax

Promise.create(resolver);

Parameter

Beispiel

const Promise = require('Promise');

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

Verknüpfte Berechtigungen

Keine.

APIs testen

Diese APIs können mit JavaScript-Tests in Sandboxes verwendet werden, um Tests für benutzerdefinierte Vorlagen in Google Tag Manager zu erstellen. Für diese Test-APIs ist keine require()-Anweisung erforderlich. [Weitere Informationen zu Tests benutzerdefinierter Vorlagen]

assertApi

Gibt ein Matcher-Objekt zurück, mit dem sich flüssige Behauptungen über die jeweilige API machen lassen.

Syntax

assertApi(apiName)

Parameter

Abgleichsmechanismen

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

Beispiele

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

assertThat

Die assertThat API ist an der [Truth]-Bibliothek von Google orientiert. Es gibt ein Objekt zurück, mit dem sich flüssig Aussagen über den Wert eines Themas treffen lassen. Bei einem Assertion-Fehler wird der Test sofort beendet und als fehlgeschlagen markiert. Ein Fehler in einem Test wirkt sich jedoch nicht auf andere Testfälle aus.

Syntax

assertThat(actual, opt_message)

Parameter

Abgleichsmechanismen

Beispiele

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

Der aktuelle Test schlägt sofort fehl und die angegebene Meldung wird ausgegeben, sofern vorhanden.

Syntax

fail(opt_message);

Parameter

Beispiel

fail('This test has failed.');

mock

Mit der mock API können Sie das Verhalten von APIs in Sandboxes überschreiben. Die Mock-API kann bedenkenlos in Vorlagencode verwendet werden, funktioniert aber nur im Testmodus. Mocks werden vor jedem Test zurückgesetzt.

Syntax

mock(apiName, returnValue);

Parameter

Beispiele

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

mockObject

Mit der mockObject API können Sie das Verhalten von APIs in Sandboxes überschreiben, die ein Objekt zurückgeben. Die API kann sicher in Vorlagencode verwendet werden, ist aber nur im Testmodus funktionsfähig. Mocks werden vor jedem Test zurückgesetzt.

Syntax

mockObject(apiName, objectMock);

Parameter