APIs für benutzerdefinierte Vorlagen

Haupt-APIs

Bei diesen APIs wird JavaScript in einer Sandbox eingesetzt, um im Google Tag Manager benutzerdefinierte Vorlagen zu erstellen. Jede API wird mit einer require()-Anweisung hinzugefügt. Beispiel:

const myAPI = require('myAPI');

addConsentListener

Registriert eine Listenerfunktion, die ausgeführt wird, wenn sich der Status des angegebenen Einwilligungstyps ändert.

Der angegebene Listener wird jedes Mal aufgerufen, wenn sich der Status für den angegebenen Einwilligungstyp von „Abgelehnt“ zu „Gewährt“ oder von „Gewährt“ zu „Abgelehnt“ ändert. Ein Einwilligungstyp ohne Status gilt als erteilt. Der Listener wird also nicht aufgerufen, wenn ein nicht festgelegter Einwilligungstyp auf „erteilt“ aktualisiert wird. Listener-Funktionen sorgen dafür, dass der Code die richtige Anzahl von Malen ausgeführt wird.

Beispiel:

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

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

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

Syntax

addConsentListener(consentType, listener)

Parameter

Parameter Typ Beschreibung
consentType String Die Einwilligungsart, für die auf Statusänderungen gewartet werden soll.
listener Funktion Die Funktion, die ausgeführt werden soll, wenn sich der Status der angegebenen Einwilligungsart ändert.

Wenn ein Listener aufgerufen wird, werden die zu ändernde Einwilligungsart und der neue Wert dieser Einwilligungsart übergeben:

Parameter Typ Beschreibung
consentType String Die Einwilligungsart, die geändert wird.
granted boolesch Ein boolescher Wert, der „true“ ist, wenn die angegebene Einwilligungsart in „Erteilt“ geändert wird.

Verknüpfte Berechtigungen

access_consent-Berechtigung mit Lesezugriff für den Einwilligungstyp.

addEventCallback

Mit der addEventCallback API können Sie eine Callback-Funktion registrieren, die am Ende eines Ereignisses aufgerufen wird. Der Rückruf wird aufgerufen, wenn alle Tags für das Ereignis ausgeführt wurden oder die Zeitüberschreitung für ein Ereignis auf der Seite erreicht wird. Dem Callback werden zwei Werte übergeben: die ID des Containers, der die Funktion aufruft, und ein Objekt mit Informationen zum Ereignis.

Syntax

addEventCallback(callback)

Parameter

Parameter Typ Beschreibung
callback Funktion Die am Ende des Ereignisses aufzurufende Funktion.

Das eventData-Objekt enthält die folgenden Daten:

Schlüsselname Typ Beschreibung
tags Array Ein Array von Tag-Datenobjekten. Jedes Tag, das während des Ereignisses ausgelöst wurde, hat einen Eintrag in diesem Array. Das Tag-Datenobjekt enthält die ID (id), den Ausführungsstatus (status) und die Ausführungszeit (executionTime) des Tags. Außerdem sind darin zusätzliche Tag-Metadaten enthalten, die für das Tag konfiguriert wurden.

Beispiel

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

Verknüpfte Berechtigungen

read_event_metadata

aliasInWindow

Mit der aliasInWindow API können Sie einen Alias (z.B. window.foo = window.bar) erstellen, um bestimmte Tags zu unterstützen, für die Aliasing erforderlich ist. Der Wert im window-Objekt unter fromPath wird dem Schlüssel im window-Objekt unter toPath zugewiesen. Gibt true zurück, wenn erfolgreich, ansonsten false.

Syntax

aliasInWindow(toPath, fromPath)

Parameter

Parameter Typ Beschreibung
toPath String Ein durch Punkte getrennter Pfad in das window-Objekt, in das ein Wert kopiert werden soll. Alle Komponenten im Pfad bis zur letzten Komponente müssen bereits im window-Objekt vorhanden sein.
fromPath String Ein durch Punkte getrennter Pfad in window zum zu kopierenden Wert. Wenn der Wert nicht vorhanden ist, schlägt der Vorgang fehl.

Beispiel

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

Verknüpfte Berechtigungen

access_globals ist sowohl für toPath als auch für fromPath erforderlich. Für toPath ist Schreibzugriff, für fromPath Lesezugriff erforderlich.

callInWindow

Damit können Sie richtliniengesteuert Funktionen über einen Pfad außerhalb des window-Objekts aufrufen. Ruft die Funktion unter dem angegebenen Pfad in window mit den angegebenen Argumenten auf und gibt den Wert zurück. Wenn der Rückgabetyp nicht direkt einem in JavaScript-Sandboxes unterstützten Typ zugeordnet werden kann, wird undefined zurückgegeben. Die acht Typen, die in JavaScript-Sandboxes unterstützt werden, sind null, undefined, boolean, number, string, Array, Object und function. Wenn der angegebene Pfad nicht vorhanden ist oder nicht auf eine Funktion verweist, wird undefined zurückgegeben.

Syntax

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

Parameter

