DataFirefly Server-Side für Shopware — Komplette Anleitung

Überblick

DataFirefly Server-Side ist der kostenlose Shopware-Connector für den Dienst DataFirefly Server-Side Tracking. Bei jeder aufgegebenen Bestellung baut das Plugin ein vollständiges Kauf-Event auf und sendet es Server-zu-Server, signiert mit HMAC-SHA256, an den in der EU gehosteten DataFirefly-Dispatcher. Der Dienst nimmt das Event entgegen, dedupliziert es und liefert es an Ihre Ziele aus: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API und Google Ads.

Das Plugin ist auf Shop-Seite bewusst minimal: Es speichert keine Ziel-Credentials, fügt dem Storefront kein Skript hinzu und legt keine Tabelle an. Es erfasst, baut, signiert, sendet — alles Weitere passiert auf Dienstseite.

Voraussetzungen

• Shopware 6.5.x, 6.6.x oder 6.7.x (selbstgehostete Installation — Shopware Cloud akzeptiert keine Server-Plugins)
• PHP 8.1 oder höher, je nach Shopware-Version, mit der curl-Erweiterung
• Ein aktives Abonnement des Dienstes DataFirefly Server-Side Tracking, um Ihren Verbindungsschlüssel zu erhalten

Installation

Per ZIP-Upload

1. Öffnen Sie in der Shopware-Administration Erweiterungen → Meine Erweiterungen → Erweiterung hochladen und wählen Sie die ZIP-Datei des Plugins.
2. Klicken Sie auf Installieren, dann auf Aktivieren.

Über die Kommandozeile

bin/console plugin:refresh
bin/console plugin:install --activate DatafireflyServerSide
bin/console cache:clear

Verbindung mit dem Dienst

Verbindungsschlüssel abrufen

1. Melden Sie sich in Ihrem Kundenbereich auf server-side.datafirefly.com an.
2. Öffnen Sie den Bereich Shop verbinden.
3. Kopieren Sie den einzeiligen Verbindungsschlüssel im Format dfss_…. Er kodiert Ihre Tenant-ID, Ihren HMAC-Signaturschlüssel und den Ingestion-Endpunkt.

Schlüssel in Shopware einfügen

1. Öffnen Sie Erweiterungen → Meine Erweiterungen → DataFirefly Server-Side → Konfiguration.
2. Fügen Sie den Schlüssel in das Feld Verbindungsschlüssel ein.
3. Aktivieren Sie den Schalter Tracking aktivieren und speichern Sie.

Das war’s: Ab der nächsten aufgegebenen Bestellung geht das Kauf-Event an den Dispatcher. Ein fehlender oder fehlerhafter Schlüssel ist nie ein blockierender Fehler — das Plugin betrachtet sich einfach als nicht konfiguriert und sendet nichts.

Konfiguration

• Tracking aktivieren — Hauptschalter. Standardmäßig aus.
• Verbindungsschlüssel — der dfss_…-Schlüssel aus Ihrem Kundenbereich.
• Marketing-Einwilligung erforderlich — aktiviert das Einwilligungs-Gate (standardmäßig aus, siehe unten).
• Name des Einwilligungs-Cookies — das Cookie, das Ihr Consent-Tool (CMP) setzt.
• Wert des Einwilligungs-Cookies (enthält) — optional: erwartetes Wertfragment im Cookie.

Die Konfiguration erfolgt pro Sales Channel: Sie können das Tracking in einem Shop aktivieren und in einem anderen nicht, oder unterschiedliche Schlüssel pro Kanal verwenden.

Einwilligungs-Gate

Der Shopware-Core setzt nativ kein einzelnes serverseitig lesbares Marketing-Einwilligungs-Cookie. Das Plugin bietet daher ein generisches Gate, standardmäßig deaktiviert: Ist es aktiv, wird das Kauf-Event nur gesendet, wenn das konfigurierte Cookie in der Anfrage des Kunden vorhanden ist — und, falls ein erwarteter Wert gesetzt ist, nur wenn der Cookie-Wert ihn enthält.

Mit DataFirefly Cookie Consent

Die empfohlene Kombination auf Shopware ist unser Plugin DataFirefly Cookie Consent (DSGVO-konformes Banner mit nativem Google Consent Mode v2): Aktivieren Sie das Gate und tragen Sie den Namen des vom Banner gesetzten Einwilligungs-Cookies ein (in dessen Dokumentation angegeben). Eine verweigerte oder fehlende Marketing-Einwilligung blockiert den Versand serverseitig, vor jeder Übertragung.

Mit einem anderen CMP

Tragen Sie den Namen des Cookies ein, das Ihr CMP setzt, wenn der Besucher Marketing-Cookies akzeptiert (z. B. CookieConsent bei Cookiebot), und optional ein Wertfragment (z. B. marketing:true). Setzt Ihr CMP kein serverseitig lesbares Cookie, oder verwalten Sie die Einwilligung vollständig vorgelagert, lassen Sie das Gate deaktiviert.

