Debug-Modus und Validierungsrückmeldungen

Mit dem Debug-Modus erhältst du detaillierte Rückmeldungen dazu, wie deine Events zum veröffentlichten Schema passen. Du kannst damit schon beim Implementieren Feldtypen, Pflichtwerte und unbekannte Felder direkt in der Antwort prüfen.

Ergänze die folgenden Debug-Header, sende ein Event und sieh dir seine Validierungsergebnisse an. Mit Server-GTM kannst du diese Rückmeldung außerdem über JSON Client bis in den Browser zurückgeben und in der Konsole anzeigen.

Debug-Modus aktivieren

Sender an Platform	Zusätzliche Debug-Header
Backend oder Server-GTM mit Server-Key	X-DDA-Debug: true
Direkter Browser-Request mit Browser-Key	X-DDA-Debug: true und X-DDA-Debug-Token: <token-dieses-browser-keys>

Authorization, Content-Type und Schema-Versionsheader bleiben erforderlich. Der Debug-Token ist vom Browser-Ingestion-Key getrennt. Das Flag muss genau den Wert true haben. Es fordert Details für diesen Request an und aktiviert keinen dauerhaften Modus für das gesamte Environment.

Header eines Server-Requests:

Authorization: Bearer <server-key>
Content-Type: application/json
X-DDA-Event-Schema-Version: <published-version>
X-DDA-Debug: true

Header eines direkten Browser-Requests:

Authorization: Bearer <browser-key>
Content-Type: application/json
X-DDA-Event-Schema-Version: <published-version>
X-DDA-Debug: true
X-DDA-Debug-Token: <debug-token-for-this-browser-key>

Ergänze X-DDA-Debug: true im Request. Bei einem Server-Key genügt dieser Header. Bei einem Browser-Key sende zusätzlich X-DDA-Debug-Token mit dem Debug-Token genau dieses Keys aus Ingestion keys. Der Token eines anderen Keys desselben Environments funktioniert nicht.

Verwende den Browser-Token nur in einer kontrollierten Debug-Sitzung. Bette ihn nicht in Code ein, der an alle Besucher ausgeliefert wird. Ein Cookie oder ein Preview-Flag des Tag Managers allein aktiviert keine API-Diagnosen. Deine Integration muss die Header mitsenden.

Validierungsrückmeldung ansehen

Sende ein Event mit den Debug-Headern und öffne die Antwort im Netzwerk-Tab der Browser-Entwicklertools, in der Tag-Manager-Preview oder in deinem HTTP-Client. results[].validation.status zeigt das Validierungsergebnis für jedes Event. Mit aktiviertem Debug ergänzt results[].validation.issues die Details zu Warnungen und Fehlern, zum Beispiel:

{
  "severity": "warning",
  "code": "schema_unknown_field",
  "path": "events[0].campaign.internal",
  "message": "The field is not part of this event schema version and was discarded.",
  "observedType": "string",
  "action": "removed"
}

Der Pfad benennt das betroffene Feld. Vergleiche es mit der vom Sender verwendeten veröffentlichten Version, nicht nur mit dem aktuellen Entwurf. Diagnosen können gekürzt sein. Debug verändert weder Annahmeregeln noch aktiviert es den Validierungsmodus. Bei fehlendem oder ungültigem Browser-Debug-Token bleibt die Antwort kompakt. Die Event-Annahme wird dadurch nicht unterbrochen.

Event-Ergebnis verstehen

results[].status	Bedeutung	Nächster Schritt
sampled_for_schema_discovery	Für Strukturermittlung verwendet	Schema prüfen und veröffentlichen, dann Sender aktualisieren
validated_only	Ohne Collection geprüft	Destination einrichten und testen, dann frische Events senden
queued	Zur Verarbeitung angenommen	Destination-Status und Warehouse-Auslieferung prüfen
duplicate	Identisches Event innerhalb der Deduplizierungsfrist bereits angenommen	Ursprüngliches Event sowie Trigger und Wiederholungen prüfen
filtered	Durch Bot- oder Consent-Regeln ausgeschlossen	reason und die relevanten gemappten Event-Felder prüfen
rejected	Dieses Event wurde nicht angenommen	code und Validierungsdetails prüfen, dann korrigieren

validation.status ist vom Verarbeitungsstatus getrennt. Möglich sind passed, warning, failed und not_run. Eine Warnung kann auf ein entferntes unbekanntes Feld hinweisen. Ein bestandenes Schema garantiert keine Warehouse-Auslieferung. Prüfe jedes Batch-Ergebnis. HTTP 202 allein bestätigt nicht den Erfolg aller Events.