Parameter Typ Beschreibung
pathToFunction String Ein durch Punkte getrennter Pfad zur Funktion in window, die aufgerufen werden soll.
args * Argumente, die an die Funktion übergeben werden sollen.

Verknüpfte Berechtigungen

access_globals mit aktivierter Berechtigung execute.

callLater

Plant einen asynchronen Aufruf einer Funktion. Die Funktion wird aufgerufen, nachdem der aktuelle Code zurückgegeben wurde. Dies entspricht setTimeout(<function>, 0).

Syntax

callLater(function)

Parameter

Parameter Typ Beschreibung
function Funktion Die aufzurufende Funktion.

copyFromDataLayer

Gibt den Wert zurück, der dem angegebenen Schlüssel in der Datenebene derzeit zugewiesen ist: den Wert, der unter dem angegebenen Schlüssel gefunden wird, wenn es sich um einen primitiven Typ, eine Funktion oder ein Objektliteral handelt, andernfalls undefined.

Syntax

copyFromDataLayer(key[, dataLayerVersion])

Parameter

Parameter Typ Beschreibung
key String Der Schlüssel im Format „a.b.c“.
dataLayerVersion number Die optionale Version der Datenschicht. Der Standardwert liegt bei 2. Es wird dringend davon abgeraten, den Wert 1 zu verwenden.

Verknüpfte Berechtigungen

read_data_layer

copyFromWindow

Kopiert eine Variable aus dem window-Objekt. Wenn der Wert in window nicht direkt einem in sandboxed JavaScript unterstützten Typ zugeordnet werden kann, wird undefined zurückgegeben. Die acht Typen, die in JavaScript-Sandboxes unterstützt werden, sind null, undefined, boolean, number, string, Array, Object und function. Gibt den abgerufenen (und erzwungenen) Wert zurück.

Syntax

copyFromWindow(key)

Parameter

Parameter Typ Beschreibung
key String Der Schlüssel in window, dessen Wert kopiert werden soll.

Verknüpfte Berechtigungen

access_globals

createArgumentsQueue

Erstellt eine Warteschlange, die mit Argumentobjekten gefüllt wird, um Tag-Lösungen zu unterstützen, für die dies erforderlich ist.

Erstellt eine globale Funktion (d.h. window) mit dem Argument fnKey (dieselbe Semantik wie createQueue). Nachdem die Funktion erstellt wurde, erstellt diese API mit dem Argument arrayKey ein Array in window (falls noch nicht vorhanden).

Wenn die unter fnKey erstellte Funktion aufgerufen wird, wird ihr Argumentobjekt in das unter arrayKey erstellte Array eingefügt. Der Rückgabewert der API ist die Funktion, die unter fnKey erstellt wurde.

Für diese Funktion sind die Lese- und Schreibeinstellungen für fnKey und arrayKey für die access_globals-Berechtigung erforderlich.

Beispiel:

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

Syntax

createArgumentsQueue(fnKey, arrayKey)

Parameter

Parameter Typ Beschreibung
fnKey String Der Pfad in window, unter dem die Funktion festgelegt ist, falls er noch nicht vorhanden ist. Dieses Argument unterstützt die Standardpunktschreibweise. Wenn der Pfad des Schlüssels nicht vorhanden ist, wird eine Ausnahme ausgelöst. Das heißt, wenn fnKey den Wert 'one.two' hat, wird eine Ausnahme ausgelöst.
arrayKey String Der Pfad in window, unter dem das Array festgelegt ist, falls er noch nicht vorhanden ist. Dieses Argument unterstützt die Standardpunktschreibweise. Wenn der Pfad des Schlüssels nicht vorhanden ist, wird eine Ausnahme ausgelöst. Wenn also arrayKey = 'one.two' ist und kein globales Objekt mit dem Namen 'one' vorhanden ist, wird eine Ausnahme ausgelöst.

Verknüpfte Berechtigungen

access_globals

createQueue

Erstellt ein Array in window, sofern es noch nicht vorhanden ist, und gibt eine Funktion zurück, die Werte in dieses Array überträgt.

Für diese Funktion ist die Lese- und Schreibeinstellung für arrayKey auf die Berechtigung access_globals erforderlich.

Beispiel:

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

Syntax

createQueue(arrayKey)

Parameter

Parameter Typ Beschreibung
arrayKey String Der Schlüssel in window, für den das Array festgelegt ist, falls noch nicht vorhanden. Dieses Argument unterstützt die Standardpunktschreibweise. Wenn der Pfad des Schlüssels nicht vorhanden ist, wird eine Ausnahme ausgelöst. Beispiel: Wenn arrayKey den Wert 'one.two' hat und kein globales Objekt mit dem Namen 'one' vorhanden ist, wird eine Ausnahme ausgelöst.

Verknüpfte Berechtigungen

access_globals

decodeUri

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

Beispiel:

const decode = require('decodeUri');

