APIs für benutzerdefinierte Vorlagen

Core-APIs

Diese APIs werden mit in einer Sandbox ausgeführtem JavaScript verwendet, um benutzerdefinierte Vorlagen in Google Tag Manager zu erstellen. Jede API wird mit einer require()-Anweisung hinzugefügt, z.B.:

const myAPI = require('myAPI');

addConsentListener

Registriert eine Listener-Funktion, die ausgeführt werden soll, 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“ in „erteilt“ oder von „erteilt“ in „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 sind dafür verantwortlich, dass ihr Code die entsprechende 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

Wenn ein Listener aufgerufen wird, werden ihm der Einwilligungstyp, der geändert wird, und der neue Wert dieses Einwilligungstyps übergeben:

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 Callback wird aufgerufen, wenn alle Tags für das Ereignis ausgeführt wurden oder wenn ein In-Page-Ereignis-Timeout erreicht wurde. Dem Callback werden zwei Werte übergeben: die ID des Containers, der die Funktion aufruft, und ein Objekt, das Informationen zum Ereignis enthält.

Syntax

addEventCallback(callback)

Parameter

Das eventData-Objekt enthält die folgenden Daten:

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 erstellen (z.B. window.foo = window.bar), um bestimmte Tags zu unterstützen, für die ein Alias erforderlich ist. Weist den Wert im window-Objekt unter fromPath dem Schlüssel im window-Objekt unter toPath zu. Gibt true zurück, wenn erfolgreich, andernfalls false.

Syntax

aliasInWindow(toPath, fromPath)

Parameter

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 und für fromPath Lesezugriff erforderlich.

callInWindow

Ermöglicht es Ihnen, Funktionen über einen Pfad des window-Objekts auf richtlinienkonforme Weise aufzurufen. Ruft die Funktion am angegebenen Pfad in window mit den angegebenen Argumenten auf und gibt den Wert zurück. Wenn der Rückgabetyp nicht direkt einem in Sandboxed JavaScript unterstützten Typ zugeordnet werden kann, wird undefined zurückgegeben. Die acht in Sandboxed JavaScript unterstützten Typen 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

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

copyFromDataLayer

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

Syntax

copyFromDataLayer(key[, dataLayerVersion])

Parameter

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 in Sandboxed JavaScript unterstützten Typen sind null, undefined, boolean, number, string, Array, Object und function. Gibt den abgerufenen (und erzwungenen) Wert zurück.

Syntax

copyFromWindow(key)

Parameter

Verknüpfte Berechtigungen

access_globals

createArgumentsQueue

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

Erstellt eine Funktion im globalen Bereich (d. h. window) mit dem fnKey-Argument (gleiche Semantik wie createQueue). Nachdem die Funktion erstellt wurde, wird mit dieser API ein Array in window erstellt (falls es noch nicht vorhanden ist). Dazu wird das arrayKey-Argument verwendet.

Wenn die unter fnKey erstellte Funktion aufgerufen wird, wird ihr „arguments“-Objekt 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 ist die Einstellung „Lesen und Schreiben“ für fnKey und arrayKey in der Berechtigung access_globals erforderlich.

Beispiel:

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

Syntax

createArgumentsQueue(fnKey, arrayKey)

Parameter

Verknüpfte Berechtigungen

access_globals

createQueue

Erstellt ein Array in window (falls es noch nicht vorhanden ist) und gibt eine Funktion zurück, mit der Werte in dieses Array eingefügt werden.

Für diese Funktion ist die Einstellung „Lesen und Schreiben“ für arrayKey in der Berechtigung access_globals erforderlich.

Beispiel:

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

Syntax

createQueue(arrayKey)

Parameter

Verknüpfte Berechtigungen

access_globals

decodeUri

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

Beispiel:

const decode = require('decodeUri');

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

Syntax

decodeUri(encoded_uri)

Parameter

Verknüpfte Berechtigungen

Keine.

decodeUriComponent

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

Beispiel:

const decode = require('decodeUriComponent');

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

Syntax

decodeUriComponent(encoded_uri_component)

