APIs für serverseitiges Tagging

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

---

addEventCallback

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

Wenn diese API in einem Tag verwendet wird, ist sie dem aktuellen Ereignis zugeordnet. Wenn diese API in einem Client verwendet wird, muss sie mit der Funktion bindToEvent 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

Parameter	Typ	Beschreibung
callback	Funktion	Die Funktion, die am Ende des Ereignisses aufgerufen werden soll.

Das eventData-Objekt enthält die folgenden Daten:

Schlüsselname	Typ	Beschreibung
tags	Array	Ein Array von Tag-Datenobjekten. Für jedes Tag, das während des Ereignisses ausgelöst wurde, ist ein Eintrag in diesem Array vorhanden. Das Tag-Datenobjekt enthält die ID des Tags (id), seinen Ausführungsstatus (status) und seine Ausführungszeit (executionTime). Die Tag-Daten enthalten auch zusätzliche Tag-Metadaten, die für das Tag konfiguriert wurden.

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

Plant einen asynchronen Aufruf einer Funktion. 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

Parameter	Typ	Beschreibung
function	Funktion	Die aufzurufende Funktion.

Verknüpfte Berechtigungen

Keine.

---

claimRequest

Verwenden Sie diese API in einem Client, um die Anfrage zu übernehmen. Sobald eine Anfrage beansprucht wird, 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 löst eine Ausnahme aus, wenn sie nach der Rückgabe des Clients aufgerufen wird, z.B. in einem asynchronen Callback wie in callLater oder der Funktion runContainer onComplete.

Ein Client sollte die Anfrage mit dieser API beanspruchen, 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 festlegen können.

Wenn das Argument „null“ oder „undefined“ 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

Parameter	Typ	Beschreibung
domainOrUrl	String	Eine Domain oder URL, für die die eTLD+1 berechnet werden soll.

Verknüpfte Berechtigungen

Keine.

---

createRegex

Erstellt eine neue Regex-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 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

Parameter	Typ	Beschreibung
pattern	String	Text des regulären Ausdrucks.
flags	String	Ein optionaler String mit den Flags für den zu erstellenden regulären Ausdruck. Die Flags „g“ (global) und „i“ (Groß-/Kleinschreibung ignorieren) werden unterstützt. Alle anderen Zeichen werden ignoriert.

Verknüpfte Berechtigungen

Keine.

Mindestversion des Images

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

Beispiel

const decodeUri = require('decodeUri');

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

Syntax

decodeUri(encoded_uri);

Parameter

Parameter	Typ	Beschreibung
encoded_uri	String	Ein URI, der mit encodeUri() oder auf andere Weise codiert wurde.

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

Beispiel

const decodeUriComponent = require('decodeUriComponent');

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

Syntax

decodeUriComponent(encoded_uri_component);

Parameter

Parameter	Typ	Beschreibung
encoded_uri_component	String	Eine URI-Komponente, die mit encodeUriComponent() oder auf andere Weise codiert wurde.

Verknüpfte Berechtigungen

Keine.

---

encodeUri

Gibt einen codierten URI (Uniform Resource Identifier) zurück, indem Sonderzeichen maskiert 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

Parameter	Typ	Beschreibung
uri	String	Ein vollständiger URI.

Verknüpfte Berechtigungen

Keine.

---

encodeUriComponent

Gibt einen codierten URI (Uniform Resource Identifier) zurück, indem Sonderzeichen maskiert werden. Gibt einen String zurück, der den bereitgestellten 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

Parameter	Typ	Beschreibung
str	String	Eine Komponente eines URI.

Verknüpfte Berechtigungen

Keine.

---

extractEventsFromMpv1

Übersetzt eine eingehende Measurement Protocol V1-Anfrage in eine Liste von Ereignissen im Unified Schema-Format. Gibt die Liste der extrahierten Ereignisse zurück. Gibt einen Fehler aus, wenn die Anfrage nicht das richtige Format hat.

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 möglich ist:

• body
• query parameters

---

extractEventsFromMpv2

Übersetzt eine eingehende Measurement Protocol V2-Anfrage in eine Liste von Ereignissen im Unified Schema-Format. Gibt die Liste der extrahierten Ereignisse zurück. Gibt einen Fehler aus, wenn die Anfrage nicht das richtige Format hat.

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 möglich ist:

• body
• query parameters

---

fromBase64

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

Syntax

fromBase64(base64EncodedString);

Parameter

Parameter	Typ	Beschreibung
base64EncodedString	String	Base64-codierter String.

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

Parameter	Typ	Beschreibung
min	number	Minimaler potenzieller Wert der zurückgegebenen Ganzzahl (einschließlich).
max	number	Maximaler potenzieller Wert der zurückgegebenen Ganzzahl (einschließlich).

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 hat 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

Parameter	Typ	Beschreibung
name	String	Name des Cookies.
noDecode	boolean	Wenn true, werden die Cookiewerte vor der Rückgabe nicht decodiert. Die Standardeinstellung ist false.

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 oder kein Wert für den angegebenen Pfad vorhanden ist.

Beispiel

const getEventData = require('getEventData');

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

Parameter

Parameter	Typ	Beschreibung
keyPath	Beliebig	Der Pfad des Schlüssels. Die Pfadkomponenten sind durch Punkte getrennt. Die Pfadkomponenten können Schlüssel in einem Objekt oder Indexe in einem Array sein. Wenn keyPath kein String ist, wird es in einen String umgewandelt.

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

Parameter	Typ	Beschreibung
scopes	Array	Ein Array von OAuth 2.0-Bereichen für Google APIs, für die Zugriff angefordert werden soll.

Verknüpfte Berechtigungen

Erfordert die Berechtigung use_google_credentials. Die Berechtigung muss mit mindestens einem zulässigen Zugriffsbereich konfiguriert werden.

---

getGoogleScript

Ruft eine Ressource aus einer vorgegebenen 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 Promise mit dem Schlüssel reason abgelehnt.

Das metadata-Objekt enthält die folgenden Caching-Metadaten basierend auf den Antwortheadern der Ressource. 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

Parameter	Typ	Beschreibung
script	String	Der Name des Skripts. Unterstützte Skripts sind 'ANALYTICS', 'GTAG' und 'GTM'. Mit der Option 'ANALYTICS' wird das Google Analytics-Script von https://www.google-analytics.com/analytics.js abgerufen. Mit der Option 'GTAG' wird das Script für das allgemeine Website-Tag (gtag.js) von https://www.googletagmanager.com/gtag/js abgerufen. Mit der Option 'GTM' wird das Google Tag Manager-Script von https://www.googletagmanager.com/gtm.js abgerufen.
options	Gegenstand	Optionale Anfrageoptionen. Unten finden Sie die unterstützten Optionen.