const decodedUrl = decode(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 vorliegt.

Beispiel:

const decode = require('decodeUriComponent');

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

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 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. Gibt undefined zurück, wenn eine ungültige Eingabe (ein einzelner Substitut) bereitgestellt wird.

Beispiel:

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

Syntax

encodeUri(uri)

Parameter

Parameter Typ Beschreibung
uri String Einen vollständigen URI.

Zugehörige 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. Gibt undefined zurück, wenn eine ungültige Eingabe (ein einzelner Substitut) bereitgestellt wird.

Beispiel:

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

Syntax

encodeUriComponent(str)

Parameter

Parameter Typ Beschreibung
str String Eine Komponente eines URI.

Verknüpfte Berechtigungen

Keine.

fromBase64

Mit der fromBase64 API können Sie Strings aus ihrer Base64-Darstellung decodieren. Gibt undefined zurück, wenn eine ungültige Eingabe vorliegt.

Syntax

fromBase64(base64EncodedString)

Parameter

Parameter Typ Beschreibung
base64EncodedString String Base64-codierter String.

Beispiel

const fromBase64 = require('fromBase64');

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

Zugehörige Berechtigungen

Keine

generateRandom

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

Syntax

generateRandom(min, max)

Parameter

Parameter Typ Beschreibung
min number Minimaler potenzieller Wert der zurückgegebenen Ganzzahl.
max number Maximaler potenzieller Wert der zurückgegebenen Ganzzahl.

Verknüpfte Berechtigungen

Keine.

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 sendPixel = require('sendPixel');

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

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

Syntax

getContainerVersion();

Zugehörige Berechtigungen

read_container_data

getCookieValues

Gibt die Werte aller Cookies mit dem angegebenen Namen zurück.

Syntax

getCookieValues(name[, decode])

Parameter

Parameter Typ Beschreibung
name String Name des Cookies.
decode Boolescher Wert Legt fest, ob die Cookiewerte mit dem decodeURIComponent() von JavaScript decodiert werden sollen. Die Standardeinstellung ist true.

Verknüpfte Berechtigungen

get_cookies

getQueryParameters

Gibt den ersten oder alle Parameter für queryKey der aktuellen URL zurück. Gibt den ersten Wert aus queryKey oder ein Array von Werten aus queryKey zurück.

Syntax

getQueryParameters(queryKey[, retrieveAll])

Parameter

Parameter Typ Beschreibung
queryKey String Der Schlüssel, der aus den Abfrageparametern gelesen werden soll.
retrieveAll boolesch Gibt an, ob alle Werte abgerufen werden sollen.

Wenn die aktuelle URL beispielsweise https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo lautet, gilt Folgendes:

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

Verknüpfte Berechtigungen

Für get_url muss die Komponente query zugelassen sein und queryKey muss in den zulässigen Abfrageschlüsseln angegeben sein (oder ein beliebiger Abfrageschlüssel).

getReferrerQueryParameters

Die getReferrerQueryParameters API funktioniert genauso wie getQueryParameters, nur dass sie auf den Referrer anstelle der aktuellen URL angewendet wird. Gibt den ersten oder alle Parameter für die queryKey des angegebenen Verweisquellen-Eintrags zurück. Gibt den ersten Wert aus queryKey oder ein Array von Werten aus queryKey zurück.

Syntax

getReferrerQueryParameters(queryKey[, retrieveAll])

Parameter

Parameter Typ Beschreibung
queryKey String Der Schlüssel, der aus den Abfrageparametern gelesen werden soll.
retrieveAll boolesch Ob alle Werte abgerufen werden sollen.

Wenn die Verweis-URL beispielsweise https://example.com/path?var=foo&var1=foo1&var=foo2&var=foo lautet, dann gilt:

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

Verknüpfte Berechtigungen

get_referrer muss die Komponente query zulassen und queryKey in den zulässigen Abfrageschlüsseln angeben (oder einen beliebigen Abfrageschlüssel zulassen).

getReferrerUrl

Bei einem bestimmten Komponententyp liest die API das Dokumentobjekt nach der Verweis-URL und gibt einen String zurück, der einen Teil der Verweis-URL darstellt. Wenn keine Komponente angegeben ist, wird die vollständige Verweis-URL zurückgegeben.

Syntax

getReferrerUrl([component])

Parameter

Parameter Typ Beschreibung
component String Die Komponente, die aus der URL zurückgegeben werden soll. Folgende Werte sind möglich: protocol, host, port, path, query oder extension. Wenn component undefined oder null ist oder nicht mit einer dieser Komponenten übereinstimmt, wird die gesamte URL zurückgegeben.

Verknüpfte Berechtigungen

get_referrer muss die Komponente query zulassen und queryKey in den zulässigen Abfrageschlüsseln angeben (oder einen beliebigen Abfrageschlüssel zulassen).

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. Im Gegensatz zu typeof unterscheidet getType zwischen array und object.

Syntax

getType(data.someField)

Hinweise

In der folgenden Tabelle sind die Strings aufgeführt, die für jeden Eingabewert zurückgegeben werden.

Eingabewert Ergebnis
undefined 'undefined'
null „null“
true „boolean“
12 'number'
'string' "string"
{ a: 3 } 'object'
[ 1, 3 ] „Array“
(x) => x + 1 „function“

Zugehörige Berechtigungen

Keine.

getUrl

Gibt einen String zurück, der die gesamte oder einen Teil der aktuellen URL darstellt, unter Angabe eines Komponententyps und einiger Konfigurationsparameter.

Syntax

getUrl(component)

Parameter

Parameter Typ Beschreibung
component String Die Komponente, die aus der URL zurückgegeben werden soll. Es muss sich um einen dieser Algorithmen handeln: protocol, host, port, path, query, extension oder fragment. Wenn „component“ undefined oder null ist oder nicht mit einer dieser Komponenten übereinstimmt, wird der gesamte href-Wert zurückgegeben.

Verknüpfte Berechtigungen

get_url

gtagSet

Es wird ein gtag-set-Befehl an die Datenschicht gesendet, der so bald wie möglich verarbeitet wird, nachdem die Verarbeitung des aktuellen Ereignisses und aller ausgelösten Tags abgeschlossen ist (oder die Zeitüberschreitung für die Tag-Verarbeitung erreicht wurde). Die Aktualisierung wird in diesem Container garantiert vor den Elementen in der Datenschicht und vor den Elementen in der Warteschlange verarbeitet.

Wenn es beispielsweise von einem Tag aufgerufen wird, das bei Initialisierung der Einwilligung ausgelöst wird, wird das Update angewendet, bevor das Initialisierungsereignis verarbeitet wird. Beispiele hierfür sind ads_data_redaction auf true oder false oder url_passthrough auf true oder false.

Beispiele:

const gtagSet = require('gtagSet');

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

Syntax

gtagSet(object)

Parameter

Parameter Typ Beschreibung
Object Gegenstand Ein Objekt, das den globalen Status für die enthaltenen Properties aktualisiert.

Verknüpfte Berechtigungen

write_data_layer prüft die Schreibberechtigung für dataLayer für alle angegebenen Schlüssel. Wenn die Eingabe für gtagSet ein einfaches Objekt ist, prüft die API die Schreibberechtigung für alle flachen Schlüssel in diesem Objekt. Bei gtagSet({foo: {bar: 'baz'}}) prüft die API beispielsweise die Schreibberechtigung für foo.bar.

Wenn die Eingabe für gtagSet ein Schlüssel und ein nicht einfacher Objektwert ist, prüft die API, ob eine Schreibberechtigung für diesen Schlüssel vorhanden ist. Bei gtagSet('abc', true) prüft die API beispielsweise, ob eine Schreibberechtigung für 'abc' vorhanden ist.

Wenn sich im Eingabeobjekt ein Zyklus befindet, werden nur Schlüssel geprüft, die vor dem Erreichen desselben Objekts liegen.

injectHiddenIframe

Fügen Sie der Seite einen unsichtbaren iFrame hinzu.

Callbacks werden als Funktionsinstanzen angegeben und in JavaScript-Funktionen eingebunden, die diese aufrufen.

Syntax

injectHiddenIframe(url, onSuccess)

Parameter

Parameter Typ Beschreibung
url String Die URL, die als Wert des Attributs src des Iframes verwendet werden soll.
onSuccess Funktion Wird aufgerufen, wenn der Frame erfolgreich geladen wurde.

Zugehörige Berechtigungen

inject_hidden_iframe

injectScript

Fügen Sie der Seite ein Script-Tag hinzu, um die angegebene URL asynchron zu laden. Die Callbacks werden als Funktionsinstanzen angegeben und sind in JavaScript-Funktionen eingebunden, die diese aufrufen.

Syntax

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

Parameter

Parameter Typ Beschreibung
url String Die Adresse des einzuschleusenden Scripts.
onSuccess Funktion Wird aufgerufen, wenn das Script erfolgreich geladen wurde.
onFailure Funktion Wird aufgerufen, wenn das Skript nicht geladen werden kann.
cacheToken String Optionaler String, der angibt, dass die angegebene URL im Cache gespeichert werden soll. Wenn dieser Wert angegeben ist, wird nur ein Script-Element erstellt, um das JavaScript anzufordern. Bei weiteren Ladeversuchen werden die angegebenen onSuccess- und onFailure-Methoden in die Warteschlange gestellt, bis das Script geladen ist.

Verknüpfte Berechtigungen

inject_script

isConsentGranted

Gibt „true“ zurück, wenn die Einwilligung des angegebenen Typs erteilt wurde.

Die Einwilligung für einen bestimmten Einwilligungstyp gilt als erteilt, wenn der Einwilligungstyp auf „erteilt“ festgelegt wurde oder gar nicht festgelegt wurde. Ist für die Einwilligungsart ein anderer Wert festgelegt, gilt das als nicht erteilt.

In den Tag-Einstellungen in Tag Manager gibt es eine Option, mit der das Tag immer ausgelöst werden kann. Wenn diese API in einem Tag verwendet wird, bei dem die Option „Immer auslösen“ aktiviert ist, wird die Einwilligung als erteilt betrachtet und true wird zurückgegeben, unabhängig vom tatsächlichen Einwilligungsstatus.

Beispiel:

const isConsentGranted = require('isConsentGranted');

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

Syntax

isConsentGranted(consentType)

Parameter

Parameter Typ Beschreibung
consentType String Der Einwilligungstyp, dessen Status geprüft werden soll.

Zugehörige Berechtigungen

access_consent-Berechtigung mit Lesezugriff für den Einwilligungstyp.

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 aufweist), gibt die Methode undefined zurück.