Privacy-first-Verhalten

• Gate aktiv + kein Cookie-Name konfiguriert → nichts wird gesendet.
• Gate aktiv + Cookie fehlt oder ist leer → nichts wird gesendet.
• Gate aktiv + erwarteter Wert konfiguriert, aber nicht im Cookie-Wert enthalten → nichts wird gesendet.
• Keine Anfrage verfügbar (CLI- oder Headless-Flows ohne HTTP-Anfrage) → nichts wird gesendet.

Verbindung testen

Das Plugin liefert einen Konsolenbefehl mit, der ein synthetisches page_view an den Dispatcher sendet, ohne echte Bestellungen anzufassen:

bin/console datafirefly:serverside:test

Verfügbare Optionen:

• --sales-channel-id=<id> — liest die Konfiguration eines bestimmten Sales Channels (Standard: globale Konfiguration).
• --source-url=<url> — nimmt eine sourceUrl in das Test-Event auf.

Ein HTTP-Code 2xx bestätigt, dass Verbindungsschlüssel, Signatur und Endpunkt korrekt sind — auch wenn auf Dienstseite noch kein Ziel konfiguriert ist.

Funktionsweise

Das Purchase-Event

Das Plugin abonniert das Bestell-Event von Shopware. Bei jedem Auslösen baut es ein purchase-Event mit einer idempotenten, bestellbasierten ID (order_<id>): Setzen Sie zusätzlich Browser-Tags ein, wendet der Dienst die Client-plus-Server-Deduplizierung an und jede Conversion wird nur einmal gezählt.

Gesendete Daten

• Transaktion: gezahlter Wert, Währung, Bestellnummer, Produkte, Mengen, Artikelanzahl.
• Matching: E-Mail, Kunden-ID, Telefon, Vorname, Nachname, Stadt, Postleitzahl und Land der Rechnungsadresse.
• Browser-Identifier zum Bestellzeitpunkt erfasst: _fbp, _fbc, _ttp und die GA4 Client-ID (Cookie _ga).

Der Aufbau ist defensiv: Jedes optionale Feld wird nur hinzugefügt, wenn es vorhanden und gültig ist (der Dispatcher validiert strikt — Land mit 2 Zeichen, Währung mit 3 usw.). In Headless-Flows, in denen manche Bestell-Assoziationen fehlen können, werden die entsprechenden Felder einfach weggelassen, nie fabriziert.

HMAC-Signierung

Jedes Event wird mit HMAC-SHA256 und dem Secret Ihres Tenants signiert: Die signierten Bytes sind exakt die gesendeten Bytes, mit einem Zeitstempel, der in einem 300-Sekunden-Anti-Replay-Fenster geprüft wird. Übertragen werden die Header Tenant-ID, Timestamp und Signatur. Ihre Meta-, GA4-, TikTok-, Pinterest- und Google-Ads-Credentials bleiben auf Dienstseite — nie im Shop, nie im Browser.

Fail-safe

Das gesamte Subsystem ist so konzipiert, dass es den Checkout nie beeinträchtigt: Timeouts von 2 Sekunden (Verbindung) und 4 Sekunden (gesamt), alle Fehler abgefangen und als Warning in den Shopware-Logs protokolliert, mit HTTP-Code und Bestellnummer — keine Exception erreicht je den Bestellprozess.

Fehlerbehebung

• Kein Event geht raus — prüfen Sie, dass der Schalter für den richtigen Sales Channel aktiviert ist, dass der Schlüssel mit dfss_ beginnt, ohne Leerzeichen oder Zeilenumbrüche, und dass das Einwilligungs-Gate nicht ohne konfiguriertes Cookie aktiv ist.
• Der Testbefehl schlägt fehl — ein Code 0 mit einer curl-Meldung deutet auf ein ausgehendes Netzwerkproblem hin (Firewall); ein 401/403 auf einen ungültigen oder regenerierten Schlüssel: Kopieren Sie ihn erneut aus dem Kundenbereich.
• Events in den Logs als nicht zugestellt markiert — HTTP-Code und Bestellnummer werden in den Shopware-Logs protokolliert (Warning-Kanal). Ein 4xx-Code bedeutet, dass das Payload von der strikten Validierung des Dispatchers abgelehnt wurde; Details finden Sie im Event Inspector Ihres Kundenbereichs.
• Doppelte Conversions bei Meta oder GA4 — stellen Sie sicher, dass Ihre Browser-Tags dieselbe Event-ID (order_<id>) senden, um von der Deduplizierung zu profitieren.

Changelog

• 1.0.0 (01.07.2026) — Erstveröffentlichung: idempotentes serverseitiges Purchase-Event, HMAC-SHA256-Signierung mit Anti-Replay-Fenster, einzeiliger Verbindungsschlüssel, Opt-in-Einwilligungs-Gate per CMP-Cookie, Konfiguration pro Sales Channel, Test-Konsolenbefehl, Fail-safe-Design.