Optionen

Option	Typ	Beschreibung
id	String	Gilt für 'GTAG' mit der gtag-Mess-ID und 'GTM' mit der Webcontainer-ID (z. B. GTM-XXXX).
debug	Beliebig	Wenn „truthy“, wird die Debug-Version des Mess-Scripts angefordert und zurückgegeben.
timeout	number	Das Zeitlimit für Anfragen in Millisekunden. Nicht positive Werte werden ignoriert. Wenn für die Anfrage ein Zeitlimit überschritten wird, wird der Callback mit undefined für den Skriptwert und {} für das Metadatenobjekt aufgerufen.

Nicht erkannte Optionsschlüssel werden ignoriert.

Verknüpfte Berechtigungen

Erfordert die Berechtigung send_http. Die Berechtigung muss so konfiguriert sein, dass mindestens der Zugriff auf Folgendes möglich ist:

• Google Domains zulassen

---

getRemoteAddress

Gibt eine String-Darstellung 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 nach besten Kräften, die ursprüngliche IP-Adresse 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 möglich ist:

• Header 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, falls vorhanden, andernfalls undefined. Wenn der Header wiederholt wird, werden die zurückgegebenen Werte mit ', ' zusammengefügt.

Beispiel

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Syntax

getRequestHeader(headerName);

Parameter

Parameter	Typ	Beschreibung
headerName	String	Der Name des Headers. Bei diesem Wert wird die Groß- und Kleinschreibung nicht berücksichtigt.

Verknüpfte Berechtigungen

read_request

---

getRequestMethod

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

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 Servercontainer-URL-Präfix aus dem Pfad. Wenn die Servercontainer-URL beispielsweise https://example.com/analytics und der Anfragepfad '/analytics/foo' ist, 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 Query-String-Parameters als string zurück oder undefined, wenn der Parameter nicht vorhanden ist. Wenn der Parameter im Suchstring wiederholt wird, wird der erste Wert zurückgegeben, der im Suchstring erscheint.

Beispiel

const getRequestQueryParameter = require('getRequestQueryParameter');

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

Syntax

getRequestQueryParameter(name);

Parameter

Parameter	Typ	Beschreibung
name	String	Der Name des Suchparameters.

Verknüpfte Berechtigungen

read_request

---

getRequestQueryParameters

Gibt die Abfrageparameter der eingehenden HTTP-Anfrage als Objekt zurück, das Abfrageparameternamen den entsprechenden Wert oder die entsprechenden Werte 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 Anfrage 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. Bevorzugen Sie getTimestampMillis.

Gibt eine Zahl zurück, die die aktuelle Zeit in Millisekunden seit der Unix-Epoche darstellt, 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 darstellt, 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.

Eingabetyp	Rückgabewert
String	'string'
number	'number'
boolean	'boolean'
Null	'null'
undefined	'undefined'
Array	'array'
Objekt	'object'
Funktion	'function'

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

Parameter	Typ	Beschreibung
value	Beliebig	Eingabewert.

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

Parameter	Typ	Beschreibung
data	String	Die Daten, mit denen der HMAC-Wert berechnet werden soll.
keyId	String	Eine Schlüssel-ID aus der JSON-Schlüsseldatei, die auf den zu verwendenden Schlüssel verweist.
options	Gegenstand	Optionale API-Konfiguration. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Option	Typ	Beschreibung
outputEncoding	String	Gibt das Codierungsformat für den Rückgabewert an. Unterstützte Formate sind hex, base64 und base64url. Wenn keine Angabe gemacht wird, ist der Standardwert base64url.

Verknüpfte Berechtigungen

use_custom_private_keys

Mindestversion des Images

1.0.0

---

isRequestMpv1

Gibt true zurück, wenn die eingehende Anfrage eine Measurement Protocol V1-Anfrage ist, andernfalls false.

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 die eingehende Anfrage eine Measurement Protocol V2-Anfrage ist, andernfalls false.

Beispiel

const isRequestMpv2 = require('isRequestMpv2');

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

Syntax

isRequestMpv2();

Verknüpfte Berechtigungen

Keine.

---

logToConsole

Gibt das oder die Argumente in der Konsole aus.

Diese Logs sind in der Google Cloud Console im Log-Explorer 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 verwendet ein oder mehrere Argumente, die bei Bedarf in einen String konvertiert und in der Konsole protokolliert werden.

Verknüpfte Berechtigungen

logging

---

makeInteger

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

Syntax

makeInteger(value);

Parameter

Parameter	Typ	Beschreibung
value	Beliebiger Typ	Der Wert, der konvertiert werden soll.

Verknüpfte Berechtigungen

Keine.

---

makeNumber

Wandelt den angegebenen Wert in eine Zahl um.

Syntax

makeNumber(value);

Parameter

Parameter	Typ	Beschreibung
value	Beliebiger Typ	Der Wert, der konvertiert werden soll.

Verknüpfte Berechtigungen

Keine.

---

makeString

Gibt den angegebenen Wert als String zurück.

Syntax

makeString(value);

Parameter

Parameter	Typ	Beschreibung
value	Beliebiger Typ	Der Wert, der konvertiert werden soll.

Verknüpfte Berechtigungen

Keine.

---

makeTableMap

Wandelt ein einfaches Tabellenobjekt mit zwei Spalten in ein Map um. Damit wird ein SIMPLE_TABLE-Vorlagenfeld mit zwei Spalten in ein übersichtlicheres Format geändert.

Mit dieser Funktion könnte 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 konvertierten Map-Schlüssel/Wert-Paare wurden hinzugefügt. Andernfalls wird null zurückgegeben.

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName);

Parameter

Parameter	Typ	Beschreibung
tableObj	Liste	Das zu konvertierende Tabellenobjekt. Es ist eine Liste von Karten, wobei jedes Map eine Zeile in der Tabelle darstellt. Jeder Attributname in einem Zeilenobjekt ist der Spaltenname und der Attributwert ist der Spaltenwert in der Zeile.
keyColumnName	String	Name der Spalte, deren Werte zu Schlüsseln im konvertierten Map werden.
valueColumnName	String	Name der Spalte, deren Werte zu Werten in der konvertierten Map werden.

Verknüpfte Berechtigungen

Keine.

---

parseUrl

