Tutorial: Aus einem verschachtelten dataLayer haltbare GTM-Variablen bauen

Eine Datenschichtvariable in Google Tag Manager (GTM) kann eine Zahl, eine Zeichenkette, ein Objekt oder eine ganze Liste zurückgeben. Die Punktnotation wählt einen Wert aus verschachtelten Daten. Entscheidend ist der Unterschied zwischen Feldname und Listenposition: items.0 bezeichnet den ersten Eintrag, kein bestimmtes Produkt.

Haltbare Variablen brauchen eine dokumentierte Datenstruktur, vollständige Ereignisdaten und Prüfungen auf fehlende Werte. Ein Index eignet sich für eine ausdrücklich gemeinte Position; die Produktidentität braucht eine Kennung.

Ein vollständiges add_to_cart-Ereignis

Das Beispiel fügt in einer Aktion zwei Stühle und einen Tisch hinzu. Das Ereignis enthält diese neu hinzugefügten Artikel, nicht den gesamten bestehenden Warenkorb. Der Wert beträgt 64.95 × 2 + 219.00 × 1 = 348.90, ohne Versand und Steuern. Bei Angabe eines Wertes ist die Währung erforderlich.

window.dataLayer = window.dataLayer || [];
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    currency: "EUR",
    value: 348.90,
    items: [
      { item_id: "SKU-42", item_name: "Stuhl", price: 64.95, quantity: 2,
        item_category: "Moebel", index: 0 },
      { item_id: "SKU-77", item_name: "Tisch", price: 219.00, quantity: 1,
        item_category: "Moebel", index: 1 }
    ]
  },
  user: { logged_in: true, segment: "b2b" }
});

Die Initialisierung erhält eine vorhandene Warteschlange. Das Leeren von ecommerce verhindert alte Felder in diesem vollständigen Datensatz. Ereignisname und zugehörige Daten gehören in denselben Push. user.segment zeigt zusätzlichen Anwendungszustand; ein Push allein richtet noch keine GA4-Nutzereigenschaft ein.

Verschachtelte Felder mit Version 2 lesen

Eine Datenschichtvariable mit Anzeigename DLV - ecommerce.currency, Datenschichtvariablenname ecommerce.currency und Version 2 liefert EUR. Der Anzeigename ist frei wählbar; den Wert bestimmt der konfigurierte Pfad. Weitere Variablen können ecommerce.value, ecommerce.items und ecommerce lesen. Die letzten beiden liefern eine Liste beziehungsweise ein Objekt.

Version 1 behandelt Punkte als wörtliche Bestandteile eines Schlüssels. Version 2 interpretiert Punkte als Verschachtelung und kann auch gepunktete Schlüssel wie {"page.type":"pdp"} in eine verschachtelte Struktur auflösen. Ein gepunkteter Schlüssel verlangt daher nicht automatisch Version 1. Einheitliche verschachtelte Objekte vermeiden mehrdeutige Mischungen aus gepunkteten Schlüsseln und Objekteigenschaften.

Groß- und Kleinschreibung zählt. Ein fehlender Pfad ohne eingerichteten Standardwert liefert undefined. Die weitere Verarbeitung hängt vom Tag und davon ab, wie Werte in die ausgehende Anfrage umgewandelt werden: Ein Parameter kann entfallen oder umgewandelt werden; eigener Code kann auch fehlschlagen. Daraus folgt weder automatisch ein leerer Parameter noch eine bestimmte Berichtsdifferenz.

Position und Identität unterscheiden

Ein benannter Pfad bleibt nur bei passendem Schema und vorhandenen Ereignisdaten brauchbar. Ein Indexpfad bleibt richtig, wenn tatsächlich „der erste Artikel“ gemeint ist; nach einer Umsortierung steht an dieser Position ein anderes Produkt. Eine produktspezifische Suche verwendet item_id. Für GA4-E-Commerce eignet sich normalerweise die ganze Liste ecommerce.items. Bei bereits passendem Quellformat ist keine eigene Umwandlung nötig.

Nachrichtenliste und zusammengeführtes Modell

window.dataLayer ist eine Liste wartender Nachrichten. GTM verarbeitet die Nachrichten und führt ein internes Datenmodell. Version 2 kann Objekte und Listen auch auf tiefer verschachtelten Ebenen zusammenführen: Ausgelassene Felder oder hintere Listeneinträge können aus älteren Nachrichten erhalten bleiben. Eine kürzere Liste entfernt frühere Einträge deshalb nicht zuverlässig.

