Microsoft Advertising nimmt Conversions inzwischen direkt von den Servern der werbetreibenden Systeme entgegen \u2013 \u00fcber die Conversions API. Seit Anfang August 2026 liegt der zugeh\u00f6rige Integrationsleitfaden zudem in einer vollst\u00e4ndig neu geschriebenen Fassung vor. Dieser Artikel richtet sich an diejenigen, die diese Integration tats\u00e4chlich bauen und betreiben: an die Tracking-Verantwortlichen, die \u00fcber den Aufwand entscheiden, an die Entwicklerinnen und Entwickler, die den Client schreiben, und an die F\u00fchrungsebene, f\u00fcr die die Zusammenfassung gedacht ist.<\/p>\n\n\n\n
Management Summary<\/h2>\n\n\n\n
Mit der Conversions API (CAPI) meldet das Backend Conversion-Events an Microsoft Advertising, unabh\u00e4ngig davon, ob der Browser sie ausl\u00f6st. Dahinter steht ein HTTPS-Endpoint, ein Pfad je UET-Tag, authentifiziert \u00fcber ein Bearer Token, mit bis zu tausend Events pro Request. Seit dem Release vom Mai 2026 l\u00e4sst sich dieses Bearer Token programmatisch abrufen, statt es von Hand aus der Oberfl\u00e4che zu kopieren \u2013 damit wird aus einem manuellen Setup eines, das sich automatisieren und rotieren l\u00e4sst. Zur Struktur dieser Token-Antwort machen Leitfaden und Operationsreferenz unterschiedliche Angaben, und dieser Unterschied ist die h\u00e4ufigste Ursache daf\u00fcr, dass ein erster Integrationsversuch abbricht \u2013 mit einem Fehlerbild, das an ein Berechtigungsproblem erinnert, ohne eines zu sein. Der \u00fcbrige Vertrag ist unkompliziert: normalisieren, hashen, deduplizieren, innerhalb eines Sieben-Tage-Fensters bleiben.<\/p>\n\n\n\n
\n
Worum es geht:<\/strong> Ein Server-zu-Server-Endpoint unter https:\/\/capi.uet.microsoft.com\/v1\/{tagId}\/events<\/code>, der Conversion-Events f\u00fcr jeweils ein UET-Tag pro Pfad annimmt, authentifiziert \u00fcber ein Bearer Token im Authorization<\/code>-Header.<\/li>\n
Warum jetzt:<\/strong> Der Integrationsleitfaden wurde am 04.08.2026 vollst\u00e4ndig \u00fcberarbeitet, und der Auth Key l\u00e4sst sich nun \u00fcber die Campaign Management API abrufen \u2013 das Setup ist damit skriptbar statt manuell auszuf\u00fchren.<\/li>\n
Der Unterschied in der Dokumentation:<\/strong> Der Leitfaden dokumentiert eine verschachtelte Antwort f\u00fcr den Auth Key, die Operationsreferenz einen flachen String. Ein Client, der gegen den Leitfaden geschrieben wurde, wirft eine Exception auf eine Antwort, die erfolgreich war. Ein Extraktor, der beide Formen annimmt, ist gegen beide St\u00e4nde abgesichert.<\/li>\n
Was es kostet:<\/strong> Ein Entwickler, grob ein bis zwei Wochen bis zum produktiven Client inklusive Backfill, Retry und Monitoring \u2013 die API-Oberfl\u00e4che ist klein, die Zeit geht in die Normalisierung der Identifier, die Consent-Behandlung und die Deduplizierungslogik.<\/li>\n
Das Ergebnis:<\/strong> Conversions, die Adblocker, Browser-Restriktionen und abgebrochene Sessions \u00fcberstehen, dazu einen Deduplizierungsschl\u00fcssel, der verhindert, dass Browser-Tag und Server denselben Kauf doppelt z\u00e4hlen.<\/li>\n<\/ul>\n\n\n\n
Die zeitliche Dringlichkeit ergibt sich aus einer einzigen Randbedingung. Ein Aufschub bricht nichts, und das UET-Tag im Browser arbeitet exakt weiter wie bisher. Was ein Aufschub kostet, ist Messqualit\u00e4t bei genau den Conversions, die der Browser nie meldet \u2013 und weil eventTime<\/code> innerhalb der letzten sieben Tage liegen muss, l\u00e4sst sich eine L\u00fccke nicht r\u00fcckwirkend schlie\u00dfen, sobald sie \u00e4lter als eine Woche ist. Diese eine Randbedingung spricht f\u00fcr einen fr\u00fchen Start: Jede Woche Aufschub ist eine Woche, die sich nie mehr senden l\u00e4sst.<\/p>\n\n\n\n
1. Warum server-seitige Conversions bei Microsoft jetzt ein Thema sind<\/h2>\n\n\n\n
Server-seitige Conversion-APIs sind als Gattung nichts Neues. Neu ist der Stand der Dokumentation, gegen den sich implementieren l\u00e4sst. Der Integrationsleitfaden tr\u00e4gt das Dokumentendatum 04.08.2026 \u2013 sechs Tage alt, w\u00e4hrend dieser Text entsteht \u2013 und ist eine komplette Neufassung, keine Kosmetik. Die Referenzseite zur Operation f\u00fcr den Auth Key wurde einen Tag fr\u00fcher aktualisiert, am 03.08.2026. Wenn zwei zusammengeh\u00f6rige Seiten innerhalb eines Tages bewegt werden, hat sich meist auch die Oberfl\u00e4che dahinter bewegt \u2013 dann lohnt sich eine erneute Lekt\u00fcre auch bei Seiten, deren Inhalt als bekannt gilt.<\/p>\n\n\n\n
Der praktische Treiber ist schlichter als jedes Plattform-Narrativ. Der Browser meldet nur einen Teil der Conversions. Eine Conversion, die in einem Checkout mit Adblocker stattfindet, in einer Session, die endet, bevor die Best\u00e4tigungsseite rendert, in einem nativen App-Wrapper oder Stunden sp\u00e4ter im Callcenter, ist eine Conversion, die das UET-Tag nie zu Gesicht bekommt. Die Bestelldatenbank sieht sie alle. Die Conversions API ist die Leitung zwischen dem System, in dem die Bestellungen erfasst sind, und dem System, das die Gebote optimiert.<\/p>\n\n\n\n
Es gibt eine zweite, verwandte Entwicklung, die zur Einordnung geh\u00f6rt, ohne dass sich schon darauf bauen lie\u00dfe. Die Release Notes vom Mai 2026 haben den MSClickIdPerformanceReport<\/code> eingef\u00fchrt, der Performance auf Ebene der einzelnen Click-ID ausweist und sich damit gegen einen eigenen msclkid<\/code>-Bestand joinen l\u00e4sst. Seine Spalte ConversionsQualified<\/code> ist als Double<\/code> typisiert. Der Grund, das als Preview und nicht als Fundament zu behandeln: Auf der Seite steht \u201eNot everyone has this feature yet” \u2013 und zwar zweimal. Das ist ein Pilot, keine allgemeine Verf\u00fcgbarkeit. Eine Planung damit ist m\u00f6glich, eine Abh\u00e4ngigkeit davon nicht.<\/p>\n\n\n\n
2. Der technische Vertrag: Endpoint, Authentifizierung, Pflichtfelder<\/h2>\n\n\n\n
Der Vertrag ist klein genug, um ihn im Kopf zu behalten. Es gibt einen Endpoint, https:\/\/capi.uet.microsoft.com\/v1\/{tagId}\/events<\/code>, und die Tag-ID steht im Pfad, nicht im Body. Wer mehrere UET-Tags betreibt \u2013 ein verbreitetes Muster, wenn ein Konto mehrere Marken oder M\u00e4rkte bedient \u2013, spricht damit mit mehreren verschiedenen URLs, und der Client braucht die Tag-ID als vollwertigen Parameter, nicht als Konstante.<\/p>\n\n\n\n
Authentifiziert wird \u00fcber ein Bearer Token im Authorization<\/code>-Header. Kein Signieren, kein Timestamp-Header, kein Hash \u00fcber den Request-Body. Das Token geh\u00f6rt zum Tag, also ist auch das Token-Management pro Tag zu denken: ein Secret je Tag-ID, gespeichert und rotiert je Tag-ID.<\/p>\n\n\n\n
TAG_ID=123456789\nAUTH_KEY=\"$(cat \/etc\/uet\/authkey-${TAG_ID})\" # aus dem lokalen Secret Store\n\ncurl -sS -X POST \n \"https:\/\/capi.uet.microsoft.com\/v1\/${TAG_ID}\/events\" \n -H \"Authorization: Bearer ${AUTH_KEY}\" \n -H \"Content-Type: application\/json\" \n --data @batch.json<\/code><\/pre>\n\n\n\n
Ein Request transportiert bis zu 1000 Events. Die eventTime<\/code> jedes Events muss innerhalb der letzten sieben Tage liegen. Jedes Event sollte eine eventId<\/code> zur Deduplizierung sowie einen Wert f\u00fcr adStorageConsent<\/code> mitf\u00fchren. Nutzerbezogene Identifier werden auf Kleinschreibung normalisiert und anschlie\u00dfend mit SHA-256 gehasht.<\/p>\n\n\n\n
Ein Wort zur Quellenlage geh\u00f6rt an diese Stelle, denn es tr\u00e4gt weiter als jedes Codebeispiel. Die in diesem Artikel genannten Felder sind diejenigen, die die Quellen ausdr\u00fccklich festlegen. Die Feldnamen, die eine konkrete<\/em> Conversion beschreiben \u2013 der Goal Name, der Umsatzwert, die W\u00e4hrung \u2013, stammen aus der jeweiligen Tag-Konfiguration und aus der Feldtabelle im Integrationsleitfaden selbst. Ma\u00dfgeblich ist diese Tabelle; Feldnamen aus einem Blogbeitrag, auch aus diesem hier, sind es nicht. Dasselbe gilt f\u00fcr Fehlercodes und Rate Limits: Die Quellen, auf die sich dieser Artikel st\u00fctzt, nennen sie nicht, also erfindet dieser Artikel sie auch nicht. Im Client wird geloggt, was der Endpoint tats\u00e4chlich zur\u00fcckgibt, und die Retry-Strategie entsteht aus dem beobachteten Verhalten in der eigenen Umgebung, nicht aus einer geratenen Zahl.<\/p>\n\n\n\n
3. Der Auth Key und die Angaben in Leitfaden und Referenz<\/h2>\n\n\n\n
Vor dem Release im Mai 2026 wurde das CAPI-Bearer-Token \u00fcber die Oberfl\u00e4che von Microsoft Advertising abgerufen und von Hand herauskopiert. F\u00fcr ein einzelnes Tag ist das praktikabel. F\u00fcr ein Team mit elf Tags, einer Rotationsrichtlinie f\u00fcr Secrets und einem Bereitschaftsdienst, der sich um zwei Uhr nachts nicht durch eine Web-UI klicken soll, ist es das nicht mehr. Die Campaign-Management-Operation GetUetTagAuthKey<\/code> liefert das Token f\u00fcr ein gegebenes UET-Tag nun programmatisch \u2013 und genau diese \u00c4nderung macht den automatisierten Betrieb der Integration m\u00f6glich.<\/p>\n\n\n\n
Die beiden Quellen beschreiben diesen Aufruf unterschiedlich. Der Integrationsleitfaden zeigt ihn mit einem Request-Body {\"TagId\": 123456789}<\/code> und einer verschachtelten<\/em> Antwort der Form {\"TagAuthKey\": {\"AuthKey\": \"...\"}}<\/code>. Die Referenzseite zu GetUetTagAuthKey<\/code> definiert etwas anderes: Das Request-Element hei\u00dft UetTagId<\/code>, das Response-Element UetTagAuthKey<\/code> und ist ein flacher<\/em> String.<\/p>\n\n\n\n
Beide Beschreibungen lassen sich nicht gleichzeitig umsetzen, und das Fehlerbild ist unspezifisch. Ein Parser, der dem Leitfaden folgt, greift nach TagAuthKey[\"AuthKey\"]<\/code>. Gegen eine Antwort in der Form, die die Referenz beschreibt, wirft dieser Parser eine Exception \u2013 bei einem Aufruf, der in Wahrheit erfolgreich war. Der Stacktrace zeigt auf die JSON-Verarbeitung, das Symptom liest sich als \u201ees kam kein Key zur\u00fcck”, und die naheliegende Reaktion ist eine Pr\u00fcfung von Account-IDs, Customer-IDs und API-Berechtigungen. Diese Suche bleibt ergebnislos: Der Aufruf war in Ordnung, abweichend war das Schema im Leitfaden.<\/p>\n\n\n\n
Die L\u00f6sung besteht darin, sich gar nicht erst festzulegen. Ein Extraktor, der beide Formen akzeptiert, und ein Log, das festh\u00e4lt, welche Form tats\u00e4chlich eintrifft, zeigen, welches Dokument f\u00fcr das jeweilige Konto gerade zutrifft.<\/p>\n\n\n\n
import logging\n\nlog = logging.getLogger(__name__)\n\n\ndef extract_auth_key(response):\n \"\"\"Beide dokumentierten Formen der GetUetTagAuthKey-Antwort annehmen.\n\n Leitfaden : {\"TagAuthKey\": {\"AuthKey\": \"...\"}} (verschachtelt)\n Referenz : {\"UetTagAuthKey\": \"...\"} (flacher String)\n \"\"\"\n # Flache Form, wie in der Operationsreferenz definiert.\n flat = response.get(\"UetTagAuthKey\")\n if isinstance(flat, str) and flat:\n log.info(\"auth key: flat shape (reference)\")\n return flat\n\n # Verschachtelte Form, wie im Integrationsleitfaden gezeigt.\n nested = response.get(\"TagAuthKey\")\n if isinstance(nested, dict):\n key = nested.get(\"AuthKey\")\n if isinstance(key, str) and key:\n log.info(\"auth key: nested shape (guide)\")\n return key\n\n # Manche Wrapper liefern ein Objekt zurueck, kein dict.\n for attr in (\"UetTagAuthKey\", \"TagAuthKey\"):\n value = getattr(response, attr, None)\n if isinstance(value, str) and value:\n log.info(\"auth key: attribute %s on response object\", attr)\n return value\n\n raise ValueError(\n \"GetUetTagAuthKey returned neither the flat nor the nested \"\n \"shape; raw response logged for inspection\"\n )<\/code><\/pre>\n\n\n\n
Die Request-Seite verdient dieselbe Behandlung. L\u00e4sst der SOAP- oder REST-Wrapper eine Benennung des Request-Elements zu, wird UetTagId<\/code> gesendet, wie in der Referenz definiert \u2013 mit einem Codekommentar, der festh\u00e4lt, dass der Leitfaden es TagId<\/code> nennt. Wird der Aufruf wegen eines unbekannten Elements rundheraus abgelehnt, steht das Ergebnis nach drei\u00dfig Sekunden fest, statt Gegenstand einer Vermutung zu bleiben.<\/p>\n\n\n\n\n\nDieselbe Operation ist in zwei Formen dokumentiert: der Leitfaden zeigt ein verschachteltes Objekt, die Referenz einen flachen String. Ein Client, der beide liest, liefert den Schl\u00fcssel in jedem Fall und meldet einen Fehler erst, wenn keiner vorhanden ist.<\/figcaption>\n<\/figure>\n\n\n\n
4. Deduplizierung: Wie UET-Tag und Server-Event zueinanderfinden<\/h2>\n\n\n\n
Sobald Conversions vom Server gesendet werden, kommen die meisten davon auch vom Browser. Das ist kein Fehler, der wegzukonstruieren w\u00e4re \u2013 beide Wege sind erw\u00fcnscht, weil jeder F\u00e4lle abdeckt, die der andere verpasst. Zu vermeiden ist allein ein Kauf, der doppelt gez\u00e4hlt wird. Der Mechanismus daf\u00fcr ist eventId<\/code>: \u00dcber dieses Feld werden der browserseitige UET-Hit und der serverseitige Hit dedupliziert.<\/p>\n\n\n\n
Die Regel, die das tr\u00e4gt, ist eine Regel \u00fcber die eigene Anwendung, nicht \u00fcber die API. Der Identifier wird einmal erzeugt, und zwar von dem System, dem das Event geh\u00f6rt, und unver\u00e4ndert an beide Transportwege \u00fcbergeben. In der Praxis hei\u00dft das: Das Backend erzeugt die ID, wenn die Bestellung entsteht, rendert sie in die Seite, damit das UET-Tag sie senden kann, und speichert sie zur Bestellung, damit der Server-Client sp\u00e4ter denselben Wert schicken kann.<\/p>\n\n\n\n
Alle Fehlerbilder sind Varianten davon, die ID zweimal zu erzeugen. Ein Zufallswert, der beim Seitenaufbau in JavaScript entsteht, und ein zweiter Zufallswert aus dem Batch-Job werden nie zusammenpassen. Ein Wert, der aus einer Session-ID abgeleitet ist, passt nicht, wenn der Nutzer in einer anderen Session konvertiert. Ein Wert, der aus der Bestellnummer abgeleitet ist, ist stabil, eindeutig und \u00fcbersteht Retries \u2013 und genau das ist erforderlich, denn Retries sind der zweite Grund, warum Deduplizierung wichtig ist. Wenn der Batch-Job nach einem Timeout einen Chunk erneut sendet, ist die identische eventId<\/code> das, was daraus keine zweite Conversion werden l\u00e4sst.<\/p>\n\n\n\n
\n
Einmal erzeugen:<\/strong> eventId<\/code> leitet sich aus etwas ab, das die Bestellung ohnehin besitzt, damit dasselbe Event immer dieselbe ID ergibt.<\/li>\n
Durchreichen, nie neu erzeugen:<\/strong> Template und Batch-Job lesen beide den gespeicherten Wert; keiner von beiden berechnet einen eigenen.<\/li>\n
\u00dcber Retries stabil halten:<\/strong> Ein wiederholter Batch tr\u00e4gt die identischen IDs, sonst wird aus dem Retry eine Doppelz\u00e4hlung.<\/li>\n
Speichern:<\/strong> Die ID geh\u00f6rt zum Bestelldatensatz, denn sie wird f\u00fcr den Abgleich gebraucht, wenn die Zahlen auseinanderlaufen.<\/li>\n<\/ul>\n\n\n\n\n\nBeide Wege tragen dieselbe eventId. Der Browsertreffer h\u00e4ngt von der Umgebung ab, deshalb macht erst der Servertreffer die Conversion verl\u00e4sslich \u2014 und die gemeinsame Kennung verhindert, dass sie doppelt gez\u00e4hlt wird.<\/figcaption>\n<\/figure>\n\n\n\n
5. Normalisierung, Hashing und Consent<\/h2>\n\n\n\n
Nutzerbezogene Identifier werden nicht im Klartext gesendet. Das dokumentierte Verfahren besteht aus zwei Schritten in fester Reihenfolge: zuerst auf Kleinschreibung normalisieren, dann mit SHA-256 hashen. Die Reihenfolge ist nicht verhandelbar, denn Hashing ist nicht case-insensitiv. Anna@example.com<\/code> und anna@example.com<\/code> ergeben v\u00f6llig unabh\u00e4ngige Digests, und eine Verwechslung an dieser Stelle wirft keinen Fehler \u2013 sie erzeugt stillschweigend einen Hash, der auf der Gegenseite nie zu irgendetwas passen wird. Der Effekt bleibt unbemerkt: Die Pipeline meldet Erfolg, und die Match Rate liegt still und leise nahe null.<\/p>\n\n\n\n
import hashlib\n\n\ndef hash_identifier(value):\n \"\"\"Erst kleinschreiben, dann SHA-256, wie die Doku es vorgibt.\n\n Das Abschneiden umgebender Leerzeichen ist defensive Hygiene\n gegen die eigene Speicherschicht; dokumentiert sind die beiden\n Schritte Kleinschreibung + SHA-256.\n \"\"\"\n if value is None:\n return None\n normalised = str(value).strip().lower()\n if not normalised:\n return None\n return hashlib.sha256(normalised.encode(\"utf-8\")).hexdigest()\n\n\nassert hash_identifier(\"Anna@Example.COM\") == hash_identifier(\"anna@example.com\")<\/code><\/pre>\n\n\n\n
Jede weitere Bereinigung pro Feld \u2013 die Kanonisierung von Telefonnummern, der Umgang mit Plus-Adressierung in E-Mails, die Behandlung von Namen mit diakritischen Zeichen \u2013 liegt im Ermessen des implementierenden Teams. Die Quellen legen Kleinschreibung und SHA-256 fest. Ein l\u00e4nderspezifisches Telefonformat legen sie nicht fest, also nimmt dieser Artikel auch keines an. Tragf\u00e4hig ist eine einmal festgelegte Regel, die auf Browser- und Serverseite identisch angewendet und schriftlich festgehalten wird.<\/p>\n\n\n\n
Der Consent reist im Feld adStorageConsent<\/code> mit dem Event mit und nimmt den Wert \"G\"<\/code> f\u00fcr erteilt und \"D\"<\/code> f\u00fcr verweigert an. Daraus folgen zwei Entwurfsentscheidungen. Erstens muss der Wert den Consent-Zustand zum Zeitpunkt der Conversion abbilden, nicht den Zustand zum Zeitpunkt, an dem der Batch-Job l\u00e4uft \u2013 der Bestelldatensatz muss ihn also persistieren und darf ihn nicht sp\u00e4ter nachschlagen. Zweitens wird \u201eunbekannt” wie \u201everweigert” behandelt. Hat der Consent-Speicher zu einer Bestellung keine Antwort, wird \"D\"<\/code> gesendet. Ein fehlender Datensatz, der standardm\u00e4\u00dfig als erteilt gewertet wird, bleibt im Dashboard unsichtbar und f\u00e4llt erst im Audit auf.<\/p>\n\n\n\n
6. Der Client im Produktivbetrieb: Batches, Sieben-Tage-Fenster, Wiederaufnahme<\/h2>\n\n\n\n
Drei Randbedingungen pr\u00e4gen den Client: 1000 Events pro Request, eventTime<\/code> innerhalb der letzten sieben Tage und keinerlei dokumentierte Hinweise zu Rate Limiting oder Fehlercodes. Die ersten beiden sind harte Grenzen, um die herum entworfen wird. Die dritte bedeutet, dass der Client so gebaut sein muss, dass er aus dem lernt, was er beobachtet, und nicht aus dem, was angenommen wurde.<\/p>\n\n\n\n
Das Sieben-Tage-Fenster ist die Randbedingung mit der gr\u00f6\u00dften Wirkung auf den Betrieb. Das Fenster setzt eine Obergrenze daf\u00fcr, wie lange eine Pipeline ausfallen darf, bevor Daten endg\u00fcltig verloren sind. Ein Job, der an einem Freitag stillschweigend ausf\u00e4llt und erst am \u00fcbern\u00e4chsten Montag auff\u00e4llt, hat bereits Events jenseits jeder Rettung verloren. Das Fenster begrenzt au\u00dferdem den initialen Backfill: Zum Start lassen sich die letzten sieben Tage Historie senden und kein Tag mehr. Der Starttermin ist entsprechend zu planen \u2013 einen Nachholdurchlauf im dritten Monat gibt es nicht.<\/p>\n\n\n\n
from datetime import datetime, timedelta, timezone\n\nMAX_BATCH = 1000\nWINDOW = timedelta(days=7)\n\n# Kleiner Sicherheitspuffer, damit ein Event waehrend eines Retry\n# nicht mitten im Flug verfaellt. An eigener Latenz ausrichten.\nMARGIN = timedelta(hours=1)\n\n\ndef within_window(event_time, now=None):\n now = now or datetime.now(timezone.utc)\n return (now - event_time) < (WINDOW - MARGIN)\n\n\ndef batches(events):\n \"\"\"Chunks in API-Groesse liefern, Abgelaufenes verwerfen.\"\"\"\n chunk = []\n for event in events:\n if not within_window(event.event_time):\n # Mitzaehlen. Eine steigende Zahl heisst: Pipeline haengt.\n yield_expired(event)\n continue\n chunk.append(event)\n if len(chunk) >= MAX_BATCH:\n yield chunk\n chunk = []\n if chunk:\n yield chunk<\/code><\/pre>\n\n\n\n
Die Wiederaufnahme setzt auf der eigenen Datenbank auf, nicht auf einem Cursor, den die API vielleicht anbietet. Am Bestelldatensatz steht eine Spalte f\u00fcr den Sendestatus \u2013 pending, sent, expired, failed \u2013, aus der der Job liest und in die er zur\u00fcckschreibt. Dann bleibt ein Absturz mitten im Lauf folgenlos: Der n\u00e4chste Lauf greift genau die Zeilen, die nie best\u00e4tigt wurden, und weil eventId<\/code> stabil ist, ist das erneute Senden einer Zeile, deren Best\u00e4tigung unterwegs verloren ging, harmlos.<\/p>\n\n\n\n\n
Offene Events nach eventTime<\/code> sortiert ausw\u00e4hlen, \u00e4lteste zuerst, damit die dem Verfall am n\u00e4chsten stehenden zuerst hinausgehen.<\/li>\n
Alles, was bereits au\u00dferhalb des Fensters liegt, verwerfen und separat z\u00e4hlen, statt es von der API ablehnen zu lassen.<\/li>\n
In Chunks von h\u00f6chstens 1000 Events aufteilen, senden und den Chunk erst nach einem best\u00e4tigten Erfolg als gesendet markieren.<\/li>\n
Bei Fehlern zur\u00fcckstufen, die tats\u00e4chliche Antwort wortgetreu loggen und die Zeilen f\u00fcr den n\u00e4chsten Lauf offen lassen.<\/li>\n
Alarm ausl\u00f6sen, sobald die Zahl abgelaufener Events einen zuvor festgelegten Schwellwert \u00fcberschreitet \u2013 dieses Signal zeigt beginnenden Datenverlust an.<\/li>\n<\/ol>\n\n\n\n
Zum Thema Retries: Weil die hier verf\u00fcgbare Dokumentation weder Fehlercodes noch Rate Limits aufz\u00e4hlt, bleiben Annahmen dar\u00fcber, welche Fehler wiederholbar sind, besser unverdrahtet. Ein Einstieg ist exponentielles Backoff bei Transportfehlern und bei jeder nicht erfolgreichen Antwort, dazu ein vollst\u00e4ndiges Log des Bodys; die Strategie verfeinert sich, sobald eine Woche echter Antworten aus dem eigenen Konto vorliegt. Ein fest eingebautes \u201eRetry bei 429″ bezieht sich auf ein Rate-Limit-Verhalten, das bis dahin nicht beobachtet wurde.<\/p>\n\n\n\n
7. Monitoring: Welche Kennzahlen den Zustand der Integration anzeigen<\/h2>\n\n\n\n
Eine CAPI-Integration f\u00e4llt leise aus. Es gibt keine Beschwerde \u00fcber einen kaputten Checkout, sondern ein langsames Abdriften der Zahlen, das sechs Wochen sp\u00e4ter auff\u00e4llt. Das Monitoring muss deshalb bewusst gesetzt werden \u2013 und der gr\u00f6\u00dfte Teil davon lebt in der eigenen Datenbank, nicht in einem Anbieter-Dashboard.<\/p>\n\n\n\n
-- Taegliche Gesundheit der Sende-Pipeline. Tabellen- und Spalten-\n-- namen sind Platzhalter fuer den lokalen Order-\/Event-Speicher.\nSELECT\n date_trunc('day', event_time) AS day,\n count(*) AS events_total,\n count(*) FILTER (WHERE send_state = 'sent') AS sent,\n count(*) FILTER (WHERE send_state = 'pending') AS still_pending,\n count(*) FILTER (WHERE send_state = 'expired') AS lost_to_window,\n count(*) FILTER (WHERE ad_storage_consent = 'D') AS consent_denied,\n count(*) FILTER (WHERE hashed_email IS NULL) AS no_identifier,\n round(avg(EXTRACT(EPOCH FROM (sent_at - event_time)) \/ 60.0), 1)\n AS avg_lag_minutes\nFROM conversion_events\nWHERE event_time >= now() - interval '30 days'\nGROUP BY 1\nORDER BY 1 DESC;<\/code><\/pre>\n\n\n\n
F\u00fcnf Signale sind eine Alarmierung wert. Abgelaufene Events<\/strong> oberhalb von null hei\u00dfen, dass die Pipeline hinterherhinkt und Daten verloren gehen; dieses Signal hat die h\u00f6chste Priorit\u00e4t. Sendeverzug<\/strong> ist der Fr\u00fchindikator f\u00fcr dasselbe Problem \u2013 beobachtet wird der durchschnittliche Abstand zwischen eventTime<\/code> und dem Sendezeitpunkt, mit einer Alarmschwelle lange vor Erreichen der sieben Tage. Identifier-Abdeckung<\/strong>, also der Anteil der Events, die \u00fcberhaupt einen gehashten Identifier tragen, bricht an dem Tag ein, an dem ein Checkout-Formular oder eine Consent-Voreinstellung ge\u00e4ndert wird; ein pl\u00f6tzlicher Sprung dort ist eine Code\u00e4nderung, keine Marktverschiebung. Consent-Verteilung<\/strong>, das Verh\u00e4ltnis von \"G\"<\/code> zu \"D\"<\/code>, bewegt sich normalerweise langsam; ein Sprung bedeutet, dass das Consent-Tool sein Verhalten ge\u00e4ndert hat. Erfolgsquote der Batches<\/strong> zeigt, ob der Endpoint annimmt, was gesendet wird, und geh\u00f6rt auf dasselbe Dashboard wie der Rest, auch wenn sie die naheliegendste Kennzahl ist.<\/p>\n\n\n\n
Der Abgleich mit der Plattformseite ist das letzte St\u00fcck, und daf\u00fcr sind Daten auf Klick-Ebene der n\u00e4chste Schritt. Der Vergleich der gesendeten Menge mit den ausgewiesenen Conversions zeigt, ob die Deduplizierung greift: Liegt der Plattformwert sp\u00fcrbar \u00fcber der Vereinigungsmenge aus Browser- und Server-Events, passt die eventId<\/code> nicht zusammen. Der MSClickIdPerformanceReport<\/code> ist das naheliegende Werkzeug f\u00fcr diesen Vergleich, weil er sich \u00fcber die Click-ID gegen den eigenen msclkid<\/code>-Bestand joinen l\u00e4sst und ConversionsQualified<\/code> eine numerische Vergleichsspalte liefert. Zu ber\u00fccksichtigen bleibt, was seine eigene Seite zweimal sagt \u2013 noch hat nicht jeder dieses Feature. Der Abgleich ist deshalb so zu bauen, dass er sauber auf den aggregierten Vergleich zur\u00fcckf\u00e4llt, wenn der Report f\u00fcr das jeweilige Konto nicht verf\u00fcgbar ist.<\/p>\n\n\n\n
Fazit<\/h2>\n\n\n\n
Zur Integration geh\u00f6ren ein Token-Abruf, ein Normalisierer, ein Batcher und eine Statusspalte. Der Endpoint nimmt einen Pfad je Tag, ein Bearer Token und bis zu tausend Events auf einmal auf. Die aufwendigeren Teile liegen au\u00dferhalb der API \u2013 sie bestehen darin, zu entscheiden, wo eventId<\/code> entsteht, den Consent-Zustand zu dem Zeitpunkt zu persistieren, zu dem er gilt, und daf\u00fcr zu sorgen, dass Kleinschreibung ausnahmslos vor SHA-256 passiert.<\/p>\n\n\n\n
Der Ertrag sind die Conversions, die der Browser nie gemeldet hat, und ein Gebotssignal, das die Bestelldatenbank abbildet statt nur den Teil davon, der die Reise durch einen Browser \u00fcberstanden hat. Das Sieben-Tage-Fenster ist der Grund, dieses Vorhaben zu terminieren statt zu vertagen: Ungesendete Historie, die \u00e4lter als eine Woche ist, l\u00e4sst sich nicht mehr \u00fcbermitteln \u2013 der Wert der Integration ist also dadurch begrenzt, wie fr\u00fch sie zu laufen beginnt.<\/p>\n\n\n\n
![\"Ein](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/hand-mscapi-de.png\")
\n![\"Ein](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/hand-mscapiflow-de.png\")
\n