Syntax

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

Parameter

JSON.parse

Parameter Typ Beschreibung
stringInput Beliebig Der Wert, der konvertiert werden soll. Wenn der Wert kein String ist, wird die Eingabe in einen String umgewandelt.

JSON.stringify

Parameter Typ Beschreibung
Wert Beliebig Wert, der konvertiert werden soll.

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

localStorage

Gibt ein Objekt mit Methoden für den Zugriff auf den lokalen Speicher zurück.

Syntax

const localStorage = require('localStorage');

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

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

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

Verknüpfte Berechtigungen

access_local_storage

Beispiel

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

logToConsole

Protokolliert Argumente in der Browserkonsole.

Syntax

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

Parameter

Parameter Typ Beschreibung
obj1 [, obj2,... objN] Beliebig Argumente

Verknüpfte Berechtigungen

logging

makeInteger

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

Syntax

makeInteger(value)

Parameter

Parameter Typ Beschreibung
value Beliebig 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 Beliebig 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 Beliebig Der Wert, der konvertiert werden soll.

Verknüpfte Berechtigungen

Keine.

makeTableMap

Wandelt ein einfaches Tabellenobjekt mit zwei Spalten in ein 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, wenn ihr Schlüssel/Wert-Paare hinzugefügt wurden, andernfalls null.

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parameter

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

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 für mathematische Funktionen werden in Zahlen umgewandelt.

