Die Bausteine
- Ein UET-Tag (Tools → UET-Tags). Seine numerische ID ist öffentlich und steht im JavaScript-Snippet.
- Ein Conversion-Ziel vom Typ „Ereignis“ oder „Ziel-URL“, das an dieses Tag gebunden ist; Server-Events werden über Eventname, Kategorie, Label und Wert genauso gegen Ziele gematcht wie Tag-Events.
- Ein OAuth-2.0-Access-Token für die Microsoft Advertising API (Scope
msads.manage), ausgestellt für das Konto, dem das Tag gehört. Track holt und erneuert ihn über die Microsoft-OAuth-Verbindung und bewahrt ihn im Tresor auf.
Der Request
POST https://capi.uet.microsoft.com/v1/{tagId}/events mit Authorization: Bearer <token> und einem JSON-Array von Events:
{
"data": [{
"eventType": "custom",
"eventName": "purchase",
"eventId": "01J9EXAMPLESOURCEEVENTID00",
"eventTime": 1767225600000,
"eventSourceUrl": "https://shop.example/danke",
"userData": { "em": "<sha256>", "ph": "<sha256>", "msclkid": "…", "clientUserAgent": "…", "clientIpAddress": "…" },
"eventData": { "eventValue": 129.9, "eventCurrency": "EUR", "items": [{ "id": "SKU-1", "name": "Produkt", "price": 99.9, "quantity": 1 }] }
}],
"continueOnValidationError": true
}eventTime sind Millisekunden seit Epoch. eventType ist custom für Conversion-Events und pageLoad für Seitenaufrufe. Mit continueOnValidationError: true nimmt der Endpunkt die gültigen Zeilen an und meldet die ungültigen mit ihrem Index; Track markiert diese Zeilen als ungültige Payload und wiederholt sie nicht, während HTTP 5xx und 429 mit Backoff wiederholt werden.
Bis zu 1.000 Events passen in einen Request.
Deduplizierung mit dem UET-Tag
Feuert auch das UET-JavaScript-Tag das Event, müssen beide Wege dieselbe eventId und denselben Eventnamen teilen. Im Browser gibst du die ID in den Event-Parametern mit (window.uetq.push('event', 'purchase', { revenue_value: 129.9, currency: 'EUR', event_id: '…' })); der Server sendet denselben Wert in eventId. Microsoft zählt die Conversion dann einmal. Das Track-SDK erzeugt eine ID pro Aktion und reicht sie gleichermaßen an das UET-Template und den Collector.
Kennungen
msclkid— die Click-ID, die Microsoft an Landingpage-URLs anhängt. Nach Marketing-Consent erfassen und First-Party speichern; ohne sie lassen sich Server-Events nur über gehashte Kennungen zuordnen.emundph— SHA-256-Hashes der normalisierten E-Mail und Telefonnummer.anid— die Microsoft-Werbe-ID für App-Traffic.clientUserAgentundclientIpAddress— für Web-Events empfohlen und im Collector verfügbar, wenn die Policy das Weiterleiten der IP erlaubt.
Testen
Die API kennt kein Test-Flag. Ein aus dem Assistenten gesendetes Testevent ist ein echtes Event auf der konfigurierten Tag-ID; gib der Staging-Umgebung deshalb eine eigene UET-Tag-ID und behalte die Produktions-Tag-ID für die Produktion — der Assistent zeigt Microsofts zeilenweise Antwort in beiden Fällen. Verlässt die Destination den Testmodus, erhält die Tag-ID der Produktionsumgebung die Events.
Fehler
| Antwort | Bedeutung | Behandlung |
|---|---|---|
| 401 | Token abgelaufen oder falscher Tenant | wird automatisch erneuert; neu verbinden, wenn die Erneuerung scheitert |
| 403 | Konto hat keinen Zugriff auf die Tag-ID | Tag-Eigentümerschaft prüfen |
| 400 mit Zeilendetails | ungültige Feldwerte | Zeile als ungültig markiert; Mapping korrigieren |
| 429 | Rate-Limit | Wiederholung mit Backoff |
| 5xx | Fehler auf Microsoft-Seite | Wiederholung; Circuit Breaker bei Andauern |
Jeder Versuch, auch die von Microsoft abgelehnten Zeilen, ist im Destination-Monitor mit geschwärzter Payload-Vorschau sichtbar.