Validierungsantwort über Server-GTM zurückgeben

Diese Integration besteht aus drei Komponenten mit unterschiedlichen Aufgaben:

Komponente	Ausführungsort	Aufgabe
JSON Tag	Browser, üblicherweise über Web-GTM	Sendet das Event an deinen Tagging-Server und empfängt dessen Antwort
JSON Client	Server-GTM, als Client-Template	Nimmt den eingehenden Request entgegen, bereitet Event Data auf und stellt sie den Server-Tags bereit
JSON Server Tag	Server-GTM, als Tag-Template	Sendet das Event an Platform und gibt dessen Antwort an JSON Client zurück

So kannst du die Platform-Validierung während der Entwicklung bis in den Browser zurückgeben:

Browser: JSON Tag → Server-GTM: JSON Client → JSON Server Tag → Platform
Browser: JSON Tag ← Server-GTM: JSON Client ← JSON Server Tag ← Validierungsantwort

1. Konfiguriere JSON Tag im Browser, üblicherweise über Web-GTM, für den Versand an deinen Tagging-Server. Richte JSON Client im Server-GTM so ein, dass es Requests unter diesem Pfad entgegennimmt und die Event Data aufbereitet. Konfiguriere JSON Server Tag für diese Events und die Weiterleitung an Platform mit Server-Key und Schema-Version.
2. Ergänze unter Custom Request Headers des Tags X-DDA-Debug mit dem Wert true für deine kontrollierten Entwicklungs- oder Preview-Requests. Auf dieser Server-zu-Server-Strecke ist kein Platform-Browser-Debug-Token erforderlich.
3. Aktiviere unter Response Settings die Option Send Response to JSON Client. Setze Response Key auf einen erkennbaren Wert wie platform_validation.
4. Löse über JSON Tag ein Testevent aus. Prüfe die Antwort deines Tagging-Servers. Die enthaltene Tag-Antwort liefert requestId und results von Platform.
5. Lies results[].validation.issues für Rückmeldungen zu einzelnen Feldern schon während der Entwicklung. Prüfe auch results[].status, selbst wenn Server-GTM den HTTP-Aufruf als erfolgreich bewertet.

JSON Server Tag enthält die Weiterleitung bereits als Option. Eine Änderung am Template-Code ist dafür nicht nötig. Siehe die Dokumentation der Response Settings.

Der aktuelle JSON Client liefert auch für ein einzelnes Event ein Array unter responses. Jeder Eintrag enthält seine Tag-Daten unter tags. JSON Tag kann diese zurückgegebenen Daten auch in seinem Data-Layer-Push bereitstellen. Siehe Antwortweiterleitung im JSON Client und Batch-Antworten.

Validierung mit einem Custom-HTML-Tag in Web-GTM ausgeben

Dieses Beispiel gruppiert Ergebnisse in der Browser-Konsole, hebt angenommene Events hervor und zeigt Validierungshinweise als Tabelle. Es läuft im Web-Container, nachdem JSON Tag die Antwort deines Tagging-Servers erhalten hat.

1. Aktiviere Send Response to JSON Client im JSON Server Tag. Setze für dieses Skript Response Key auf dda. Falls du oben platform_validation verwendet hast, ändere entweder diese Einstellung oder ersetze response.tags.dda im Skript durch response.tags.platform_validation.
2. Suche in der Web-GTM-Preview das Data-Layer-Event, mit dem JSON Tag die Antwort bereitstellt. Erstelle eine Data-Layer-Variable für das vollständige geparste JSON-Client-Antwortobjekt einschließlich responses. Nenne die GTM-Variable Jsonclient Response (Data Layer Variable), damit sie zur Referenz unten passt. Der Variablenname ist nicht der Data-Layer-Pfad. Übernimm diesen aus deinem tatsächlichen Push.
3. Erstelle im Web-Container ein Custom HTML-Tag und füge das Skript unten ein.
4. Aktiviere Push Response in Data Layer in JSON Tag Settings. Erstelle einen Custom Event-Trigger mit dem Eventnamen jsonclientResponse (Groß- und Kleinschreibung beachten). Den Trigger selbst kannst du JSON Client Response nennen. Wenn du Data Layer Event Name in JSON Tag Settings geändert hast, verwende diesen Wert. Löse das Tag bei der Antwort aus, nicht schon beim ausgehenden Tracking-Event.
5. Sende ein Event, öffne die Browser-Konsole und klappe die Ergebnisgruppe auf.