Parameter

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 bereitgestellten String als URI codiert darstellt. Gibt undefined zurück, wenn eine ungültige Eingabe (ein einzelnes Ersatzzeichen) angegeben wird.

Beispiel:

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

Syntax

encodeUri(uri)

Parameter

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

Beispiel:

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

Syntax

encodeUriComponent(str)

Parameter

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

Syntax

fromBase64(base64EncodedString)

Parameter

Beispiel

const fromBase64 = require('fromBase64');

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

Verknüpfte Berechtigungen

Keine

generateRandom

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

Syntax

generateRandom(min, max)

Parameter

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

Verknüpfte Berechtigungen

read_container_data

getCookieValues

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

Syntax

getCookieValues(name[, decode])

Parameter

Verknüpfte Berechtigungen

get_cookies

getQueryParameters

Gibt den ersten oder alle Parameter für die 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

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

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

getReferrerQueryParameters

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

Syntax

getReferrerQueryParameters(queryKey[, retrieveAll])

Parameter

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

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

Verknüpfte Berechtigungen

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

getReferrerUrl

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

Syntax

getReferrerUrl([component])

Parameter

Verknüpfte Berechtigungen

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

getTimestamp

Veraltet. getTimestampMillis wird bevorzugt.

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

Syntax

getType(data.someField)

Hinweise

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

Verknüpfte Berechtigungen

Keine.

getUrl

Gibt einen String zurück, der die gesamte oder einen Teil der aktuellen URL darstellt, wenn ein Komponententyp und einige Konfigurationsparameter angegeben werden.

Syntax

getUrl(component)

Parameter

Verknüpfte Berechtigungen

get_url

gtagSet

Sendet einen gtag-Set-Befehl an die Datenschicht, der so schnell wie möglich verarbeitet werden soll, nachdem das aktuelle Ereignis und alle davon ausgelösten Tags verarbeitet wurden (oder das Zeitlimit für die Tag-Verarbeitung erreicht ist). Das Update wird garantiert in diesem Container verarbeitet, bevor Elemente in der Warteschlange der Datenschicht verarbeitet werden.

Wenn die Funktion beispielsweise von einem Tag aufgerufen wird, das bei der Initialisierung der Einwilligung ausgelöst wird, wird die Aktualisierung angewendet, bevor das Initialisierungsereignis verarbeitet wird. Beispiele: ads_data_redaction ist auf true oder false gesetzt oder url_passthrough ist auf true oder false gesetzt.

Beispiele:

const gtagSet = require('gtagSet');

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

Syntax

gtagSet(object)

Parameter

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 vereinfachten Schlüssel in diesem Objekt, z.B. für gtagSet({foo: {bar: 'baz'}}), prüft die API die Schreibberechtigung für foo.bar.

Wenn die Eingabe für gtagSet ein Schlüssel und ein Wert ist, der kein einfaches Objekt ist, prüft die API, ob eine Schreibberechtigung für diesen Schlüssel vorhanden ist. Für gtagSet('abc', true) prüft die API beispielsweise, ob eine Schreibberechtigung für 'abc' vorhanden ist.

Wenn das Eingabeobjekt einen Zyklus enthält, werden nur Schlüssel vor dem Erreichen desselben Objekts geprüft.

injectHiddenIframe

Fügt der Seite einen unsichtbaren iFrame hinzu.

Callbacks werden als Funktionsinstanzen angegeben und in JavaScript-Funktionen eingeschlossen, die sie aufrufen.

Syntax

injectHiddenIframe(url, onSuccess)

Parameter

Verknüpfte Berechtigungen

inject_hidden_iframe

injectScript

Fügt der Seite ein Script-Tag hinzu, um die angegebene URL asynchron zu laden. Die Callbacks werden als Funktionsinstanzen übergeben und in JavaScript-Funktionen eingeschlossen, die sie aufrufen.

Syntax

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

Parameter

Verknüpfte Berechtigungen

inject_script

isConsentGranted

Gibt „true“ zurück, wenn die angegebene Einwilligung erteilt wurde.

