Microsoft Advertising, UET und Conversions API

Server-Side-Conversion-Uploads an Bing Ads via Beaconrys OAuth-Broker. Der Broker hält den zentralen Microsoft-Developer-Token, du verbindest dein Konto in zwei Minuten über die normale Microsoft-Consent-Seite.

Warum ein Broker

Die Microsoft-Advertising-API verlangt einen Developer-Token bei jedem Conversion-Upload. Genehmigung zwei bis vier Wochen. Beaconry betreibt einen zentralen Cloudflare-Worker (denselben, der auch Google-Ads-OAuth abwickelt), der einen genehmigten Developer-Token für dich hält. Du verbindest dein eigenes Microsoft-Konto via OAuth, der Broker proxied die OfflineConversions-Calls. Refresh-Tokens bleiben in der KV des Brokers, das Plugin speichert nur einen HMAC-signierten Site-Bearer.

Voraussetzungen

• Microsoft-Advertising-Account mit Super-Admin- oder Standard-User-Rolle.
• Microsoft-Konto (Arbeit, Schule oder persönliches MSA), das sich bei Microsoft Advertising anmelden kann.
• Etwa 5 Minuten.

1. Mit Microsoft Advertising verbinden

WordPress-Admin → Beaconry → Tracking → Microsoft Ads. Klick Microsoft-Konto verbinden. Du wirst auf login.microsoftonline.com weitergeleitet.

Mit dem Microsoft-Konto anmelden, das Zugriff auf deine Microsoft-Advertising-Daten hat. Den geforderten Scope (msads.manage + offline_access) auf der Consent-Seite genehmigen. Microsoft leitet zurück auf den Tracking-Tab, der Broker speichert den Refresh-Token unter einer opaken Site-ID. Beaconry hält nur den resultierenden Site-Bearer, verschlüsselt mit AES-256-GCM.

Der Broker nutzt Microsoft Identity Platform v2.0 auf dem Multi-Tenant-/common-Endpoint, also funktionieren sowohl AAD-Konten (Arbeit, Schule) als auch persönliche MSAs, der häufigste Bing-Ads-Fall.

2. Customer-ID und Account-ID finden

Microsoft Advertising adressiert ein Konto über zwei numerische IDs, beide Pflicht.

• Microsoft Advertising öffnen (ads.microsoft.com).
• Oben rechts im Account-Switcher steht deine Customer-ID (der Parent-Customer-Scope, also das Manager-Konto).
• Darunter die Account-ID für das eigentliche Bing-Ads-Konto, das deine Kampagnen fährt.
• Beide in Beaconry → Customer-ID und Account-ID auf dem Tracking-Tab eintragen. Beide sind 6- bis 12-stellige Zahlen, Beaconry entfernt Formatierungs-Zeichen automatisch.

3. Conversion-Goals in Microsoft Ads anlegen

Microsoft adressiert Conversions per Goal-Name, nicht per numerischer ID. Du benennst ein Goal einmal in der Microsoft-Advertising-UI und referenzierst es als String aus Beaconry.

• Microsoft Advertising → Tools → Conversion-Tracking → Conversion-Goals → Conversion-Goal anlegen.
• Goal-Typ: Offline-Conversion. Nicht "Event", das verdrahtet nur das Browser-UET-Tag.
• Eine zum Event passende Kategorie wählen (Purchase, Add to cart, Begin checkout, Lead, Subscribe, Schedule, Sign up, Contact).
• Wert-Modell und Attributions-Fenster nach Microsofts Empfehlung setzen.
• Speichern. Den Goal-Namen-String exakt wie eingetippt notieren, Beaconry referenziert ihn case-sensitive.

4. Goals auf Beaconrys Event-Slots mappen

Beaconry hat acht Slots, einen pro Conversion-Typ. Den passenden Goal-Namen in jeden Slot eintragen, den du tracken willst. Andere leer lassen.

5. Test-Event versenden

Speichern, klick Microsoft-Ads-Test-Event senden. Beaconry feuert eine synthetische Conversion über den Broker. HTTP 200 ohne Fehler heißt: Bearer, IDs und mindestens ein Goal-Name passen.

Microsoft Advertising hat keine Echtzeit-Test-Ansicht wie Metas Test Events. Live-Conversions tauchen in Tools → Conversion-Tracking innerhalb von etwa 3 Stunden auf.

Über die Click-ID

Microsoft braucht eine msclkid (Microsoft Click ID) auf jeder Offline-Conversion, um sie zur Anzeige zurückzuführen. Bing-Such-Ads hängen automatisch ?msclkid=... an jede Klick-Landing-URL. Beaconry fängt sie beim ersten Page-Load und persistiert sie im nl_ext-Cookie neben gclid, fbclid und ttclid. Conversions ohne erfasste msclkid werden still übersprungen, so ist Microsofts API gebaut.

Hybrid-Modus, UET-Tag

Hybrid-Modus lädt das Microsoft-Universal-Event-Tracking-Tag (UET) im Browser parallel zum Server-Side-Dispatch. Beaconry sendet denselben Per-Event-eventId-String von beiden Seiten, damit Microsoft deduplizieren kann (UET unterstützt Event-Level-Dedup seit 2024). Bessere Match-Rate, etwas mehr Bytes für den Besucher. Standardmäßig aus.

Aktivieren in Beaconry → Tracking → Microsoft Ads → Hybrid-Modus. Zusätzlich UET-Tag-ID eintragen (die numerische ID, die Microsoft unter Tools → UET-Tag anzeigt).

Was automatisch versendet wird

• WooCommerce-Funnel: AddToCart, InitiateCheckout, Purchase, mit Bestellwert und Währung.
• Form-Leads: Kadence-Blocks-Form- und Fluent-Forms-Submissions auf den Lead-Slot gemappt.
• msclkid-Capture aus URL-Parametern bei Bing-Ad-Klick-Landings, persistiert in nl_ext.
• Gehashte PII (E-Mail, Telefon) Server-Side per Microsofts Enhanced-Conversions-Guidelines.
• Stabile Per-Order-Event-IDs für Hybrid-Mode-UET-Dedup.

Troubleshooting

• "AuthenticationTokenExpired": der Broker refreshed Access-Tokens automatisch, der zugrunde liegende Refresh-Token läuft aber nach 90 Tagen Inaktivität ab. Trennen, dann erneut Microsoft-Konto verbinden. Customer-ID, Account-ID und Goal-Slots bleiben konfiguriert.
• Conversions hochgeladen, Counter bleibt aber bei null: der Goal-Name in Beaconry stimmt nicht exakt mit dem in Microsoft Advertising überein (case-sensitive, inklusive Leerzeichen). Beide Seiten erneut prüfen.
• "MicrosoftClickId required": der Besucher kam ohne msclkid. Direkte Besuche und Besuche aus nicht-Bing-Quellen haben keine, das ist erwartet. Nur Bing-Ad-Klicks attributieren zurück.
• "Customer not authorized": das verbundene Microsoft-Konto hat keine Rolle auf der eingetragenen Customer-ID. Mit einem Konto neu verbinden, das Super-Admin- oder Standard-User-Zugriff auf den Customer hat.