AIAI AdBaseChatGPT Ads Guide

Tutorial · Schritt 13 von 14

Fortgeschritten: Conversions API ergänzen

OpenAI Ads Conversions API als fortgeschrittenes Setup: Server-Events senden, event_id deduplizieren, API-Key sicher speichern und Conversion Map wiederverwenden.

Kurzfassung

Wenn Pixel, Consent und Conversion Map funktionieren, kann die Conversions API ergänzt werden. Sie sendet wichtige Abschluss-Events serverseitig an OpenAI und ist robuster als Pixel allein. Am saubersten ist das Setup, wenn Pixel und API dieselbe Conversion Map und dieselbe event_id für denselben Abschluss nutzen.

Ziel

Ziel: Nach Pixel, Consent und Conversion Map ein robusteres serverseitiges Conversion-Tracking planen.

Wann dieser Schritt relevant ist

  • Backend, Shop, CRM, Formular-Handler oder Server-Tagging ist verfügbar.
  • Käufe oder Leads sollen zuverlässiger gemessen werden als über den Browser allein.
  • Browser-Tracking reicht wegen Consent, Adblockern oder Browser-Limits nicht aus.
  • Offline- oder CRM-Qualifizierung soll später nachgemeldet werden.

Vorgehen

Pixel aus Schritt 10 testen und erst danach die API planen.

Consent-Situation aus Schritt 11 klären: Welche Events dürfen wann gesendet werden?

Conversion Map aus Schritt 12 finalisieren – sie ist die gemeinsame Quelle für Pixel und API.

Conversion-Schlüssel (Pixel ID, Conversions API Key) im Ads Manager im Conversions-Bereich verwalten.

API-Key nur serverseitig als Secret speichern, nie im Frontend oder Repository.

Server-Events nur nach echten Abschlüssen senden (bestätigter Kauf, bestätigter Lead).

Wenn Pixel und API dasselbe Event melden, dieselbe ID verwenden.

Logs und Fehlerantworten der API überwachen.

Pixel vs. Conversions API

  • Das Pixel misst browserseitig und ist schnell eingerichtet – ideal für Standard-Setups.
  • Die Conversions API sendet serverseitig aus Backend, Shop oder CRM und ist stabiler für bezahlte Käufe, bestätigte Leads, Buchungen oder spätere Qualifizierung.
  • Idealerweise ergänzen sich beide Spuren: Pixel für Reichweite und Signalgeschwindigkeit, API für Verlässlichkeit.

event_id und Deduplizierung

  • Wenn Browser-Pixel und Server-API denselben Kauf oder Lead melden, sendet das Browser-Event event_id: "order_12345".
  • Das Server-Event verwendet dieselbe ID als id.
  • So bleibt ein Abschluss ein Abschluss und wird nicht doppelt gezählt.

oppref / OpenAI Click Reference

  • Wenn eine Click Reference verfügbar ist, sollte sie durch Redirects, Formulare und Checkout-Strecken erhalten bleiben.
  • Serverseitig mitsenden, damit der Abschluss dem Klick zugeordnet werden kann.
  • Keine Werte erfinden: nur echte First-Party-Daten und erlaubte Daten verwenden.

Codebeispiele

  • Alle Werte sind Platzhalter – Pixel ID, Keys und Beträge müssen aus dem eigenen System kommen.
Server-Event per Conversions API senden
curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL_ID>" \
  -H "Authorization: Bearer <CONVERSIONS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "validate_only": false,
    "events": [
      {
        "id": "order_12345",
        "type": "order_created",
        "timestamp_ms": <EVENT_TIMESTAMP_MS>,
        "source_url": "https://example.com/checkout/confirmation",
        "action_source": "web",
        "data": {
          "type": "contents",
          "amount": 12999,
          "currency": "EUR"
        }
      }
    ]
  }'

Gleiche ID auf beiden Wegen – ein Abschluss bleibt ein Abschluss.

Browser-Pixel und Server-API deduplizieren
// Browser-Pixel auf der Danke-Seite
oaiq("measure", "order_created", {
  type: "contents",
  amount: 12999,
  currency: "EUR"
}, {
  event_id: "order_12345"
});

// Server-API für denselben Kauf: gleiche ID verwenden
{
  "id": "order_12345",
  "type": "order_created",
  "data": {
    "type": "contents",
    "amount": 12999,
    "currency": "EUR"
  }
}

Pro Route festhalten, welche Felder Event-ID und Betrag liefern.

Backend-Spezifikation aus der Conversion Map
{
  "route": "/danke-kauf",
  "openai_event": "order_created",
  "event_id_source": "order.id",
  "amount_cents_source": "order.total_cents",
  "currency": "EUR",
  "send_browser_pixel": true,
  "send_server_event": true,
  "deduplicate_with_event_id": true
}

Screenshots

Ads Manager Einstellungen mit Kontoinformationen, Verifizierung und API-Schlüssel Bereich.
In den Einstellungen sind API-Schlüssel sichtbar: In den Einstellungen sind API-Schlüssel sichtbar. Für die Conversions API werden Pixel ID und Conversions API Key aus dem Conversions-Bereich benötigt. Kontoname wurde anonymisiert.

Prüfpunkte

  • Pixel funktioniert nachweislich.
  • Backend-Zuständigkeit ist geklärt.
  • Pixel ID und Conversions API Key liegen vor.
  • API-Key ist ausschließlich als serverseitiges Secret gespeichert.
  • Events werden nur nach echten Abschlüssen gesendet.
  • oppref wird, wenn verfügbar, durchgereicht.
  • Pixel und API nutzen dieselbe event_id.
  • Consent und Datenschutz sind geprüft.
  • validate_only wird zum Testen verwendet, wenn möglich.
  • Fehlerlogs werden überwacht.

Häufige Fehler

  • API-Key im Frontend oder im Repository.
  • Pixel und API senden unterschiedliche IDs für denselben Abschluss.
  • Server-Event wird beim Button-Klick statt beim echten Abschluss gesendet.
  • amount nicht in Cent übergeben.
  • Conversion Map und API-Logik laufen inhaltlich auseinander.
  • Consent wird bei serverseitigen Events ignoriert.
  • Doppelte Events werden nicht geprüft.

Praxis-Hinweis

Nicht mit der API starten. Erst Pixel und Conversion Map verständlich machen, dann die API als robuste zweite Spur ergänzen.

Relevante Quellen