Googles GTM-Beispiele für E-Commerce leeren das bisherige Objekt mit dataLayer.push({ecommerce:null}), bevor ein vollständiges Ereignis folgt. Dieses Muster passt zum obigen Beispiel. Absichtlich über mehrere Nachrichten aufgebaute Zustände brauchen dagegen abgestimmte Rücksetzungen und vollständige Nutzdaten; blindes Leeren vor einem unvollständigen Datensatz kann benötigte Werte entfernen.

Optionale Prüfung ohne erfundene Standardwerte

Die folgende benutzerdefinierte JavaScript-Variable mit Namen JS - ecommerce valid liest eine Datenschichtvariable der Version 2 namens DLV - ecommerce. Die Funktion liefert einen Wahrheitswert und verändert die Quelle nicht.

Die Regeln dieses Beispiels sind bewusst streng: EUR, numerische nichtnegative Preise und Werte, positive ganzzahlige Mengen sowie mindestens eine nichtleere Zeichenkette in item_id oder item_name. Jede übergebene Kennung und jeder übergebene Name muss eine nichtleere Zeichenkette sein. GA4 akzeptiert auch einen Artikel nur mit Namen; eine ID ist nicht grundsätzlich Pflicht. Bei fehlender Menge verwendet GA4 den Wert 1. Dieses Beispiel verlangt trotzdem eine ausdrückliche Menge, damit fehlende Shopdaten auffallen.

function () {
  var e = {{DLV - ecommerce}};
  function number(x) { return typeof x === "number" && isFinite(x); }
  function text(x) { return typeof x === "string" && x.trim() !== ""; }
  if (!e || e.currency !== "EUR" || !number(e.value) || e.value < 0 ||
      !Array.isArray(e.items) || !e.items.length) { return false; }
  var sum = 0;
  for (var i = 0; i < e.items.length; i++) {
    var a = e.items[i];
    if (!a || typeof a !== "object" || Array.isArray(a)) { return false; }
    if (!text(a.item_id) && !text(a.item_name)) { return false; }
    if (a.item_id !== undefined && !text(a.item_id)) { return false; }
    if (a.item_name !== undefined && !text(a.item_name)) { return false; }
    if (!number(a.price) || a.price < 0 ||
        !number(a.quantity) || a.quantity <= 0 ||
        Math.floor(a.quantity) !== a.quantity) { return false; }
    sum += a.price * a.quantity;
  }
  return isFinite(sum) && Math.abs(sum - e.value) < 0.005;
}

Der Vergleich erlaubt eine Gleitkommaabweichung von weniger als einem halben Eurocent. Das ist eine Beispielprüfung für EUR, kein allgemeines Währungs-, Rabatt- oder Steuermodell. Kostenlose Artikel mit echtem numerischem Preis 0 bleiben gültig. Zeichenketten wie "64.95", fehlerhafte Preise und Nullmengen fallen durch, statt unbemerkt zu 0 oder 1 zu werden. Optionale Artikelfelder bleiben erhalten, weil die Liste nicht neu aufgebaut wird.

Für das GA4-Tag add_to_cart verwendet ein Trigger vom Typ „Benutzerdefiniertes Ereignis“ den Ereignisnamen add_to_cart und zusätzlich die Bedingung {{JS - ecommerce valid}} gleich true. Die Ereignisparameter currency, value und items erhalten die entsprechenden Variablen der Version 2. Die Prüfung muss am tatsächlich sendenden Tag hängen; ein Rückgabewert undefined aus einer anderen Variablen stoppt kein Tag. Andere Trigger dürfen die Prüfung nicht umgehen.

Das gewählte Ereignis prüfen

In der GTM-Vorschau liefern drei Ansichten desselben gewählten Ereignisses ergänzende Informationen: ursprüngliche Nachricht, resultierender Datenschichtzustand und aufgelöste Variablen. Zusätzliche Modellfelder können beabsichtigter dauerhafter Zustand sein und sind nicht automatisch ein Fehler. Fehlende Ergebnisse können durch Zeitpunkt, Rücksetzung, falsche Version, Schreibweise oder eigene Validierung entstehen.

Eine sinnvolle Testfolge umfasst zwei Artikel, einen Artikel, geänderte Reihenfolge, einen kostenlosen Artikel, einen Artikel nur mit Namen und fehlerhafte Eingaben. Nach einem zweiten kürzeren Ereignis dürfen keine alten Produkte übrig bleiben. Das Tag muss bei gültigen Daten einmal auslösen und bei ungültigen Daten blockiert bleiben. Tag Assistant und die ausgehende GA4-Anfrage prüfen anschließend die konfigurierte Zuordnung; ein Funktionstest allein prüft keinen Container.