Verknüpfte Berechtigungen

Keine.

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 der Standardbibliothek Object.values(). 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. Sie gibt ein Array der eigenen aufzählbaren Attribut-[key, value]-Paare eines bestimmten Objekts in derselben Reihenfolge zurück wie eine for...in...-Schleife. Wenn der Eingabewert kein Objekt ist, wird er zu einem Objekt gezwungen.

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 Argument oder ein Null-Argument wird behandelt, als wäre es ein fixiertes 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

Parameter Typ Beschreibung
objectInput Beliebig Das Objekt, dessen Schlüssel aufgezählt 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 aufgezählt werden sollen. Wenn die Eingabe kein Objekt ist, wird sie in ein Objekt umgewandelt.

Object.entries

Parameter Typ Beschreibung
objectInput Beliebig 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 Objekt, das eingefroren werden soll. 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.

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 ein leeres Objekt.

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

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

Verknüpfte Berechtigungen

Keine.

queryPermission

Fragen Sie die zulässigen und eingegrenzten Berechtigungen ab. Gibt einen booleschen Wert zurück: true, wenn eine Berechtigung gewährt wird, andernfalls false.

Syntax

queryPermission(permission, functionArgs*)

Parameter

Parameter Typ Beschreibung
permission String Name der Berechtigung.
functionArgs Beliebig Funktionsargumente variieren je nach abgefragter Berechtigung. Weitere Informationen finden Sie unten im Abschnitt Funktionsargumente.

Funktionsargumente

sendPixel, injectScript, injectHiddenIframe: Der zweite Parameter sollte ein URL-String sein.

writeGlobals, readGlobals: Der zweite Parameter sollte der Schlüssel sein, der geschrieben oder gelesen wird.

readUrl: Es sind keine zusätzlichen Argumente erforderlich, um abzufragen, ob die gesamte URL gelesen werden kann. Wenn Sie prüfen möchten, ob eine bestimmte Komponente gelesen werden kann, übergeben Sie den Komponentennamen als zweites Argument:

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

Wenn Sie prüfen möchten, ob ein bestimmter Abfrageschlüssel lesbar ist, übergeben Sie ihn als dritten Parameter:

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

Verknüpfte Berechtigungen

Keine.

readCharacterSet

Gibt den Wert von document.characterSet zurück.

Syntax

readCharacterSet()

Parameter

Keine.

Verknüpfte Berechtigungen

read_character_set

readTitle

Gibt den Wert von document.title zurück.

Syntax

readTitle()

Parameter

Keine.

Verknüpfte Berechtigungen

read_title

require

Importiert eine integrierte Funktion anhand ihres Namens. Gibt eine Funktion oder ein Objekt zurück, das von Ihrem Programm aufgerufen werden kann. Gibt undefined zurück, wenn der Browser die integrierte Funktion nicht unterstützt.

Syntax

require(name)

Parameter

Parameter Typ Beschreibung
name String Der Name der zu importierenden Funktion.

Beispiel

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

Verknüpfte Berechtigungen

Keine.

sendPixel

Stellt eine GET-Anfrage an einen angegebenen URL-Endpunkt.

Syntax

sendPixel(url, onSuccess, onFailure)