Konsolenausgabe auf Debug-Sitzungen begrenzen

Aktiviere im Web-Container unter Variables → Configure die integrierte Variable Debug Mode. Sie zeigt den GTM-Preview-/Debug-Modus an. Ergänze am Konsolen-Tag eine Ausnahme:

Einstellung	Wert
Auslösender Trigger	Custom Event jsonclientResponse
Ausnahme-Trigger	Custom Event jsonclientResponse, Some Custom Events
Bedingung der Ausnahme	{{Debug Mode}} ist nicht gleich true

Hinterlege die Ausnahme unter Exceptions am Tag. Beide Trigger prüfen dasselbe Antwort-Event. Außerhalb des Preview-/Debug-Modus blockiert die Ausnahme das Konsolen-Tag.

Alternativ erstellst du eine Variable vom Typ 1st Party Cookie für ein eigenes Debug-Cookie, zum Beispiel tracking_debug. Verwende eine Custom-Event-Ausnahme für dasselbe Antwort-Event mit der Bedingung, dass diese Variable nicht gleich 1 ist. Setze das Cookie für deine Debug-Sitzung auf 1. Auch bei fehlendem Cookie bleibt die Konsolenausgabe blockiert. Wenn entweder GTM-Preview oder das Cookie die Ausgabe freigeben soll, kombiniere beide negativen Bedingungen in einer Ausnahme: Debug Mode ist nicht gleich true und Cookie ist nicht gleich 1.

Diese Bedingungen steuern nur das Konsolen-Tag. Sie aktivieren weder den Platform-Header X-DDA-Debug noch die serverseitige Antwortweiterleitung. Konfiguriere beides separat. Prüfe in Preview, dass das Tag bei aktiver gewählter Debug-Bedingung auslöst und bei inaktiver Bedingung blockiert wird.

Quellen: Antwortkonfiguration in JSON Tag Settings, integrierte GTM-Variablen und Trigger-Ausnahmen.

Die Referenz {{...}} ist eine GTM-Variable und kein eigenständig ausführbares JavaScript. Passe sie bei einem anderen Variablennamen an. Das Skript liest die Antwort und stellt sie dar. Es sendet keine Events und aktiviert keine Debug-Header.

<script>
(function () {
  var client = {{Jsonclient Response (Data Layer Variable)}};
  var con = window.console;

  if (!con || !client || !Array.isArray(client.responses)) return;

  var successStyle =
    "background: #dcfce7; color: #166534; padding: 3px 8px; " +
    "border-radius: 4px; font-weight: bold;";
  var warningStyle =
    "background: #ffedd5; color: #9a3412; padding: 3px 8px; " +
    "border-radius: 4px; font-weight: bold;";

  client.responses.forEach(function (response, responseIndex) {
    var feedback = response && response.tags && response.tags.dda;
    if (!feedback) return;
    var requestId = feedback.requestId || "unknown";

    if (!Array.isArray(feedback.results)) {
      con.log("%c[Drag & Drop Analytics] NO EVENT RESULTS", warningStyle, {
        requestId: requestId,
        status: feedback.status,
        code: feedback.code,
        message: feedback.message
      });
      return;
    }

    feedback.results.forEach(function (result) {
      if (!result) return;
      var validation = result.validation || {};
      var issues = Array.isArray(validation.issues) ? validation.issues : [];
      var passed = validation.status === "passed" &&
        issues.length === 0 && !validation.truncated;
      var success = passed && result.status === "queued";
      var headline;

      if (success) {
        headline = "✓ QUEUED";
      } else if (result.status === "rejected" || validation.status === "failed") {
        headline = "⚠ FAILED";
      } else if (issues.length || validation.status === "warning" || validation.truncated) {
        headline = "⚠ VALIDATION ISSUES";
      } else {
        headline = (result.status || "UNKNOWN").toUpperCase();
      }

      var label = "[Drag & Drop Analytics] " + headline +
        " | Response " + responseIndex +
        " | Event index " + result.index +
        " | " + result.status +
        " | Validation: " + (validation.status || "unknown");
      con.groupCollapsed("%c" + label, success ? successStyle : warningStyle);
      con.log("Request ID:", requestId);

      if (issues.length) {
        var rows = issues.map(function (issue) {
          return {
            Severity: issue.severity || "",
            Code: issue.code || "",
            Path: issue.path || "",
            Message: issue.message || "",
            ExpectedType: issue.expectedType || "",
            ObservedType: issue.observedType || "",
            Action: issue.action || ""
          };
        });
        if (con.table) con.table(rows);
        else con.log(rows);
      }
      if (validation.truncated) {
        con.warn("Diagnostics were truncated. Additional issues are not shown.");
      }
      if (passed) {
        con.log(result.status === "queued"
          ? "✓ Valid, with no validation issues. Added to the queue."
          : "✓ Validation passed with no validation issues.");
      } else if (!issues.length && !validation.truncated) {
        if (validation.status === "not_run") {
          con.info("Validation was not performed, e.g. during schema discovery.");
        } else {
          con.warn("Validation status:", validation.status || "unknown",
            "| No issue details included in the response.");
        }
      }
      if (result.status === "rejected") {
        con.error("Event rejected:", result.code || "no error code provided");
      } else if (result.status === "filtered") {
        con.info("Event filtered:", result.reason || "no reason provided");
      } else if (result.status === "duplicate") {
        con.info("Duplicate detected. Not added to the queue again.");
      }
      con.groupEnd();
    });
  });
})();
</script>

