Multi-Currency-Auto-Konvertierung

Verkauf in EUR, USD und GBP, Reporting in einer Währung. Beaconry hängt sich in die Dispatch-Pipeline und schreibt value + jeden items[].price in deine Ziel-Währung um, bevor das Event den Server verlässt, mit ECB-Tageskursen, einmal pro Tag gepullt.

Was es macht

Wenn dein Shop mehrere Währungen akzeptiert (WooCommerce Multi-Currency, Aelia, manueller Switcher, Geo-Routing), hast du auf jeder Werbeplattform dasselbe Reporting-Problem: Meta will eine Reporting-Währung, Google Ads will eine Reporting-Währung, dein CFO will eine Reporting-Währung. Ohne Normalisierung bekommst du Conversion-Summen über drei Buckets verteilt, die du dann in einer Tabelle addierst, mit FX-Kursen aus einem beliebigen Moment, den Meta sich gerade ausgedacht hat.

Multi-Currency normalisiert jede Transaktion im Flug. Die Original-Währung bleibt am Event als interne Annotation, sodass deine Debug-Logs und das Live-Dashboard weiterhin "92,59 EUR (USD)" zeigen können, falls du wissen willst, was tatsächlich abgerechnet wurde.

Wie aktivieren

wp-admin, Beaconry, Tab Advanced, Karte Multi-Currency Reporting. Ziel-Währung im Dropdown wählen (eine der ~30 ECB-publizierten Codes). Speichern. Standard ist "Disabled", damit gehen Events unverändert durch.

Power-User-Override: BCNR_CURRENCY_TARGET in wp-config.php setzen, um das Ziel über Deploys hinweg festzunageln, siehe "Konstanten für Power-User" unten.

Wie es funktioniert (unter der Haube)

1. Tägliche ECB-Pull. Ein WP-Cron-Event bcnr_currency_refresh holt die European-Central-Bank-Daily-Rates-XML von https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml (5-Sekunden-Timeout, offizielle vertrauenswürdige Quelle). Die geparste [code => rate]-Tabelle wird an zwei Stellen gecached: ein 24-Stunden-Transient bcnr_fx_rates für schnelle Reads und ein dauerhaftes autoload=false-Option bcnr_fx_rates_fallback, das einen Transient-Eviction überlebt.
2. Pre-Dispatch-Filter. BCNR_Currency::normalize_event() hängt sich an den bcnr_pre_dispatch_event-Filter mit Priorität 10. Läuft einmal pro Event, vor dem Fan-out an die Kanäle, sodass jeder Kanal denselben bereits normalisierten Wert sieht.
3. Cross-Currency-Mathe via EUR-Brücke. ECB veröffentlicht nur EUR-zu-X-Kurse. Um USD → GBP zu konvertieren, geht Beaconry USD → EUR (1 / rate[USD]) → GBP (× rate[GBP]). Same-Currency-Events sind ein No-Op-Pass-Through, Unknown-Currency-Events sind ein No-Op-Pass-Through (kein stilles Raten bei einem Tippfehler).
4. Annotation am Event. Nach Konvertierung werden _bcnr_fx_source (Original-ISO-Code) und _bcnr_fx_rate (angewandter Kurs) am Event-Payload ergänzt. Interne Felder, vor dem HTTP-Send von jeder Channel-dispatch_*-Methode entfernt (nur dokumentierte Meta- / GA4- / TikTok- / LinkedIn- / Google-Ads-Keys gehen aufs Wire). Sichtbar in der Recent-Events-Tabelle des Live-Dashboards und in bcnr_log bei Dispatch-Fehlern.
5. Outage-Handling. ECB hat gelegentlich Schluckauf gegen 16:00 CET (eigenes tägliches Publish-Fenster). Wenn der Pull fehlschlägt, fällt Beaconry auf den dauerhaften Cache zurück (letzter erfolgreicher Pull, oft Stunden alt, FX-Kurse ändern sich höchstens Bruchteile eines Prozents pro Tag). Wenn der dauerhafte Cache auch leer ist (Frischinstallation während eines ECB-Outage), gehen Events unverändert durch den Filter mit der Original-Währung, und ein Admin-Notice-Flag bcnr_fx_last_error wird gesetzt, sodass der nächste Page-Load dem Operator zeigt, was passiert ist. Dispatch crasht nie.

Konstanten für Power-User

BCNR_CURRENCY_TARGET in wp-config.php, Wert ist ein 3-Letter-ISO-4217-Code (Großbuchstaben). Wenn gesetzt, gewinnt die Konstante zur Read-Zeit gegen das DB-Setting, das Dropdown in der UI ist gesperrt mit Hinweis zurück zu wp-config.php. Nützlich für Staging-vs-Production-Parität, Infra-as-Code-Deploys und für den seltenen Fall, dass du eine nicht gelistete Währung willst, die nicht im ECB-Feed steht (die Konstante akzeptiert jeden ISO-Code, die Konvertierung verlangt aber weiterhin, dass Quelle und Ziel ECB-bekannt sind).

Troubleshooting

• "Meine Werte sehen unverändert aus": wahrscheinlich ist die Quell-Währung am Event leer (nicht-monetäres Event wie page_view) oder gleich dem Ziel. Beides ist ein No-Op per Design. Schau in die Recent-Events-Tabelle des Live-Dashboards, das konvertierte Event würde die _bcnr_fx_source- und _bcnr_fx_rate-Annotationen zeigen.
• "Admin-Notice sagt ECB nicht erreichbar": ECB-Outage. Beaconry probiert beim nächsten Cron-Tick erneut und erholt sich selbst. Existierende Events behalten ihre Original-Währung in der Zwischenzeit, keine Daten verloren. Bleibt der Hinweis länger als einen Tag stehen, prüfe ob wp_remote_get von deinem Server aus www.ecb.europa.eu erreichen kann (Firewall, ausgehendes HTTP).
• "Ich habe eine Ziel-Währung gewählt, das Dropdown ist jetzt gesperrt": BCNR_CURRENCY_TARGET ist in wp-config.php definiert. Konstante gewinnt gegen DB-Setting. Entweder wp-config.php editieren oder die Konstante löschen, wenn die UI das Steuern soll.
• "Kann ich einen Custom-Kurs nutzen": aktuell nicht freigelegt. Die Idee von Multi-Currency ist "eine vertrauenswürdige öffentliche Quelle, keine Operator-Überraschung". Wenn du einen handgerollten Kurs pro Markt brauchst, häng dich selbst an bcnr_pre_dispatch_event mit Priorität 9 (vor Beaconrys 10) und schreibe value + currency dort um.