Parameter

Parameter Typ Beschreibung
url String An wen soll Google Pixel gesendet werden?
onSuccess Funktion Wird aufgerufen, wenn das Pixel erfolgreich geladen wurde. Hinweis: Auch wenn die Anfrage erfolgreich gesendet wurde, benötigen Browser möglicherweise eine gültige Bildantwort, um onSuccess auszuführen.
onFailure Funktion Wird aufgerufen, wenn das Pixel nicht geladen werden kann. Hinweis: Auch wenn die Anfrage erfolgreich gesendet wurde, wird „onFailure“ möglicherweise ausgeführt, wenn der Server keine gültige Bildantwort zurückgibt.

Verknüpfte Berechtigungen

send_pixel

setCookie

Setzt oder löscht das Cookie mit dem angegebenen Namen, Wert und den angegebenen Optionen.

Syntax

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

Parameter

Parameter Typ Beschreibung
name String Name des Cookies.
value String Wert des Cookies.
options Gegenstand Gibt die Attribute Domain, Path, Expires, Max-Age, Secure und SameSite an. Weitere Informationen finden Sie unten im Abschnitt Optionen.
encode Boolescher Wert Steuert, ob der Cookiewert mit encodeURIComponent() von JavaScript codiert werden soll. Die Standardeinstellung ist true.

Optionen

  • Domain:Wird von der Property options['domain'] festgelegt, sofern vorhanden. Legen Sie diesen Wert auf 'auto' fest, um zu versuchen, das Cookie mit der breitestmöglichen Domain basierend auf dem Speicherort des Dokuments zu schreiben. Wenn das fehlschlägt, werden nacheinander immer engere Subdomains versucht. Wenn alle Probleme auftreten, wird versucht, das Cookie ohne Domain zu schreiben. Wenn kein Wert festgelegt ist, wird versucht, das Cookie ohne Angabe einer Domain zu schreiben. Hinweis: Wenn ein Cookie ohne angegebene Domain in document.cookie geschrieben wird, legt der User-Agent die Domain des Cookies standardmäßig auf den Host des aktuellen Dokumentspeicherorts fest.
  • Pfad: Wird durch options['path'] festgelegt, falls vorhanden. Wenn ein Cookie ohne Pfad in document.cookie geschrieben wird, setzt der User-Agent den Pfad des Cookies standardmäßig auf den Pfad des aktuellen Dokumentspeicherorts.
  • Max-Age:Wird von options['max-age'] festgelegt, sofern vorhanden.
  • Expires:Wird von options['expires'] festgelegt, sofern vorhanden. Falls vorhanden, muss dies ein Datumsstring im UTC-Format sein. Mit Date.toUTCString() kann ein Date für diesen Parameter formatiert werden.
  • Secure:Wird von options['secure'] festgelegt, sofern vorhanden.
  • SameSite:Wird von options['samesite'] festgelegt, sofern vorhanden.

Verknüpfte Berechtigungen

set_cookies

setDefaultConsentState

Sendet ein Standardupdate für die Einwilligung an die Datenschicht, das so schnell wie möglich nach dem aktuellen Ereignis und allen ausgelösten Tags verarbeitet wird (oder das Zeitlimit für die Tag-Verarbeitung erreicht wurde). Die Aktualisierung wird in diesem Container garantiert vor den Elementen in der Warteschlange in der Datenschicht verarbeitet. Weitere Informationen zur Einwilligung

Beispiel:

const setDefaultConsentState = require('setDefaultConsentState');

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

Syntax

setDefaultConsentState(consentSettings)

Parameter

Parameter Typ Beschreibung
consentSettings Gegenstand Ein Objekt, das den Standardstatus für die angegebenen Einwilligungsarten definiert.

Das consentSettings-Objekt ist eine Zuordnung beliebiger Strings für den Einwilligungstyp zu 'granted' oder 'denied'. Folgende Werte werden unterstützt:

Schlüsselname Typ Beschreibung
consentType String Der Wert für jede Einwilligungsart kann auf „gewährt“ oder „abgelehnt“ festgelegt werden. Alle anderen Werte als „gewährt“ werden als „abgelehnt“ behandelt. Wenn Sie den Wert auf „nicht definiert“ setzen, hat das keine Auswirkungen auf den vorherigen Wert.
region Array Optionale Regionskonten, die angeben, für welche Region die Einwilligungseinstellungen gelten. Regionscodes werden mit Ländern und/oder Untergliederungen im ISO 3166-2-Format angegeben.
wait_for_update number Gibt einen Millisekundenwert an, um zu steuern, wie lange auf das Senden von Daten gewartet werden soll. Wird mit Einwilligungstools verwendet, die asynchron geladen werden.

Verknüpfte Berechtigungen

access_consent-Berechtigung mit Schreibzugriff für alle Einwilligungsarten im Objekt „consentSettings“

setInWindow