Grünes QUEUED bedeutet, dass die Validierung bestanden und das Event in die Queue aufgenommen wurde. Es bestätigt keine Warehouse-Auslieferung. Andere Gruppen zeigen Validierungswarnungen, Ablehnungen, Filterung, Duplikate oder reine Validierung. Gekürzte Diagnosen werden ausdrücklich gekennzeichnet. Leere Detailspalten bedeuten, dass die Antwort die Eigenschaft nicht enthält. Die aktuellen Platform-Diagnosen liefern kein expectedType. Diese optionale Spalte bleibt deshalb leer.

Aktiviere für detaillierte Feldhinweise den oben beschriebenen serverseitigen Debug-Header. Das Skript kann keine Details ergänzen, die nicht in der Antwort stehen.

Rückmeldung während der Entwicklung prüfen

Sende im Test-Environment zuerst ein gültiges Event. Sende danach eines mit einem bewusst falschen Typ für ein Pflichtfeld. Prüfe, dass es rejected, Validierung failed und einen Hinweis auf das betroffene Feld zurückgibt. Korrigiere es und sende ein frisches Event. Ein zusätzliches unbekanntes Feld kann dagegen eine Warnung auslösen und entfernt werden, ohne das ganze Event abzulehnen. So lassen sich Warnungen und Fehler schon vor der Veröffentlichung der Tracking-Änderung unterscheiden.

Begrenze die detaillierte Antwortweitergabe auf die vorgesehene Debug-Nutzung. Setzt das Server-Tag den Debug-Header immer, können alle Empfänger seiner Antwort Diagnosen erhalten. Entferne oder begrenze Header und Antwortweiterleitung nach der Entwicklung. Der Server-Key bleibt auf dem Server.

HTTP-Fehler untersuchen

HTTP-Status	Prüfen
400	JSON-Struktur, Pflichtfelder, Typen und Schema-Versionsheader. Fehlercode oder Einzelergebnisse lesen
401	Fehlender, ungültiger, abgelaufener oder widerrufener Ingestion Key
403	Erlaubte Browser-Origins, Key-Typ und tatsächliche Request-Origin
409	Producer event ID mit widersprüchlichem Inhalt wiederverwendet
413	Event-Größe, gesamte Request-Größe oder Batch-Anzahl
429	Rate Limit oder Quote. Antwortinformationen und gegebenenfalls Retry-After beachten
503	Vorübergehend nicht verfügbare Ingestion oder Verarbeitung. Stabile Event-IDs für begrenzte Wiederholungen behalten

Wiederhole nicht jede 4xx-Antwort unverändert. Behebe ihre Ursache. Ein Batch kann angenommene und abgelehnte Events enthalten. Der HTTP-Status allein reicht deshalb nicht für die Diagnose.

Wenn Warehouse oder Report leer bleiben

1. Prüfe, ob das Event an das richtige Environment und die richtige Destination ging.
2. Prüfe das Ergebnis. Discovery- und Validation-only-Events werden später nicht nachgeliefert.
3. Prüfe bei filtered die Consent-Mappings, Destination-Anforderungen und den gemappten User-Agent für die Bot-Erkennung.
4. Prüfe bei queued die Destination-Verbindung und Hinweise zu Collection needs attention. Annahme ist keine Warehouse-Bestätigung.
5. Wenn das Event im Warehouse liegt, prüfe Explorer-Datenquelle, Leseberechtigungen, Zeitraum, Zeitzone, gewählte Metrik und Filter.

Sende nach einer Änderung ein neues Event, um die aktualisierte Validierungsrückmeldung zu sehen.