Troubleshooting

Pixel feuert nicht, fehlende Conversions, OAuth-Errors, Plugin-Konflikte. Die häufigsten Stolperer in der Reihenfolge, in der sie typisch auftreten.

Beaconry-Events kommen in keiner Plattform an

Hier anfangen, wenn nichts läuft.

1. Site in einem frischen Browser öffnen, Consent-Banner akzeptieren.
2. DevTools → Network-Tab. Page neu laden.
3. Nach POST an /wp-json/beaconry/v1/event suchen. Status 202 heißt "in Dispatch-Queue".
4. Falls der Request fehlt: Consent abgelehnt oder der Banner ist falsch konfiguriert. Beaconry → Tracking → Dashboard → "Consent-State"-Pill checken.
5. Bei HTTP 4xx: WordPress-REST ist kaputt (anderes Plugin filtert /wp-json/). Andere Plugins einzeln deaktivieren.
6. Bei 202 aber keine Plattform-Conversion: Beaconry → Logs öffnen. Plattform-Antwort wird mit vollem Request- und Response-Payload pro Event geloggt.

Meta, Events kommen via CAPI an, aber Match-Quality "Schlecht"

Beaconry sendet die richtigen gehashten PII-Felder. Meta braucht drei Trust-Signale, um sie zu nutzen:

• Domain-Verifizierung in Business-Einstellungen → Brand Safety → Domains.
• Trusted-Domains-Liste in Pixel → Einstellungen → Traffic-Berechtigungen.
• Aggregated Event Measurement mit Priority-Reihenfolge pro Domain.

Ohne diese drei nimmt Meta das Event auf, markiert es aber als "Schlecht". Setzen aller drei dauert ~10 Min in Meta und ist unabhängig von Beaconry.

TikTok, "code: 40005, content_id required"

Die TikTok-Events-API lehnt Events ohne content_id im contents[]-Array ab. Beaconry setzt das automatisch für WooCommerce-Events (die Produkt-SKU). Bei Custom-JS-Events content_id in contents[] einfügen, nicht auf Top-Level (TikTok ignoriert Top-Level-content_id).

Google Ads, "PERMISSION_DENIED"

Der Google-Account, der den OAuth-Handshake gemacht hat, hat keine Edit-Berechtigung auf der Customer-ID. Zwei Fixes:

• Google Ads → Tools → Zugriff und Sicherheit. Verifizieren, dass der verbindende Account mindestens "Standard"-Rolle auf dieser Customer-ID hat.
• Falls du einen Manager-(MCC)-Account genutzt hast: mit dem Manager-Account verbinden und in Beaconry die Sub-Account-Customer-ID angeben. Der OAuth-Scope muss den Manager abdecken.

Nach dem Fix nochmal Mit Google verbinden klicken, um neu zu authentifizieren.

Google Ads, Conversion hochgeladen aber im Campaign Manager nicht sichtbar

Google Ads hat bis zu 3 Stunden Conversion-Latenz. Es gibt keine Echtzeit-Test-Ansicht für die API. Warten, dann Campaign Manager → Tools → Conversions → Status-Spalte prüfen.

Falls nach 6 Stunden nichts erscheint: Beaconry → Logs öffnen, den Upload finden, die Antwort prüfen. partialFailureError mit Details heißt, Google hat die Zeile abgelehnt. Häufigster Grund: Conversion-Action ist pausiert (im Campaign Manager wieder aktivieren).

LinkedIn, "403 Forbidden"

Der LinkedIn-Account, der OAuth gemacht hat, hat keine Berechtigung auf dem Ad-Account. Account-Manager-, Campaign-Manager- oder Account-Billing-Admin-Rolle nötig. Viewer-Rolle wird abgelehnt.

Mit einem Account neu authentifizieren, der mindestens Campaign-Manager-Rolle hat.

LinkedIn, Token-Ablauf-Warnung

LinkedIn-Access-Tokens laufen nach 60 Tagen ab. Beaconrys Logs-Tab bekommt einen täglichen Heartbeat plus Warnung, wenn 7 Tage übrig sind. Mit LinkedIn verbinden klicken, um zu erneuern. Conversion-Rule-IDs und Ad-Account-ID bleiben konfiguriert, du wiederholst nur den OAuth-Handshake.

GA4, Events in Realtime aber fehlen in Standard-Reports

GA4-Standard-Reports haben 24 bis 48 Stunden Verarbeitungs-Delay. Realtime ist die Source-of-Truth für "ist das Event angekommen". Falls Realtime das Event zeigt, erscheint es morgen auch in Standard-Reports.

Tracking stoppt auf einem stundenlang offenen Tab oder auf gecachten Pages

Jeder Dispatch ist durch einen beaconry_event-Nonce geschützt, und WordPress-Nonces laufen ab (typisch nach 12 bis 24 Stunden). Auf einem über Nacht offen gelassenen Tab oder bei HTML aus einem Page-Cache wäre dieser Nonce normalerweise abgelaufen, wenn ein Besucher konvertiert. Beaconry erneuert den beaconry_event-Nonce client-seitig, damit lange offene Tabs und page-gecachtes HTML weiterhin gültige Events dispatchen, ohne Reload. Falls Dispatches nur nach langen Leerlauf-Phasen weiter fehlschlagen, prüfe, ob der Refresh-Request selbst nicht geblockt wird (eine zu aggressive Cache-Regel oder Firewall vor /wp-json/).