Legt den angegebenen Wert in window unter dem angegebenen Schlüssel fest. Standardmäßig wird mit dieser Methode der Wert in window nicht festgelegt, wenn bereits ein Wert vorhanden ist. Legen Sie overrideExisting auf true fest, um den Wert in window festzulegen, unabhängig davon, ob bereits ein Wert vorhanden ist. Gibt einen booleschen Wert zurück: true, wenn der Wert erfolgreich festgelegt wurde, und false andernfalls.

Syntax

setInWindow(key, value, overrideExisting)

Parameter

Parameter Typ Beschreibung
key String Der Schlüssel in window, unter dem der Wert eingefügt werden soll.
value * Der Wert, der in window festgelegt werden soll.
overrideExisting boolesch Das Flag, das angibt, dass der Wert in window festgelegt werden soll, unabhängig davon, ob dort ein Wert vorhanden ist oder nicht.

Zugehörige Berechtigungen

access_globals

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.

Beispiel:

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

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

Syntax

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

Parameter

Parameter Typ Beschreibung
input String Der String, für den der Hash berechnet werden soll.
onSuccess Funktion Wird mit dem resultierenden Base64-codierten Hashwert aufgerufen, sofern im options-Objekt keine andere Ausgabecodierung angegeben ist.
onFailure Funktion Wird aufgerufen, wenn beim Berechnen des Digests ein Fehler auftritt oder der Browser keine native Unterstützung für SHA256 hat. Der Callback wird mit einem Objekt aufgerufen, das den Namen des Fehlers und die Meldung enthält.
options Gegenstand Optionales Optionsobjekt, um die Ausgabecodierung anzugeben. Falls angegeben, sollte das Objekt den Schlüssel outputEncoding mit dem Wert base64 oder hex enthalten.

Verknüpfte Berechtigungen

Keine.

templateStorage

Gibt ein Objekt mit Methoden zum Zugriff auf den Vorlagenspeicher zurück. Mit dem Vorlagenspeicher können Daten für mehrere Ausführungen einer einzelnen Vorlage freigegeben werden. Daten, die im Vorlagenspeicher gespeichert werden, bleiben für die gesamte Lebensdauer der Seite erhalten.

Syntax

const templateStorage = require('templateStorage');

templateStorage.getItem(key);

templateStorage.setItem(key, value);

templateStorage.removeItem(key);

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

Verknüpfte Berechtigungen

access_template_storage

Beispiel

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

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

templateStorage.setItem('alreadyRan', true);

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

toBase64

Mit der toBase64 API können Sie einen String in eine Base64-Darstellung codieren.

Syntax

toBase64(input)

Parameter

Parameter Typ Beschreibung
input String Zu codierender String.

Beispiel

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Zugehörige Berechtigungen

Keine

updateConsentState

Es wird eine Einwilligungsaktualisierung an die Datenebene gesendet, die so schnell wie möglich verarbeitet wird, nachdem die Verarbeitung des aktuellen Ereignisses und aller ausgelösten Tags abgeschlossen ist (oder die Zeitüberschreitung für die Tag-Verarbeitung erreicht wurde). Das Update wird garantiert in diesem Container vor allen Elementen in der Warteschlange in der Datenschicht verarbeitet. Weitere Informationen zur Einwilligung

Beispiel:

const updateConsentState = require('updateConsentState');

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

Syntax

updateConsentState(consentSettings)

Parameter

Parameter Typ Beschreibung
consentSettings Gegenstand Ein Objekt, das den Status für die angegebenen Einwilligungstypen aktualisiert.

Das consentSettings-Objekt ist eine Zuordnung beliebiger Strings für den Einwilligungstyp zu 'granted' oder 'denied'. Folgende Werte werden unterstützt:

Schlüsselname Typ Beschreibung
consentType String Der Wert für jede Einwilligungsart kann auf „erteilt“ oder „abgelehnt“ festgelegt werden. Alle anderen Werte als „granted“ (gewährt) werden als „denied“ (abgelehnt) behandelt. Wenn Sie den Wert auf „nicht definiert“ setzen, hat das keine Auswirkungen auf den vorherigen Wert.

Zugehörige Berechtigungen

access_consent mit Schreibzugriff für alle Einwilligungsarten im Objekt „consentSettings“.

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 in benutzerdefinierten Vorlagen

assertApi

Gibt ein Matcher-Objekt zurück, das verwendet werden kann, um Assertions für die angegebene API zu erstellen.

Syntax

assertApi(apiName)

Parameter

Parameter Typ Beschreibung
apiName String Der Name der zu prüfenden API. Es muss sich dabei um denselben String handeln, der an require() übergeben wurde.

Matcher

  • 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 der [Truth]-Bibliothek von Google nachempfunden. 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

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

Abgleichsmechanismen

