Events über die HTTP-API senden

Request-Vertrag

Kopiere den Ingestion-Endpoint deiner Installation aus Tracking setup. Die Route lautet POST /ingest/v1/events. Sende ein Event-Objekt oder ein direktes Array aus Event-Objekten mit Content-Type: application/json. Verpacke einen Batch nicht in eine Eigenschaft events, außer sie gehört zum Schema eines einzelnen Events.

Header	Wert
Authorization	Bearer <ingestion-key>
Content-Type	application/json
X-DDA-Event-Schema-Version	Veröffentlichte positive Ganzzahl aus Update tracking

Der Key bestimmt Organization, Projekt und Environment. Payload-Felder können diese Zuordnung nicht ändern. Eine Schema-Version gilt für alle Events eines Requests. Lasse den Versionsheader nur für Discovery vor der ersten veröffentlichten Projektversion weg. Danach ist ein fehlender Header ein Fehler. Verwende im Sender die Version seiner Implementierung bis zur bewussten Aktualisierung.

Optionale Debug-Header

Für detaillierte Validierungsrückmeldungen während der Tracking-Implementierung ergänzt du die normalen Request-Header um folgende Angaben:

Sender	Zusätzliche Header
Server-Key, auch bei Server-GTM	X-DDA-Debug: true
Browser-Key	X-DDA-Debug: true und X-DDA-Debug-Token: <debug-token-dieses-browser-keys>

Verwende genau den Wert true. Der Browser-Debug-Token ist vom Ingestion Key getrennt und steht unter Ingestion keys beim jeweiligen Browser-Key. Bei einem Server-Key ist kein zusätzlicher Debug-Token nötig.

Sende ein Event und prüfe results[].validation.status. Bei freigegebenem Debug liefert results[].validation.issues zusätzlich Details zu betroffenen Feldern bei Warnungen und Fehlern. Debug verändert weder Event-Annahme noch Auslieferung. Bei fehlendem oder ungültigem Browser-Debug-Token bleibt die Antwort kompakt.

Unter Debug-Modus und Validierungsrückmeldungen findest du vollständige Header-Beispiele, die Auswertung der Antwort und die Weiterleitung über Server-GTM bis in die Browser-Konsole.

Payload definieren und zuordnen

Platform nimmt deine JSON-Struktur an. Das veröffentlichte Schema legt Pflichtfelder, Typen und Mappings fest. Ein Feldname allein gibt einem Wert keine feste Bedeutung. Zum Beispiel:

{
  "event": {
    "name": "button_click",
    "id": "example-event-0001",
    "timestamp": "2026-10-11T12:00:00Z"
  },
  "button": {"id": "start_trial"}
}

Ordne in diesem Beispiel event.name als Event name, event.id als Producer event ID und event.timestamp als Event-Zeitstempel zu. Definiere button.id als String-Feld für button_click. Verwende für jedes echte Event einen aktuellen Zeitstempel und eine eindeutige ID. Ergänze alle Pflichtfelder aus veröffentlichtem Base Schema und Event-Schema. Producer event ID ist optional. Für sichere Wiederholungen ist eine stabile ID jedoch wichtig.

Unbekannte Felder erzeugen Warnungen und werden vor der Speicherung entfernt. Verlasse dich nicht darauf, dass nicht deklarierte Felder im Warehouse ankommen. Fehlende Pflichtfelder und Typfehler lehnen das betroffene Event ab. Prüfe Schemaänderungen vor der Aktualisierung des Senders.

Vom Server senden

Speichere den Server-Key in der Secret-Konfiguration deines Servers. Der folgende Aufruf setzt voraus, dass INGESTION_ENDPOINT, INGESTION_KEY und SCHEMA_VERSION sicher gesetzt sind. event.json enthält ein zum veröffentlichten Schema passendes Event:

curl --request POST "$INGESTION_ENDPOINT" \
  --header "Authorization: Bearer $INGESTION_KEY" \
  --header 'Content-Type: application/json' \
  --header "X-DDA-Event-Schema-Version: $SCHEMA_VERSION" \
  --data-binary @event.json

Prüfe HTTP-Status und JSON-Antwort. Protokolliere den Authorization-Header nicht. Sende bei einem Relay benötigte ursprüngliche Besucherinformationen über die dafür gemappten Event-Felder. Der HTTP-User-Agent des Relays ersetzt beispielsweise für die Bot-Erkennung nicht den gemappten Besucher-User-Agent im Event.

JSON Server Tag in Server-GTM konfigurieren