Mein Refund ist nicht in Meta oder Google Ads

Das ist Absicht. Refund-Events gehen nur an GA4, weil GA4 ein natives Refund-Event hat, das den erstatteten Umsatz gegen den ursprünglichen Kauf verrechnet. Die Ad-Kanäle (Meta, TikTok, LinkedIn, Google Ads, Microsoft Ads, Pinterest, X Ads, Snapchat, Reddit) haben kein echtes Refund-Event, also überspringt Beaconry sie lieber, als eins zu faken. Deine Conversion-Summen auf den Ad-Plattformen bleiben der reine Kauf-Count, und du verrechnest den Netto-Umsatz in GA4.

Form-Funnel-Zahlen (form_start / form_abandon)

Die Funnel-Signale form_start (erstes Feld fokussiert) und form_abandon (verlassen ohne Absenden) erscheinen nur in GA4, nie in den Ad-Kanälen. Es sind Analytics-Signale zum Messen von Drop-off, keine Conversions, also gibt es in Meta oder Google Ads nichts zu suchen.

Um den Drop-off pro Formular in GA4 zu lesen: filtere die Events nach dem Formular-Identifier und vergleiche dann den form_start-Count mit dem passenden Submission-Event für dasselbe Formular. Die Lücke ist dein Abbruch, und form_abandon markiert genau, welche Sessions ausgestiegen sind. Falls ein Formular form_start zeigt, aber überhaupt keine Submissions, feuert der Success-Hook des Formulars nicht (prüfe, ob das Completion-Event des Formular-Plugins Beaconry erreicht).

Plugin-Konflikte

• Cache-Plugins (W3 Total Cache, WP Rocket): sicherstellen, dass /wp-json/ vom Page-Cache ausgeschlossen ist. Die meisten WP-aware-Caches machen das per Default. Falls deins nicht, brechen Consent-Banner-Status und Event-Dispatch. Beaconry nimmt sein eigenes Inline-Script außerdem automatisch von der JS-Optimierung (Concatenation, Deferral, Delay-until-Interaction) auf LiteSpeed Cache, WP Rocket, SiteGround Optimizer und Cloudflare aus, damit die Nonce-Refresh- und Dispatch-Logik nie umsortiert oder gestrippt wird.
• Andere Tracking-Plugins (PixelYourSite, Tracking Plus, Sky GA4): nicht zwei Tracking-Plugins für dasselbe Ziel laufen lassen. Sie werden Events doppelt feuern. Entweder Beaconrys Kanal für die Plattform deaktivieren oder das andere Plugin komplett.
• Cookie-Consent-Plugins (CookieYes, Complianz): Beaconry hat seinen eigenen Consent-Banner (nl-data-gate). Falls du schon ein CMP hast, Beaconrys Banner in Beaconry → Banner auf "Hidden" stellen und über die API integrieren. Das CMP soll nl_pref = "{analytics: true}" setzen, sobald der Nutzer die Analytics-Kategorie akzeptiert.

WooCommerce-Events feuern nicht

1. Beaconry hookt in woocommerce_thankyou (Purchase), woocommerce_add_to_cart und woocommerce_before_checkout_form. In Beaconry → Logs verifizieren, dass die Hooks feuern.
2. Falls ein Hook in den Logs fehlt: Theme oder Plugin schneidet den WooCommerce-Flow ab. WooCommerce-Status → Tools → Logs auf Fehler während des Checkouts prüfen.
3. Custom-Thank-You-Pages: Beaconrys Purchase-Event feuert auf der Standard-WooCommerce-Thankyou-Vorlage. Falls du nach der Bestellung auf eine Custom-Page redirectest, musst du nlc.track('purchase', ...) dort manuell feuern.

"Mein Adblocker blockt Beaconry trotzdem"

Beaconrys /wp-json/beaconry/v1/event-Pfad ist strukturell adblock-immun. Falls du es geblockt siehst:

• URL in DevTools verifizieren. Ist es wirklich /wp-json/beaconry/v1/event auf deiner Domain, oder eine andere Domain? Falls anders, ist Hybrid-Modus für einen Kanal aktiv und der Pixel dieses Kanals lädt von einer Drittanbieter-Domain (DIE blockbar IST).
• Falls Hybrid-Modus die Ursache ist, deaktivieren. Server-Side-Dispatch deckt 100 % der zustimmenden Besucher wieder ab.

Im Zweifel: Logs prüfen

Beaconry → Logs hält die letzten 200 Events mit vollem Request- und Response-Payload. Filter nach Kanal, Event-Typ oder Status. Die meisten Issues sind aus der Plattform-Antwort im Log-Eintrag diagnostizierbar.

Für tieferes Debugging BCNR_DEBUG = true in wp-config.php setzen. Der Logs-Tab enthält dann auch WordPress' HTTP-Transport-Layer-Messages.

Steckst du fest?

E-Mail an info@beaconry.app mit dem betroffenen Kanal-Namen, dem relevanten Logs-Eintrag und einem Screenshot der Plattform-Antwort. Antwort üblich innerhalb eines Werktags.