# 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… - Seite: - Sprache: de - Aktualisiert am: 2026-07-01 - Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-server-side-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-server-side-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-server-side-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-server-side-shopware/index.md) - Index: ## Überblick DataFirefly Server-Side ist der kostenlose Shopware-Connector für den Dienst [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). 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. **Geschäftsmodell:** Das Plugin ist kostenlos; die Auslieferung der Events erfordert ein Abonnement des Dienstes (Starter 39 €/Monat, Growth 119 €/Monat, Scale 349 €/Monat). Details und Anmeldung auf [server-side.datafirefly.com](https://server-side.datafirefly.com/). ## 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 ``` Das Plugin fügt dem Storefront nichts hinzu: Nach der Installation ist kein `build-storefront` nötig. ## Verbindung mit dem Dienst ### Verbindungsschlüssel abrufen 1. Melden Sie sich in Ihrem Kundenbereich auf [server-side.datafirefly.com](https://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. Der Verbindungsschlüssel enthält Ihr Signatur-Secret: Behandeln Sie ihn vertraulich, wie ein Passwort. Bei einem Leak regenerieren Sie ihn im Kundenbereich und ersetzen ihn in der Plugin-Konfiguration. ### 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](https://www.datafirefly.com/de/produkt/df-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. Im Zweifel sendet das Plugin nicht: Das ist eine Design-Entscheidung. Kein Event kann „aus Versehen" ohne Einwilligung rausgehen, solange das Gate aktiv ist. ## 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=` — liest die Konfiguration eines bestimmten Sales Channels (Standard: globale Konfiguration). - `--source-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_`): 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_`) 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.