Gibt ein Objekt zurück, das alle Komponenten einer bestimmten URL enthält, ähnlich dem 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 ein leeres Objekt.

Das zurückgegebene Objekt hat 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:[e-mail]:8080/foo?param=val%2Cue#bar');

Syntax

parseUrl(url);

Parameter

Parameter	Typ	Beschreibung
url	String	Die vollständige URL, die geparst wird.

Verknüpfte Berechtigungen

Keine.

---

returnResponse

Leert die Antwort, die zuvor von anderen Vorlagen mit den APIs festgelegt wurde, die die Antwort ändern, einschließlich setCookie, setPixelResponse, setResponseBody, setResponseHeader und setResponseStatus. Standardmäßig wird der HTTP-Statuscode 200, ein leerer Text und keine Header zurückgegeben.

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

Syntax

returnResponse();

Beispiel

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. Verwenden Sie bindToEvent, um eine API im Kontext des Ereignisses auszuführen. Weitere Informationen finden Sie im Beispiel für 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

Parameter	Typ	Beschreibung
event	Gegenstand	Die Ereignisparameter.
onComplete	Funktion	Ein Callback, der aufgerufen wird, nachdem alle Tags ausgelöst wurden.
onStart	Funktion	Ein Callback, der unmittelbar vor dem Auslösen der Tags aufgerufen wird.

Verknüpfte Berechtigungen

run_container

---

sendEventToGoogleAnalytics

Sendet ein einzelnes Ereignis mit Common Event Data an Google Analytics und gibt ein Promise zurück, das in ein Objekt mit dem Schlüssel location aufgelöst wird oder in ein Objekt mit dem Schlüssel reason abgelehnt wird. Das Ziel, Google Analytics 4, basiert auf der Mess-ID in den Ereignisdaten.

Das Feld location wird 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

Parameter	Typ	Beschreibung
event	Gegenstand	Das Ereignis im Unified Schema-Format.

Verknüpfte Berechtigungen

Erfordert die Berechtigung send_http. Die Berechtigung muss so konfiguriert sein, dass mindestens der Zugriff auf Folgendes möglich ist:

• Google Domains zulassen

---

sendHttpGet

Stellt eine HTTP-GET-Anfrage an die angegebene URL und gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird, sobald die Anfrage abgeschlossen ist oder ein Zeitlimit überschritten wird.