Matcher Beschreibung
isUndefined() Es wird behauptet, dass das Subjekt undefined ist.
isDefined() Es wird behauptet, dass das Subjekt nicht undefined ist.
isNull() Es wird behauptet, dass das Subjekt null ist.
isNotNull() Es wird behauptet, dass das Subjekt nicht null ist.
isFalse() Es wird behauptet, dass das Subjekt false ist.
isTrue() Es wird behauptet, dass das Subjekt true ist.
isFalsy() Stellt fest, dass das Subjekt falsch ist. Falsch-Werte sind undefined, null, false, NaN, 0 und '' (leerer String).
isTruthy() Es wird behauptet, dass das Subjekt wahr ist. Falsche Werte sind undefined, null, false, NaN, 0 und ' (leerer String).
isNaN() Prüft, ob das Subjekt der Wert „NaN“ ist.
isNotNaN() Prüft, ob das Subjekt einen Wert hat, der nicht NaN ist.
isInfinity() Stellt fest, dass das Subjekt positiv oder negativ unendlich ist.
isNotInfinity() Erklärt, dass das Subjekt ein beliebiger Wert außer einem positiven oder negativen Unendlichkeitswert ist.
isEqualTo(expected) Prüft, ob das Subjekt dem angegebenen Wert entspricht. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isNotEqualTo(expected) Prüft, ob das Subjekt nicht mit dem angegebenen Wert übereinstimmt. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isAnyOf(...expected) Prüft, ob das Subjekt mit einem der angegebenen Werte übereinstimmt. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
isNoneOf(...expected) Prüft, ob das Subjekt keinem der angegebenen Werte entspricht. Dies ist ein Wertvergleich, kein Referenzvergleich. Die Inhalte von Objekten und Arrays werden rekursiv verglichen.
isStrictlyEqualTo(expected) Prüft, ob das Subjekt genau dem angegebenen Wert entspricht (===).
isNotStrictlyEqualTo(expected) Prüft, ob das Subjekt nicht genau (!==) mit dem angegebenen Wert übereinstimmt.
isGreaterThan(expected) Bestätigt, dass das Objekt in einem geordneten Vergleich größer als (>) des angegebenen Werts ist.
isGreaterThanOrEqualTo(expected) Prüft, ob das Subjekt größer oder gleich (>=) dem angegebenen Wert in einem geordneten Vergleich ist.
isLessThan(expected) Bestätigt, dass das Subjekt in einem geordneten Vergleich kleiner als (<) des angegebenen Werts ist.
isLessThanOrEqualTo(expected) Stellt sicher, dass das Subjekt bei einem geordneten Vergleich kleiner oder gleich (<=) dem angegebenen Wert ist.
contains(...expected) Prüft, ob das Subjekt ein Array oder String ist, das alle angegebenen Werte in beliebiger Reihenfolge enthält. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
doesNotContain(...expected) Prüft, ob das Subjekt ein Array oder String ist, das keinen der angegebenen Werte enthält. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
containsExactly(...expected) Bestätigt, dass das Subjekt ein Array ist, das alle gegebenen Werte in beliebiger Reihenfolge und keine anderen Werte enthält. Dies ist ein Wertvergleich, kein Referenzvergleich. Der Inhalt von Objekten und Arrays wird rekursiv verglichen.
doesNotContainExactly(...expected) Prüft, ob das Subjekt ein Array ist, das in beliebiger Reihenfolge andere Werte als die angegebenen enthält. Dies ist ein Wertvergleich, 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 Prüfung schlägt immer fehl, wenn der Wert kein Array oder String ist.
isEmpty() Prüft, ob das Subjekt ein leeres Array oder ein leerer String ist (Länge = 0). Die Prüfung schlägt immer fehl, wenn der Wert kein Array oder String ist.
isNotEmpty() Bestätigt, dass das Subjekt ein Array oder ein String ist, der nicht leer ist (Länge > 0). Die Prüfung schlägt immer fehl, wenn der Wert kein Array oder String ist.
isArray() Stellt fest, dass der Typ des Subjekts ein Array ist.
isBoolean() Prüft, ob der Typ des Subjekts ein boolescher Wert ist.
isFunction() Es wird behauptet, dass der Typ des Subjekts eine Funktion ist.
isNumber() Prüft, ob der Typ des Subjekts eine Zahl ist.
isObject() Stellt fest, dass der Typ des Subjekts ein Objekt ist.
isString() Prüft, ob 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 vorhanden.

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 APIs in Sandboxes überschreiben. Die Mock API kann im Vorlagencode sicher verwendet werden, ist aber nur im Testmodus betriebsbereit. Die Simulationen werden vor jedem Test zurückgesetzt.

Syntax

mock(apiName, returnValue);

Parameter

Parameter Typ Beschreibung
apiName String Der Name der zu mockenden API; entspricht dem String, der an require() übergeben wird.
returnValue Beliebig Der Wert, der für die API zurückgegeben werden soll, oder eine Funktion, die anstelle der API aufgerufen wird. Wenn returnValue eine Funktion ist, wird diese anstelle der Sandbox-API aufgerufen. Ist returnValue kein Funktionswert, wird dieser anstelle der Sandbox-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 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

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

Beispiele

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

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 Datenobjekt, das im Test verwendet werden soll.

Rückgabewert

Gibt den Wert einer Variablen für Variablenvorlagen zurück; für alle anderen Vorlagentypen wird undefined zurückgegeben.

Beispiel

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