Die Einwilligung für einen bestimmten Einwilligungstyp gilt als erteilt, wenn der Einwilligungstyp auf „Erteilt“ festgelegt oder gar nicht festgelegt wurde. Wenn der Einwilligungstyp auf einen anderen Wert festgelegt ist, gilt die Einwilligung als nicht erteilt.

In der Tag Manager-Benutzeroberfläche für Tag-Einstellungen wird eine Option zum Festlegen der Auslösung angeboten. Wenn ein Tag, für das „Immer auslösen“ aktiviert ist, diese API verwendet, wird die Einwilligung als erteilt betrachtet und true zurückgegeben, unabhängig vom tatsächlichen Einwilligungsstatus.

Beispiel:

const isConsentGranted = require('isConsentGranted');

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

Syntax

isConsentGranted(consentType)

Parameter

Verknüpfte Berechtigungen

access_consent-Berechtigung mit Lesezugriff für den Einwilligungstyp.

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.

Syntax

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

Parameter

JSON.parse

JSON.stringify

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

Argumente werden in der Browserkonsole protokolliert.

Syntax

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

Parameter

Verknüpfte Berechtigungen

logging

makeInteger

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

Syntax

makeInteger(value)

Parameter

Verknüpfte Berechtigungen

Keine.

makeNumber

Wandelt den angegebenen Wert in eine Zahl um.

Syntax

makeNumber(value)

Parameter

Verknüpfte Berechtigungen

Keine.

makeString

Gibt den angegebenen Wert als String zurück.

Syntax

makeString(value)

Parameter

Verknüpfte Berechtigungen

Keine.

makeTableMap

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

Syntax

makeTableMap(tableObj, keyColumnName, valueColumnName)

Parameter

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

Die Parameter von mathematischen Funktionen werden in Zahlen konvertiert.

Verknüpfte Berechtigungen

Keine.

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 wie bei einer 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(). Gibt ein Array mit den eigenen aufzählbar Attributwerten eines bestimmten Objekts in derselben Reihenfolge zurück, die eine for...in...-Schleife verwenden würde. 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ählbar definierten 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 Eigenschaften hinzugefügt, vorhandene Eigenschaften entfernt oder die Werte vorhandener Eigenschaften 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 den 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

Object.values

Object.entries

Object.freeze

Object.delete

Beispiel

const Object = require('Object');

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

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

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

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

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

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 eines leeren Strings 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:xyz@example.com:8080/foo?param=val%2Cue#bar');

Syntax

parseUrl(url);

Parameter

Verknüpfte Berechtigungen

Keine.

queryPermission

Zulässige und eingeschränkte Berechtigungen abfragen Gibt einen booleschen Wert zurück: true, wenn eine Berechtigung erteilt wurde, andernfalls false.

Syntax

queryPermission(permission, functionArgs*)

Parameter

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

readAnalyticsStorage

Ruft die für Analytics gespeicherten Daten ab und gibt ein Objekt mit client_id und sessions zurück.

• client_id: Ein String, der die für die Analyse verwendete Client-ID darstellt.
• sessions: Ein Array von Objekten mit Informationen zu aktuellen Sitzungen. Jedes Objekt enthält:
  • measurement_id: Ein String, der die Mess-ID des Analytics-Zielvorhabens darstellt.
  • session_id: Ein String, der den Zeitstempel darstellt, der die aktuelle Sitzung kennzeichnet.
  • session_number: Eine Zahl, die die Anzahl der Sitzungen angibt, die ein Nutzer bis zur aktuellen Sitzung gestartet hat.

Syntax

const readAnalyticsStorage = require('readAnalyticsStorage');

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

readAnalyticsStorage(cookieOptions);

Parameter

Verknüpfte Berechtigungen

read_analytics_storage

Beispiel

const readAnalyticsStorage = require('readAnalyticsStorage');

const analyticsStorageData = readAnalyticsStorage();

sendOfflineEvent(analyticsStorageData.client_id, "tutorial_begin");

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

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

Verknüpfte Berechtigungen

send_pixel

setCookie

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

Syntax

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

Parameter

Optionen