Im üblichen Browser-zu-Server-Aufbau sendet JSON Tag aus dem Browser an deinen Tagging-Server. JSON Client läuft im Server-GTM, nimmt den Request entgegen und bereitet Event Data auf. JSON Server Tag leitet diese Daten anschließend an Platform weiter.

Wähle die serverseitige Methode JSON Server Tag in Tracking setup. Konfiguriere im Server-Container HTTP Endpoint, POST, JSON Content Type und die oben genannten Header unter Custom Request Headers. Ordne unter Map Event Properties deine eingehenden Event-Variablen der JSON-Struktur deines Schemas zu.

Wähle den Trigger für die weiterzuleitenden Events. Prüfe in Preview den ausgehenden Request-Body und die Antwort. Nach einer neuen Schema-Veröffentlichung aktualisierst du mit Update tracking den Versionsheader im Tag und veröffentlichst den Container. Sende ein Event nicht zugleich über Browser und Relay, ohne Event-IDs und Deduplizierung für dieses Verhalten bewusst zu planen.

Für Rückmeldungen im Browser während der Entwicklung aktiviere Debug-Modus und JSON-Client-Antwortweiterleitung.

Direkt aus dem Browser senden

Verwende einen Browser-Key und eine erlaubte Origin. Die Runtime aus der Tracking-Anleitung liefert die generierte Integration. Ein eigener Sender verwendet denselben HTTP-Vertrag:

async function sendEvent(endpoint, browserKey, schemaVersion, event) {
  const response = await fetch(endpoint, {
    method: 'POST',
    credentials: 'omit',
    headers: {
      'Authorization': `Bearer ${browserKey}`,
      'Content-Type': 'application/json',
      'X-DDA-Event-Schema-Version': String(schemaVersion)
    },
    body: JSON.stringify(event)
  })
  const result = await response.json()
  return {httpStatus: response.status, ...result}
}

Der Browser führt bei Bedarf einen CORS-Preflight aus. Dessen Erfolg bestätigt noch nicht, dass der Key für die Origin zugelassen ist. Das prüft der authentifizierte POST. Verwende für diese API kein sendBeacon, da sie einen Authorization-Header verlangt. Browser-Cookies authentifizieren den Ingestion-Request nicht.

Jedes Event-Ergebnis auswerten

Einzelne Events und Batches verwenden dieselbe Antwortstruktur:

{
  "requestId": "example-request-id",
  "results": [
    {"index": 0, "status": "queued", "validation": {"status": "passed"}},
    {"index": 1, "status": "rejected", "code": "platform_ingestion_event_invalid", "validation": {"status": "failed"}}
  ]
}

index beginnt bei null und bezieht sich auf die ursprüngliche Eingabereihenfolge. Auch ein erfolgreicher HTTP-Status kann abgelehnte Events enthalten. Prüfe jedes Ergebnis, auch bei HTTP 200 oder 202. Ein requestweiter Fehler liefert stattdessen requestId, status, code und message. Die Fehlerdiagnose erklärt die Auswertung.

Wiederholungen und Batches

Behalte bei einer Wiederholung mit unbekanntem Ausgang die gemappte Producer event ID und den Event-Inhalt bei. Innerhalb der Deduplizierungsfrist wird ein identischer Replay als duplicate erkannt. Eine gleiche ID mit widersprüchlichem Inhalt wird abgelehnt. Ohne gemappte und mitgelieferte Producer event ID werden reguläre Events nicht dedupliziert. Wiederholungen allein garantieren keine exakt einmalige Auslieferung.

Korrigiere bei teilweise angenommenen Batches die abgelehnten Events und sende diese gezielt erneut. Wiederhole nach einer erfolgreichen Antwort nicht blind den ganzen Batch. Verwende bei Netzwerkfehlern oder vorübergehenden Serverfehlern begrenzte Wiederholungen mit zunehmendem Abstand und stabilen IDs. Ein Timeout beim Client beweist nicht, dass der Server den Request abgelehnt oder zurückgerollt hat. Beachte Retry-After, wenn vorhanden. Authentifizierungs- und Schemafehler benötigen eine Korrektur statt einer unveränderten Wiederholungsschleife.

Die Standardgrenzen sind 100 Events pro Batch, 32 KiB pro Event und 256 KiB pro Request. Installationen können andere Grenzen konfigurieren. Beachte sowohl Anzahl als auch Byte-Größe. Zusätzlich gelten Organization-Quoten und Rate Limits.