X Ads, twq Universal Tag und Conversions API

Server-Side-Conversion-Tracking für X Ads (vormals Twitter Ads). Pixel-ID kombiniert mit Conversions-API-Key. Optional Hybrid-Modus, der das Browser-twq-Universal-Website-Tag parallel lädt, dedupliziert über conversion_id.

Voraussetzungen

• X-Ads-Manager-Account mit Account-Administrator- oder Ad-Manager-Rolle.
• Existierende Web-Conversion-Event-Quelle (das X-Pendant zu einem Pixel) an deiner Domain.
• Etwa 5 Minuten.

1. X-Pixel-ID finden

• X Ads Manager öffnen (ads.x.com).
• Tools → Conversion-Tracking → Web.
• Event-Quelle für diese Domain auswählen. Falls keine existiert, via Neue Event-Quelle hinzufügen → Web anlegen.
• Pixel-ID (alphanumerisch, etwa 5 bis 6 Zeichen, Format wie ojxyz) steht im Header der Event-Quelle. Kopieren.

2. Conversions-API-Key generieren

• Auf derselben Event-Quellen-Detail-Seite: Conversion-API → API-Key generieren.
• X liefert einen langlebigen Bearer-Token, scoped auf die Event-Quelle. Im Normalbetrieb läuft er nicht ab, kann aber manuell revoked werden.
• Der Key wird nur EINMAL angezeigt. Sofort kopieren. Es gibt keinen "später-abrufen"-Mechanismus, du müsstest revoken und neu generieren.

3. Credentials in Beaconry eintragen

WordPress-Admin → Beaconry → Tracking → X Ads. Pixel-ID und API-Key einfügen, speichern.

Der Key wird mit AES-256-GCM verschlüsselt gespeichert (gekoppelt an deine WordPress-Auth-Salts). Konstanten-Variante: BCNR_X_ADS_PIXEL_ID und BCNR_X_ADS_API_KEY in wp-config.php.

4. Test-Event versenden

Klick X-Ads-Test-Event senden. Beaconry feuert ein synchrones PageView via Conversions API und meldet die Antwort inline.

HTTP 200 ohne Fehler heißt: Credentials passen. Das Event taucht in Tools → Conversion-Tracking → Health innerhalb von etwa 30 Minuten auf. X Ads hat keine Echtzeit-Test-Ansicht wie Metas Test Events, der Health-Tab ist die Stelle, die du beobachtest.

Über die Click-ID

X hängt ?twclid=... (die X Click ID) an jede Ad-Klick-Landing-URL. Beaconry fängt sie beim ersten Page-Load und persistiert sie im nl_ext-Cookie neben fbclid, gclid, ttclid, msclkid und sc_at. Server-Side-Events tragen dann twclid für saubere Attribution. Ohne fällt X auf gehashte PII plus IP und User-Agent zurück.

Hybrid-Modus, twq Universal Tag

Server-Side-CAPI allein deckt 100 Prozent der zustimmenden Besucher. Hybrid-Modus lädt das Browser-twq-Universal-Website-Tag (static.ads-twitter.com/uwt.js) parallel, damit X die First-Party-Cookies des Besuchers sieht. Beaconry sendet dieselbe conversion_id von beiden Seiten als drittes Argument an twq('event', ..., {conversion_id: ...}), X dedupliziert gegen Doppel-Counting.

Aktivieren in Beaconry → Tracking → X Ads → Hybrid-Modus. Bessere Match-Rate, etwas mehr Bytes für den Besucher. Standardmäßig aus.

Was automatisch versendet wird

Beaconry mappt GA4-kanonische Events auf X' Standard-Event-Vokabular:

Alle Payloads tragen gehashte PII (em, ph, twitter_handle sobald verfügbar), die erfasste twclid, plus IP und User-Agent.

Troubleshooting

• "401 invalid_credentials": API-Key revoked oder unter einer anderen Event-Quelle generiert. Auf der Event-Quellen-Detail-Seite neu generieren und in Beaconry austauschen.
• "400 invalid_event_name": ein Custom-Event-Name wurde gesendet, der nicht zu X' Standard-Vokabular gehört. Beaconry sendet nur Standard-Namen aus der Tabelle oben. Custom NLData.track()-Events mit Nicht-Standard-Namen werden auf dem X-Kanal verworfen.
• Health-Tab zeigt null empfangene Events: ausgehender HTTP-Verkehr von deiner Origin zu ads-api.x.com könnte geblockt sein. WAF- oder Hosting-Firewall-Outbound-Regeln prüfen. Beaconrys Logs-Tab zeigt den vollen HTTP-Fehler.
• Counter springt nach Aktivieren des Hybrid-Modus: das dritte Argument an twq('event', ...) muss {conversion_id: ...} sein, nicht {eventID: ...}. X benutzt einen anderen Feld-Namen als Meta. Beaconrys Hybrid-Loader setzt den richtigen automatisch, aber prüfen, dass kein paralleles Custom-twq-Snippet mit dem falschen Feld läuft.