• Domain:wird durch die Property options['domain'] festgelegt, sofern vorhanden. Legen Sie diesen Wert auf 'auto' fest, um zu versuchen, das Cookie mit der breitestmöglichen Domain zu schreiben, die auf dem Speicherort des Dokuments basiert. Wenn das fehlschlägt, werden nacheinander immer kleinere Unterdomains ausprobiert. Wenn alle diese Versuche fehlschlagen, 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 Dokumentstandorts fest.
• Pfad:wird von options['path'] festgelegt, sofern vorhanden. Wenn ein Cookie ohne angegebenen Pfad in document.cookie geschrieben wird, legt der User-Agent den Pfad des Cookies standardmäßig auf den Pfad des aktuellen Dokuments fest.
• Max-Age:Wird von options['max-age'] festgelegt, sofern vorhanden.
• Läuft ab am:Wird von options['expires'] festgelegt, falls vorhanden. Falls vorhanden, muss dies ein UTC-formatierter Datumsstring sein. Mit Date.toUTCString() kann ein Date für diesen Parameter formatiert werden.
• Secure:wird von options['secure'] festgelegt, falls vorhanden.
• SameSite:wird von options['samesite'] festgelegt, sofern vorhanden.

Verknüpfte Berechtigungen

set_cookies

setDefaultConsentState

Sendet ein Standard-Update der Einwilligung an die Datenschicht, das so schnell wie möglich nach dem aktuellen Ereignis und allen Tags, die dadurch ausgelöst wurden, verarbeitet wird (oder wenn das Zeitlimit für die Tag-Verarbeitung erreicht ist). Das Update wird garantiert in diesem Container verarbeitet, bevor alle in der Datenschicht in die Warteschlange eingereihten Elemente verarbeitet werden. 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

Das consentSettings-Objekt ist eine Zuordnung von beliebigen Strings für Einwilligungstypen zu 'granted' oder 'denied'. Folgende Werte werden unterstützt:

Verknüpfte Berechtigungen

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

setInWindow

Legt den angegebenen Wert in window für den angegebenen Schlüssel fest. Standardmäßig wird mit dieser Methode kein Wert in window festgelegt, wenn bereits ein Wert vorhanden ist. Setzen Sie overrideExisting auf true, 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

Verknüpfte Berechtigungen

access_globals

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.

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

Verknüpfte Berechtigungen

Keine.

templateStorage

Gibt ein Objekt mit Methoden für den Zugriff auf den Vorlagenspeicher zurück. Mit der Vorlagenspeicherung können Daten für mehrere Ausführungen einer einzelnen Vorlage freigegeben werden. Daten, die im Vorlagenspeicher gespeichert sind, 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

Beispiel

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

Verknüpfte Berechtigungen

Keine

updateConsentState

Sendet eine Einwilligungsaktualisierung an die Datenschicht, die so schnell wie möglich verarbeitet werden soll, nachdem das aktuelle Ereignis und alle Tags, die dadurch ausgelöst wurden, verarbeitet wurden (oder das Zeitlimit für die Tag-Verarbeitung erreicht ist). Das Update wird garantiert in diesem Container verarbeitet, bevor alle in der Datenschicht in die Warteschlange gestellten Elemente verarbeitet werden. Weitere Informationen zur Einwilligung

Beispiel:

const updateConsentState = require('updateConsentState');

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

Syntax

updateConsentState(consentSettings)

Parameter

Das consentSettings-Objekt ist eine Zuordnung von beliebigen Strings für Einwilligungstypen zu 'granted' oder 'denied'. Folgende Werte werden unterstützt:

Verknüpfte Berechtigungen

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

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 auf flüssige Weise Zusicherungen für die angegebene API gemacht werden können.

Syntax

assertApi(apiName)

Parameter

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 sich fließend Behauptungen über den Wert eines Subjekts aufstellen lassen. Bei einem Assertionsfehler wird der Test sofort beendet und als fehlgeschlagen markiert. Ein Fehler in einem Test hat jedoch keine Auswirkungen auf andere Testläufe.

Syntax

assertThat(actual, opt_message)

Parameter

Abgleichsfunktionen

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

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

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

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

Rückgabewert

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

Beispiel

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