Das aufgelöste Ergebnis ist ein Objekt mit drei Schlüsseln: statusCode, headers und body. Wenn die Anfrage fehlschlägt (z.B. ungültige URL, keine Route zum Host, SSL-Aushandlungsfehler usw.), wird das Promise mit {reason: 'failed'} abgelehnt. Wenn die Option timeout festgelegt wurde und bei der Anfrage eine Zeitüberschreitung aufgetreten ist, wird das Promise mit {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

Parameter	Typ	Beschreibung
url	String	Die angeforderte URL.
options	Gegenstand	Optionale Anfrageoptionen. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Option	Typ	Beschreibung
headers	String	Zusätzliche Anfrageheader.
timeout	number	Das Zeitlimit in Millisekunden, bevor die Anfrage abgebrochen wird. Die Standardeinstellung ist 15000.
authorization	Gegenstand	Optionales Autorisierungsobjekt aus dem Aufruf von getGoogleAuth zum Einbeziehen von Autorisierungsheadern beim Senden von Anfragen an googleapis.com.

Verknüpfte Berechtigungen

send_http

---

sendHttpRequest

Sendet eine HTTP-Anfrage an die angegebene URL und gibt ein Promise zurück, das mit der Antwort aufgelöst wird, sobald die Anfrage abgeschlossen ist oder das Zeitlimit überschritten wurde.

Das aufgelöste Ergebnis ist ein Objekt mit drei Schlüsseln: statusCode, headers und body. Wenn die Anfrage fehlschlägt (z.B. ungültige URL, keine Route zum Host, SSL-Aushandlungsfehler usw.), wird das Promise mit {reason: 'failed'} abgelehnt. Wenn die Option timeout festgelegt wurde und bei der Anfrage eine Zeitüberschreitung aufgetreten ist, wird das Promise mit {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

Parameter	Typ	Beschreibung
url	String	Die angeforderte URL.
options	Gegenstand	Optionale Anfrageoptionen. Weitere Informationen finden Sie unten unter Optionen.
body	String	Optionaler Anfragetext.

Optionen

Option	Typ	Beschreibung
headers	String	Zusätzliche Anfrageheader.
method	Gegenstand	Die Anfragemethode. Die Standardeinstellung ist GET.
timeout	number	Das Zeitlimit in Millisekunden, bevor die Anfrage abgebrochen wird. Die Standardeinstellung ist 15000.
authorization	Gegenstand	Optionales Autorisierungsobjekt aus dem Aufruf von getGoogleAuth zum Einbeziehen von Autorisierungsheadern beim Senden von Anfragen an googleapis.com.

Verknüpfte Berechtigungen

send_http

---

sendPixelFromBrowser

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

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

Beispiel:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

Syntax

sendPixelFromBrowser(url)

Parameter

Parameter	Typ	Beschreibung
url	String	Die URL, die an den Browser gesendet werden soll.

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 Cookie, mit dem es erstellt wurde, festgelegt und ihm ein Ablaufwert zugewiesen werden, der in der Vergangenheit liegt, z.B. "Thu, 01 Jan 1970 00:00:00 GMT".

Beachten Sie, dass returnResponse aufgerufen werden muss, 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

Parameter	Typ	Beschreibung
name	String	Der Name des Cookies. Bei dem Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
value	String	Der Cookie-Wert.
options	Gegenstand	Optionale Cookie-Attribute:domain, expires, fallbackDomain, httpOnly, max-age, path, secure und sameSite. Weitere Informationen finden Sie unten unter Optionen.
noEncode	boolean	Bei „true“ wird der Cookiewert nicht codiert. Die Standardeinstellung ist false.

Optionen

• domain:Der Host, an den das Cookie gesendet werden soll. 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 UTC-formatierter Datumsstring sein, z.B. „Sat, 26 Oct 1985 08:21:00 GMT“. Wenn sowohl expires als auch max-age festgelegt sind, hat max-age Vorrang.

• httpOnly: Verbietet JavaScript den Zugriff auf das Cookie, wenn true.

• max-age: Anzahl der Sekunden bis zum Ablauf des Cookies. 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 Einstellung auf true gesetzt ist, wird das Cookie nur dann an den Server gesendet, wenn eine Anfrage von einem https:-Endpunkt erfolgt.

• sameSite: Gibt an, dass ein Cookie nicht mit ursprungsübergreifenden Anfragen gesendet werden darf. Muss 'strict', 'lax' oder 'none' sein.

Verknüpfte Berechtigungen

set_cookie

---

setPixelResponse

Legt den Antworttext auf ein 1×1-GIF fest, setzt den Content-Type-Header auf „image/gif“, legt Caching-Header so fest, dass User-Agents die Antwort nicht im Cache speichern, und setzt den Antwortstatus auf 200.

Beachten Sie, dass returnResponse aufgerufen werden muss, 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 möglich ist:

• headers – muss die folgenden Schlüssel zulassen:
  • content-type
  • cache-control
  • expires
  • pragma
• body
• status

---

setResponseBody

Legt den Antworttext auf das Argument fest.

Beachten Sie, dass returnResponse aufgerufen werden muss, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseBody(body[, encoding]);

Parameter

Parameter	Typ	Beschreibung
body	String	Der Wert, der als Antworttext festgelegt werden soll.
encoding	String	Die Zeichencodierung des Antworttexts (Standardwert: 'utf8'). Unterstützte Werte sind 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' und 'hex'.

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes möglich ist:

• body

---

setResponseHeader

Legt einen Header in der Antwort fest, die zurückgegeben wird. Wenn ein Header mit diesem Namen (unabhängig von der Groß-/Kleinschreibung) zuvor von dieser API festgelegt wurde, wird der vom vorherigen Aufrufer festgelegte Wert durch den letzten Aufruf überschrieben oder gelöscht.

Beachten Sie, dass returnResponse aufgerufen werden muss, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseHeader(name, value);

Parameter

Parameter	Typ	Beschreibung
name	String	Der Name des Headers. Bei HTTP-Header-Namen wird die Groß-/Kleinschreibung nicht berücksichtigt. Der Header-Name wird also in Kleinbuchstaben umgewandelt.
value	String undefined	Der Header-Wert. Wenn „null“ oder „undefined“, wird der benannte Header aus der zurückzugebenden Antwort entfernt.

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes möglich ist:

• headers

---

setResponseStatus

Legt den HTTP-Statuscode der Antwort fest, die zurückgegeben wird.

Beachten Sie, dass returnResponse aufgerufen werden muss, damit die Antwort an den Client zurückgesendet wird.

Syntax

setResponseStatus(statusCode);

Parameter

Parameter	Typ	Beschreibung
statusCode	number	Der zurückzugebende HTTP-Statuscode.

Verknüpfte Berechtigungen

Erfordert die Berechtigung access_response. Die Berechtigung muss so konfiguriert sein, dass der Zugriff auf mindestens Folgendes möglich ist:

• status

---

sha256

Berechnet den SHA-256-Digest der Eingabe und ruft einen Callback mit dem in Base64 codierten Digest auf, sofern im options-Objekt keine andere Ausgabecodierung angegeben ist.

Diese API-Signatur und dieses Verhalten entsprechen der sha256 API für Web-Container. Für benutzerdefinierte Vorlagen in Server-Containern sollte jedoch die sha256Sync API verwendet werden, da der Code dadurch einfacher wird.

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

Parameter	Typ	Beschreibung
input	String	Der zu hashende String.
onSuccess	Funktion	Wird mit dem resultierenden Digest aufgerufen, der in Base64 codiert ist, sofern im options-Objekt keine andere Ausgabecodierung angegeben ist.
options	Gegenstand	Optionales Optionenobjekt zum Angeben der Ausgabecodierung. Falls angegeben, sollte das Objekt den Schlüssel outputEncoding mit dem Wert base64 oder hex enthalten.

Verknüpfte Berechtigungen

Keine.

---

sha256Sync

Berechnet den SHA-256-Digest der Eingabe und gibt ihn als Base64-codierten Wert zurück, 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

Parameter	Typ	Beschreibung
input	String	Der zu hashende String.
options	Gegenstand	Optionales Optionenobjekt zum Angeben der Ausgabecodierung. Falls angegeben, sollte das Objekt den Schlüssel outputEncoding mit dem Wert base64 oder hex enthalten.

Verknüpfte Berechtigungen

Keine.

---

templateDataStorage

Gibt ein Objekt mit Methoden für den Zugriff auf den Vorlagendatenspeicher zurück. Durch die Speicherung von Vorlagendaten 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 im Vorlagendatenspeicher speichern, ist daher nicht garantiert, dass bei jeder nachfolgenden Anfrage auf die Daten zugegriffen werden kann.

Der Begriff „data“ im Namen „templateDataStorage“ bezieht sich darauf, dass mit dieser API nur einfache Datentypen ohne Funktionen gespeichert werden dürfen. Alle Funktionen oder Verweise auf Funktionen, die an die API übergeben werden, werden stattdessen als null gespeichert.

Hinweis:Anfragen aus dem Debug- oder Vorschaumodus oder aus dem Vorlageneditor haben Zugriff auf den Vorlagendatenspeicher, der leer initialisiert wird und nur für die Dauer der Anfrage bestehen bleibt, damit Debug- oder Testdaten nicht mit Produktionsdaten vermischt werden.

Hinweis:Im Gegensatz zur Web Storage API werden Daten in templateDataStorage nicht in Strings serialisiert bzw. deserialisiert.

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

Testet einen String anhand eines regulären Ausdrucks, 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 zustandsbehaftet. Weitere Informationen finden Sie in der RegExp.

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

Parameter	Typ	Beschreibung
regex	Objekt	Der reguläre Ausdruck, der getestet werden soll und von der createRegex API zurückgegeben wird.
string	String	Zu testender Teststring.

Verknüpfte Berechtigungen

Keine.

---

toBase64

Codiert einen String als Base64 oder Base64url. Die Standardeinstellung ist die Base64-Codierung.

Syntax

toBase64(input, options);

Parameter

Parameter	Typ	Beschreibung
input	String	Zu codierender String.
options	Gegenstand	Optionale API-Konfiguration. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Option	Typ	Beschreibung	Mindestversion
urlEncoding	boolean	Bei „true“ wird das Ergebnis im base64url-Format codiert.	1.0.0

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 Promise zurück, das bei erfolgreichem Einfügen aufgelöst oder bei einem Fehler abgelehnt wird.

Wenn das Einfügen erfolgreich ist, wird das Promise ohne Argumente aufgelöst.

Wenn das Einfügen fehlschlägt, wird das Promise mit einer Liste von Objekten abgelehnt, die den Fehlergrund und möglicherweise ein Zeilenobjekt enthalten, falls ein Fehler auftritt. Es ist möglich, dass ein Teil der Anfrage erfolgreich abgeschlossen wird, während andere Teile nicht abgeschlossen werden. Das Promise wird in diesem Fall mit einer Liste von Fehlern für jede Zeile mit einem Zeilenobjekt abgelehnt, um zu unterscheiden, welche Zeilen eingefügt wurden (siehe Fehlerbeispiele unten). Weitere Informationen finden Sie in der BigQuery-Dokumentation zu Fehlermeldungen.

Syntax

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

Parameter

Parameter	Typ	Beschreibung
connectionInfo	Gegenstand	Definiert die Informationen, die für die Verbindung zu einer BigQuery-Tabelle erforderlich sind. Es gibt einen optionalen und zwei erforderliche Parameter: projectId: Optionale Google Cloud-Projekt-ID. Wenn nichts angegeben ist, wird projectId aus der Umgebungsvariable GOOGLE_CLOUD_PROJECT abgerufen, sofern die Berechtigungseinstellung access_bigquery für die Projekt-ID auf * oder GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn der Servercontainer in Google Cloud ausgeführt wird, ist GOOGLE_CLOUD_PROJECT bereits auf die ID des Google Cloud-Projekts festgelegt. datasetId: BigQuery-Dataset-ID. tableId: BigQuery-Tabellen-ID.
rows	Array	Die Zeilen, die in die Tabelle eingefügt werden sollen.
options	Gegenstand	Optionale Anfrageoptionen. Die unterstützten Optionen sind: ignoreUnknownValues und skipInvalidRows. Unbekannte Optionsschlüssel werden ignoriert. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Parameter	Typ	Beschreibung
ignoreUnknownValues	boolean	Wenn der Wert auf true gesetzt ist, werden Zeilen akzeptiert, die Werte enthalten, die nicht mit dem Schema übereinstimmen. Die unbekannten Werte werden ignoriert. Die Standardeinstellung ist false.
skipInvalidRows	boolean	Wenn true festgelegt ist, werden alle gültigen Zeilen einer Anfrage eingefügt, auch wenn ungültige Zeilen vorhanden sind. Die Standardeinstellung ist false.

Fehlerbeispiele

Ein Fehler vom Typ „Modul nicht gefunden“ bedeutet, dass in Ihrem Servercontainer wahrscheinlich eine ältere Version unseres Images ausgeführt wird, in der das BigQuery-Modul noch nicht enthalten war. Stellen Sie Ihren Servercontainer mit denselben Einstellungen noch einmal mit unserem Bereitstellungsskript bereit. Das Modul wird automatisch eingefügt, sobald der Vorgang abgeschlossen ist.

Bei einem Fehler, der nicht mit dem Einfügen zusammenhängt, gibt es in der Regel ein Fehlerobjekt mit dem Schlüssel reason:

[{reason: 'invalid'}]

Ein Einfügefehler kann mehrere Fehlerobjekte mit einem errors-Array und einem row-Objekt enthalten. Das folgende Beispiel zeigt eine Fehlerantwort beim Einfügen von zwei Zeilen, von denen nur eine 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 Promise mit einem Objekt abgelehnt, das einen reason-Schlüssel mit dem Wert not_found enthält.

Hinweis :Standardmäßig speichert Firestore.read die Antwort für die Dauer der Containerausführung im Cache. Informationen zum Deaktivieren des Caching finden Sie unten im Abschnitt Optionen. Das Caching wird während einer Transaktion automatisch deaktiviert.

Syntax

Firestore.read(path[, options]);

Parameter

Parameter	Typ	Beschreibung
path	String	Der Pfad zum Dokument oder zur Sammlung. Darf nicht mit einem Schrägstrich (/) beginnen oder enden.
options	Gegenstand	Optionale Anfrageoptionen. Die unterstützten Optionen sind: projectId, disableCache und transaction. Unbekannte Optionsschlüssel werden ignoriert. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Parameter	Typ	Beschreibung
projectId	String	Optional: ID des Google Cloud Platform-Projekts Wenn nichts angegeben ist, wird die projectId aus der Umgebungsvariable GOOGLE_CLOUD_PROJECT abgerufen, sofern die Berechtigungseinstellung access_firestore für die Projekt-ID auf * oder GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn der Servercontainer in Google Cloud ausgeführt wird, ist GOOGLE_CLOUD_PROJECT bereits auf die ID des Google Cloud-Projekts festgelegt.
disableCache	boolean	Optional: Legt fest, ob der Cache deaktiviert werden soll. Das Caching ist standardmäßig aktiviert. Die Ergebnisse werden für die Dauer der Anfrage im Cache gespeichert.
transaction	String	Optional: Der Wert, der von Firestore.runTransaction() abgerufen wird. Markiert den Vorgang, der in einer Transaktion verwendet werden soll.

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. Verweist der Pfad auf eine Sammlung, wird ein Dokument mit einer zufällig generierten ID erstellt. Wenn der Pfad zu einem Dokument führt und dieses nicht vorhanden ist, wird es erstellt. Diese API gibt ein Promise zurück, das in die ID des hinzugefügten oder geänderten Dokuments aufgelöst wird. Wenn die Transaktionsoption verwendet wird, gibt die API weiterhin ein Promise zurück, enthält aber nicht die ID, da die Schreibvorgänge in Batches zusammengefasst werden.

Syntax

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

Parameter

Parameter	Typ	Beschreibung
path	String	Der Pfad zum Dokument oder zur Sammlung. Darf nicht mit einem Schrägstrich (/) beginnen oder enden.
input	Gegenstand	Der Wert, der in das Dokument geschrieben werden soll. Wenn die Zusammenführungsoption festgelegt ist, werden die Schlüssel aus der Eingabe in das Dokument zusammengeführt.
options	Gegenstand	Optionale Anfrageoptionen. Die unterstützten Optionen sind: projectId, merge und transaction. Unbekannte Optionsschlüssel werden ignoriert. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Parameter	Typ	Beschreibung
projectId	String	Optional: ID des Google Cloud Platform-Projekts Wenn nichts angegeben ist, wird die projectId aus der Umgebungsvariable GOOGLE_CLOUD_PROJECT abgerufen, sofern die Berechtigungseinstellung access_firestore für die Projekt-ID auf * oder GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn der Servercontainer in Google Cloud ausgeführt wird, ist GOOGLE_CLOUD_PROJECT bereits auf die ID des Google Cloud-Projekts festgelegt.
merge	boolean	Optional: Wenn true festgelegt ist, werden die Schlüssel aus der Eingabe in das Dokument eingefügt. Andernfalls wird das gesamte Dokument überschrieben. Die Standardeinstellung ist false.
transaction	String	Optional: Der Wert, der von Firestore.runTransaction() abgerufen wird. Markiert den Vorgang, der in einer Transaktion verwendet werden soll.

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 Promise zurück, das in ein Array von Firestore-Dokumenten aufgelöst wird, die den Abfragebedingungen entsprechen. Das Firestore-Dokumentobjekt ist dasselbe wie oben in Firestore.read aufgeführt. Wenn es keine Dokumente gibt, die den Abfragebedingungen entsprechen, wird das zurückgegebene Promise in ein leeres Array aufgelöst.

Hinweis :Standardmäßig speichert Firestore.query die Antwort für die Dauer der Containerausführung im Cache. Informationen zum Deaktivieren des Caching finden Sie unten im Abschnitt Optionen. Das Caching wird während einer Transaktion automatisch deaktiviert.

Hinweis: Firestore erstellt automatisch einen Index für jedes einzelne Feld. Wenn Sie mehrere Felder abfragen möchten, muss möglicherweise ein zusammengesetzter Index für die angegebene Sammlung erstellt werden. Weitere Informationen finden Sie in der Firestore-Dokumentation zu zusammengesetzten Indexen.

Syntax

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

Parameter

Parameter	Typ	Beschreibung
collection	String	Der Pfad zur Sammlung. Darf nicht mit einem Schrägstrich (/) beginnen oder enden.
queryConditions	Array	Ein Array von Abfragebedingungen. Jede Abfrage hat die Form eines Arrays mit drei Werten: key, operator und expectedValue. Beispiel: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. Die Bedingungen werden mit AND verknüpft, um das Abfrageergebnis zu erstellen. Eine Liste der kompatiblen Abfrageoperatoren finden Sie unter Abfrageoperatoren für Firestore.
options	Gegenstand	Optionale Anfrageoptionen. Die unterstützten Optionen sind: projectId, disableCache, limit und transaction. Unbekannte Optionsschlüssel werden ignoriert. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Parameter	Typ	Beschreibung
projectId	String	Optional: ID des Google Cloud Platform-Projekts Wenn nichts angegeben ist, wird die projectId aus der Umgebungsvariable GOOGLE_CLOUD_PROJECT abgerufen, sofern die Berechtigungseinstellung access_firestore für die Projekt-ID auf * oder GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn der Servercontainer in Google Cloud ausgeführt wird, ist GOOGLE_CLOUD_PROJECT bereits auf die ID des Google Cloud-Projekts festgelegt.
disableCache	boolean	Optional: Legt fest, ob der Cache deaktiviert werden soll. Das Caching ist standardmäßig aktiviert. Die Ergebnisse werden für die Dauer der Anfrage im Cache gespeichert.
limit	number	Optional: Ändert die maximale Anzahl der Ergebnisse, die von der Abfrage zurückgegeben werden. Der Standardwert ist 5.
transaction	String	Optional: Der Wert, der von Firestore.runTransaction() abgerufen wird. Markiert den Vorgang, der in einer Transaktion verwendet werden soll.

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 kann der Nutzer atomar aus Firestore lesen und in Firestore schreiben. Wenn ein gleichzeitiger Schreibvorgang oder ein anderer Transaktionskonflikt auftritt, wird die Transaktion bis zu zweimal wiederholt. Wenn der Vorgang nach insgesamt drei Versuchen fehlschlägt, wird er von der API mit einem Fehler abgelehnt. Diese API gibt ein Promise zurück, das bei erfolgreicher Transaktion in ein Array von Dokument-IDs für jeden Schreibvorgang aufgelöst wird und bei einem Fehler mit dem Fehler abgelehnt wird.

Syntax

Firestore.runTransaction(callback[, options]);

Parameter

Parameter	Typ	Beschreibung
callback	Funktion	Ein Callback, der mit einer String-Transaktions-ID aufgerufen wird. Die Transaktions-ID kann an API-Aufrufe zum Lesen, Schreiben und Abfragen übergeben werden. Diese Callback-Funktion muss ein Promise zurückgeben. Der Callback kann bis zu dreimal ausgeführt werden, bevor er fehlschlägt.
options	Gegenstand	Optionale Anfrageoptionen. Die einzige unterstützte Option ist projectId. Unbekannte Optionsschlüssel werden ignoriert. Weitere Informationen finden Sie unten unter Optionen.

Optionen

Parameter	Typ	Beschreibung
projectId	String	Optional: ID des Google Cloud Platform-Projekts Wenn nichts angegeben ist, wird die projectId aus der Umgebungsvariable GOOGLE_CLOUD_PROJECT abgerufen, sofern die Berechtigungseinstellung access_firestore für die Projekt-ID auf * oder GOOGLE_CLOUD_PROJECT festgelegt ist. Wenn der Servercontainer in Google Cloud ausgeführt wird, ist GOOGLE_CLOUD_PROJECT bereits auf die ID des Google Cloud-Projekts festgelegt.

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

Die Fehlerursachen können unter anderem Firestore REST API-Fehlercodes enthalten.

Verknüpfte Berechtigungen

access_firestore

---

JSON

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

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

Die Funktion stringify() konvertiert die Eingabe in einen JSON-String. Wenn der Wert nicht geparst 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, das Math-Funktionen bereitstellt.

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

Verknüpfte Berechtigungen

Keine.

---

Messages

Die folgenden APIs ermöglichen die Übergabe von Nachrichten zwischen verschiedenen Teilen eines Containers.

---

addMessageListener

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

1. messageType:string
2. message:Object

Wenn das Callback in einem Client hinzugefügt wird, empfängt es Nachrichten für alle Ereignisse, die von diesem Client erstellt werden. Wenn der Callback nur Nachrichten von einem bestimmten Ereignis empfangen soll, binden Sie diese API mit bindToEvent in der onStart-Funktion der runContainer API an das Ereignis. Sehen Sie sich das Beispiel an.

Syntax

const addMessageListener = require('addMessageListener');

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

Parameter

Parameter	Typ	Beschreibung
messageType	String	Der Nachrichtentyp, auf den gewartet werden soll. Wenn der Wert kein String ist, wird er in einen String umgewandelt.
callback	Funktion	Der Callback, der ausgeführt werden soll, wenn eine Nachricht des entsprechenden Nachrichtentyps gesendet wird. Wenn der Callback keine Funktion ist, führt die API keine Aktion aus.

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 Nachrichtenlistener 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. Damit können Nachrichten von einem Tag zurück an den Client gesendet werden, auf dem der Container ausgeführt wurde.

Syntax

const sendMessage = require('sendMessage');

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

Parameter

Parameter	Typ	Beschreibung
messageType	String	Der Nachrichtentyp, der gesendet werden soll. Wenn der Wert kein String ist, wird er in einen String umgewandelt.
message	Gegenstand	Die zu sendende Nachricht. Wenn die Nachricht kein Objekt ist, führt die API keine Aktion aus.

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 Methode keys() bietet das Standardbibliotheksverhalten von Object.keys(). Es wird ein Array mit den eigenen aufzählbareren Property-Namen eines bestimmten Objekts in derselben Reihenfolge zurückgegeben, die auch eine for...in...-Schleife verwenden würde. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode values() bietet das Verhalten der Standardbibliothek Object.values(). Es wird ein Array mit den eigenen aufzählbareren Attributwerten eines bestimmten Objekts in derselben Reihenfolge zurückgegeben, die eine for...in...-Schleife hätte. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode entries() bietet das Verhalten der Standardbibliothek Object.entries(). Es wird ein Array mit den eigenen aufzählbareren Property-[key, value]-Paaren eines bestimmten Objekts in derselben Reihenfolge zurückgegeben wie bei einer for...in...-Schleife. Wenn der Eingabewert kein Objekt ist, wird er in ein Objekt umgewandelt.

Die Methode freeze() bietet das Verhalten der Standardbibliothek Object.freeze(). Ein eingefrorenes Objekt kann nicht mehr geändert werden. Durch das Einfrieren eines Objekts wird verhindert, dass neue Attribute hinzugefügt, vorhandene Attribute entfernt und die Werte vorhandener Attribute geändert werden. freeze() gibt dasselbe Objekt zurück, das übergeben wurde. Ein primitives oder Null-Argument wird so 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, sofern das Objekt nicht eingefroren ist. Wie der Delete-Operator 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 Schlüssel angibt, der nicht vorhanden ist. In allen anderen Fällen wird false zurückgegeben. Sie unterscheidet sich jedoch in folgenden Punkten vom Standardbibliotheksoperator „delete“:

• 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 Bereich entfernt werden.

Syntax

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

Parameter

Object.keys

Parameter	Typ	Beschreibung
objectInput	Beliebig	Das Objekt, dessen Schlüssel aufgelistet werden sollen. Wenn die Eingabe kein Objekt ist, wird sie in ein Objekt umgewandelt.

Object.values

Parameter	Typ	Beschreibung
objectInput	Beliebig	Das Objekt, dessen Werte aufgelistet werden sollen. Wenn die Eingabe kein Objekt ist, wird sie in ein Objekt umgewandelt.

Object.entries

Parameter	Typ	Beschreibung
objectInput	Beliebig	Das Objekt, dessen Schlüssel/Wert-Paare aufgelistet werden sollen. Wenn die Eingabe kein Objekt ist, wird sie in ein Objekt umgewandelt.

Object.freeze

Parameter	Typ	Beschreibung
objectInput	Beliebig	Das einzufrierende Objekt. Wenn die Eingabe kein Objekt ist, wird sie als eingefrorenes Objekt behandelt.

Object.delete

Parameter	Typ	Beschreibung
objectInput	Beliebig	Das Objekt, dessen Schlüssel gelöscht werden soll.
keyToDelete	String	Der zu löschende Schlüssel der obersten Ebene.

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 für die Interaktion mit Promises bereitstellt.

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

• .then() – Bearbeitet sowohl die gelösten als auch die abgelehnten Fälle. Es werden zwei Callbacks als Parameter verwendet: einer für den Erfolgsfall und einer für den Fehlerfall.
• .catch() – Behandelt nur die abgelehnten Fälle. Akzeptiert einen Callback als Parameter.
• .finally(): Ermöglicht das Ausführen von Code, unabhängig davon, ob das Promise aufgelöst oder abgelehnt wurde. Akzeptiert einen Callback als Parameter, der ohne Argument aufgerufen wird.

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

Hinweis :Ein Sandboxed JS-Promise läuft nach fünf Sekunden ab (wird abgelehnt), wenn es nicht aufgelöst wurde.

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 Promise 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

Parameter	Typ	Beschreibung
inputs	Array	Ein Array von Werten oder Promises. Wenn eine Eingabe kein Promise ist, wird sie so weitergegeben, als wäre sie der aufgelöste Wert eines Promise. Gibt einen Fehler aus, wenn die Eingabe kein Array ist.

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 Promise, das funktional einem JavaScript-Promise entspricht.

Syntax

Promise.create(resolver);

Parameter

Parameter	Typ	Beschreibung
resolver	Funktion	Eine Funktion, die mit zwei Funktionen aufgerufen wird: „resolve“ und „reject“. Das zurückgegebene Promise wird aufgelöst oder abgelehnt, wenn der entsprechende Parameter aufgerufen wird. Gibt einen Fehler aus, wenn „resolver“ keine Funktion ist.

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 funktionieren mit Sandboxed-JavaScript-Tests, um Tests für benutzerdefinierte Vorlagen in Google Tag Manager zu erstellen. Für diese Test-APIs ist keine require()-Erklärung erforderlich. [Weitere Informationen zu Tests benutzerdefinierter Vorlagen]

---

assertApi

Gibt ein Matcher-Objekt zurück, mit dem sich flüssig Zusicherungen für die angegebene API machen lassen.

Syntax

assertApi(apiName)

Parameter

Parameter	Typ	Beschreibung
apiName	String	Der Name der zu prüfenden API. Das ist derselbe String, der an require() übergeben wurde.

Abgleichsfunktionen

• 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 die [Truth]-Bibliothek von Google angelehnt. Es wird ein Objekt zurückgegeben, mit dem fließend Zusicherungen zum Wert eines Subjekts gemacht werden können. Bei einem Assertionsfehler wird der Test sofort beendet und als fehlgeschlagen markiert. Ein Fehler in einem Testlauf hat jedoch keine Auswirkungen auf andere Testläufe.

Syntax

assertThat(actual, opt_message)

Parameter

Parameter	Typ	Beschreibung
actual	Beliebig	Der Wert, der in den fließenden Prüfungen verwendet werden soll.
opt_message	String	Optionale Meldung, die ausgegeben werden soll, wenn die Assertion fehlschlägt.

Abgleichsfunktionen

Matcher	Beschreibung
isUndefined()	Gibt an, dass das Subjekt undefined ist.
isDefined()	Gibt an, dass das Subjekt nicht undefined ist.
isNull()	Gibt an, dass das Subjekt null ist.
isNotNull()	Gibt an, dass das Subjekt nicht null ist.
isFalse()	Gibt an, dass das Subjekt false ist.
isTrue()	Gibt an, dass das Subjekt true ist.
isFalsy()	Gibt an, dass das Subjekt falsch ist. Falsche Werte sind undefined, null, false, NaN, 0 und '' (leerer String).
isTruthy()	Bestätigt, dass das Subjekt wahr ist. Falsche Werte sind undefined, null, false, NaN, 0 und '' (leerer String).
isNaN()	Gibt an, dass das Subjekt der Wert „NaN“ ist.
isNotNaN()	Gibt an, dass das Subjekt ein beliebiger Wert außer NaN ist.
isInfinity()	Bestätigt, dass das Subjekt positiv oder negativ unendlich ist.
isNotInfinity()	Gibt an, dass das Subjekt ein beliebiger Wert außer „+Infinity“ oder „-Infinity“ ist.
isEqualTo(expected)	Prüft, ob das Subjekt dem angegebenen Wert entspricht. Dies ist ein Wertevergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isNotEqualTo(expected)	Prüft, ob das Subjekt nicht gleich dem angegebenen Wert ist. Es handelt sich um einen Wertevergleich, nicht um einen Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isAnyOf(...expected)	Gibt an, dass das Subjekt einem der angegebenen Werte entspricht. Es handelt sich um einen Wertevergleich, nicht um einen Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isNoneOf(...expected)	Gibt an, dass das Subjekt keinem der angegebenen Werte entspricht. Dies ist ein Wertevergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isStrictlyEqualTo(expected)	Prüft, ob das Subjekt exakt gleich (===) dem angegebenen Wert ist.
isNotStrictlyEqualTo(expected)	Gibt an, dass das Subjekt nicht genau gleich (!==) dem angegebenen Wert ist.
isGreaterThan(expected)	Gibt an, dass das Subjekt in einem geordneten Vergleich größer als (>) der angegebene Wert ist.
isGreaterThanOrEqualTo(expected)	Gibt an, dass das Subjekt in einem geordneten Vergleich größer oder gleich (>=) dem angegebenen Wert ist.
isLessThan(expected)	Gibt an, dass das Subjekt in einem geordneten Vergleich kleiner als (<) der angegebene Wert ist.
isLessThanOrEqualTo(expected)	Gibt an, dass das Subjekt in einem geordneten Vergleich kleiner oder gleich (<=) dem angegebenen Wert ist.
contains(...expected)	Prüft, ob das Subjekt ein Array oder ein String ist, das alle angegebenen Werte in beliebiger Reihenfolge enthält. Es handelt sich um einen Wertevergleich, nicht um einen Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
doesNotContain(...expected)	Gibt an, dass das Subjekt ein Array oder ein String ist, das/der keinen der angegebenen Werte enthält. Dies ist ein Wertevergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
containsExactly(...expected)	Prüft, ob das Subjekt ein Array ist, das alle angegebenen Werte in beliebiger Reihenfolge und keine anderen Werte enthält. Dies ist ein Wertevergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
doesNotContainExactly(...expected)	Gibt an, dass das Subjekt ein Array ist, das eine andere Menge von Werten als die angegebenen Werte in beliebiger Reihenfolge enthält. Dies ist ein Wertevergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
hasLength(expected)	Prüft, ob das Subjekt ein Array oder String mit der angegebenen Länge ist. Die Assertion schlägt immer fehl, wenn der Wert kein Array oder String ist.
isEmpty()	Gibt an, dass das Subjekt ein leeres Array oder ein leerer String ist (Länge = 0). Die Assertion schlägt immer fehl, wenn der Wert kein Array oder String ist.
isNotEmpty()	Gibt an, dass das Subjekt ein Array oder String ist, das nicht leer ist (Länge > 0). Die Assertion schlägt immer fehl, wenn der Wert kein Array oder String ist.
isArray()	Gibt an, dass der Typ des Subjekts ein Array ist.
isBoolean()	Gibt an, dass der Typ des Subjekts ein boolescher Wert ist.
isFunction()	Gibt an, dass der Typ des Subjekts eine Funktion ist.
isNumber()	Gibt an, dass der Typ des Subjekts eine Zahl ist.
isObject()	Gibt an, dass der Typ des Subjekts ein Objekt ist.
isString()	Gibt an, dass der Typ des Subjekts ein String ist.

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 sie angegeben wurde.

Syntax

fail(opt_message);

Parameter

Parameter	Typ	Beschreibung
opt_message	String	Optionaler Text für die Fehlermeldung.

Beispiel

fail('This test has failed.');

---

mock

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

Syntax

mock(apiName, returnValue);

Parameter

Parameter	Typ	Beschreibung
apiName	String	Der Name der API, die simuliert werden soll. Das ist derselbe String, der an require() übergeben wird.
returnValue	Beliebig	Der Wert, der für die API oder eine Funktion zurückgegeben werden soll, die anstelle der API aufgerufen wird. Wenn returnValue eine Funktion ist, wird diese Funktion anstelle der Sandboxed API aufgerufen. Wenn returnValue etwas anderes als eine Funktion ist, wird dieser Wert anstelle der Sandboxed API zurückgegeben.

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 Sandboxed APIs überschreiben, die ein Objekt zurückgeben. Die API kann im Vorlagencode verwendet werden, ist aber nur im Testmodus aktiv. Mocks werden vor jedem Test zurückgesetzt.

Syntax

mockObject(apiName, objectMock);

Parameter

Parameter	Typ	Beschreibung
apiName	String	Der Name der API, die simuliert werden soll. Das ist derselbe String, der an require() übergeben wird.
objectMock	Gegenstand	Der Wert, der für die API oder eine Funktion zurückgegeben werden soll, die anstelle der API aufgerufen wird. Muss ein Objekt sein.

Beispiele

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

---

runCode

Führt den Code für die Vorlage, d.h. den Inhalt des Tabs Code, in der aktuellen Testumgebung mit einem bestimmten Eingabedatenobjekt aus.

Syntax

runCode(data)

Parameter

Parameter	Typ	Beschreibung
data	Gegenstand	Das im Test zu verwendende Datenobjekt.

Rückgabewert

Gibt den Wert einer Variablen für Variablentemplates zurück. Für alle anderen Templatetypen wird undefined zurückgegeben.

Beispiel

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

---