DataFirefly Server-Side — Vollständige Anleitung

Überblick

DataFirefly Server-Side ist der kostenlose PrestaShop-Connector für den Dienst DataFirefly Server-Side Tracking. Bei jeder validierten Bestellung baut das Modul ein vollständiges Kauf-Event und sendet es von Server zu Server, HMAC-SHA256-signiert, an den in der EU gehosteten DataFirefly-Dispatcher (Deutschland). Der Dienst liefert das Event anschließend an Ihre konfigurierten Ziele aus: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API und Google Ads.

Die Rollenteilung ist einfach: Das Modul erfasst und signiert, der Dienst nimmt entgegen, dedupliziert und liefert aus. Das Modul ist kostenlos; die Auslieferung erfordert ein Dienst-Abonnement (Starter ab 39 €/Monat).

Voraussetzungen

• PrestaShop 1.7.6 oder höher, 8.x oder 9.x
• PHP 7.4 oder höher, mit der cURL-Erweiterung (auf praktisch jedem Hosting vorhanden)
• Ein aktives DataFirefly-Server-Side-Tracking-Konto — abonnieren Sie auf server-side.datafirefly.com
• Empfohlen: unser Modul DataFirefly Cookie Manager (konformes tarteaucitron-Banner mit Google Consent Mode v2) für das native Consent-Gate

Installation

1. Laden Sie das Modul-ZIP aus Ihrem DataFirefly-Konto herunter.
2. Öffnen Sie im PrestaShop-Backoffice Module > Modul-Manager > Modul hochladen und legen Sie die Datei datafirefly_serverside.zip ab.
3. Klicken Sie auf Installieren. Das Modul registriert sich am Bestellvalidierungs-Hook; es sind keine Overrides oder Theme-Änderungen nötig.

Nach der Installation ist das Tracking deaktiviert und die Einwilligungspflicht aktiviert: Es wird nichts gesendet, bis Sie das Modul konfiguriert und aktiviert haben.

Zugangsdaten abrufen

1. Melden Sie sich in Ihrem DataFirefly-Kundenbereich an (oder abonnieren Sie, falls noch nicht geschehen).
2. Öffnen Sie den Bereich Shop verbinden Ihrer Site.
3. Kopieren Sie die drei angezeigten Werte: die Tenant-ID (im Format shop_ihrshop_xxxx), das HMAC-Secret (64-Zeichen-Signaturschlüssel) und den Events-Endpoint.

Konfiguration

Öffnen Sie Module > Modul-Manager > DataFirefly Server-Side > Konfigurieren. Das Formular hat fünf Einstellungen:

• Tracking aktivieren — der Hauptschalter. Solange er auf Nein steht, wird kein Event gesendet.
• Tenant-ID — die Kennung Ihres Shops im Dienst, kopiert aus Ihrem Kundenbereich.
• HMAC-Secret — der 64-Zeichen-Signaturschlüssel. Jedes Event wird vor dem Versand mit diesem Schlüssel signiert.
• Events-Endpoint — die Ingestion-URL des Dispatchers. Der Standardwert ist in praktisch allen Fällen richtig; ändern Sie ihn nur, wenn Ihr Kundenbereich einen anderen angibt.
• Einwilligung verlangen — standardmäßig aktiviert. Wenn aktiv, wird der Kauf nur weitergeleitet, wenn der Besucher eine Marketing-Einwilligung erteilt hat (siehe unten). Deaktivieren Sie dies nur, wenn Sie die Einwilligung vorgelagert mit einem anderen System verwalten.

Speichern Sie und fahren Sie mit dem Test fort.

Verbindung testen

Klicken Sie im Konfigurationsformular auf Testevent senden. Das Modul sendet ein signiertes, synthetisches page_view an den Dispatcher — ohne echte Bestellungen zu berühren.

• „Testevent zugestellt“ (HTTP 200): Ihre Tenant-ID, Ihr Secret und Ihr Endpoint sind korrekt. Ihr Shop ist verbunden, auch wenn dienstseitig noch kein Ziel konfiguriert ist.
• „Testevent fehlgeschlagen“: Der HTTP-Code und die Meldung des Dispatchers werden zur Diagnose angezeigt (siehe Fehlerbehebung).

Die Einwilligung (DSGVO)

Wenn Einwilligung verlangen aktiv ist, liest das Modul — direkt serverseitig, zum Zeitpunkt der Bestellvalidierung — das Einwilligungs-Cookie im tarteaucitron-Format, das von unserem Modul DataFirefly Cookie Manager (Google Consent Mode v2) gesetzt wird. Der Cookie-Name wird automatisch aus der Cookie-Manager-Konfiguration übernommen (Standard: tarteaucitron).

Der Kauf wird weitergeleitet, wenn der Besucher mindestens einem Werbedienst zugestimmt hat: Meta Pixel, Google Ads, TikTok Pixel oder LinkedIn Insight. Der Ansatz ist privacy-first: fehlendes oder unlesbares Cookie = kein Versand.

Wenn Sie die Einwilligung mit einem anderen System verwalten, deaktivieren Sie Einwilligung verlangen und wenden Sie Ihre eigene Logik vorgelagert an: Dann muss Ihr System garantieren, dass keine Bestellung von einem nicht einwilligenden Besucher stammt.

Was gesendet wird

Bei jeder validierten Bestellung baut das Modul ein purchase-Event mit:

• Transaktion: bezahlter Betrag, ISO-Währung, Bestellreferenz, Produkte (ID, Name, Menge, Brutto-Einzelpreis) und Gesamtzahl der Artikel.
• Match-Daten: E-Mail und Kunden-ID, Telefon, Vorname, Nachname, Stadt, PLZ und ISO-Land aus der Rechnungsadresse (Fallback auf die Lieferadresse).
• Browser-Identifier, erfasst zum Bestellzeitpunkt: _fbp und _fbc (Meta), _ttp (TikTok) und die GA4-Client-ID aus dem _ga-Cookie.

Jedes optionale Feld wird nur hinzugefügt, wenn es vorhanden und gültig ist: Der Dispatcher validiert strikt, und ein wohlgeformtes Event ist ein zugestelltes Event. Die Event-ID ist idempotent an die Bestellung gebunden (order_ID) — sie ermöglicht die Client-und-Server-Deduplizierung auf den Plattformen, falls Sie zusätzlich Browser-Tags einsetzen.

Auf dem Transportweg trägt jede Anfrage drei Header: den Tenant, den Zeitstempel (geprüft in einem 300-Sekunden-Anti-Replay-Fenster) und die HMAC-SHA256-Signatur des exakten Anfragekörpers. Ihre Zugangsdaten für Meta, GA4, TikTok, Pinterest und Google Ads bleiben in Ihrem DataFirefly-Bereich: Weder der Shop noch der Browser sehen sie jemals.

Ihre Events auf der Dienstseite überwachen

In Ihrem Kundenbereich zeigt Ihnen der Event Inspector die Events einzeln, mit maskierten personenbezogenen Daten (DSGVO-konform). Dort prüfen Sie, was tatsächlich an jedes Ziel ausgeliefert wird. Die Verfügbarkeit der Plattformen können Sie jederzeit auf der öffentlichen Statusseite einsehen.

Fehlerbehebung

Das Testevent schlägt mit „not_configured“ fehl

Eines der drei Felder (Tenant-ID, Secret, Endpoint) ist leer. Kopieren Sie alle drei Werte erneut aus Ihrem Kundenbereich und speichern Sie vor dem erneuten Test.

Das Testevent schlägt mit HTTP 401 oder 403 fehl

Die Signatur wird abgelehnt: Das HMAC-Secret passt nicht zum Tenant, oder die Tenant-ID ist falsch. Kopieren Sie beide Werte erneut, ohne Leerzeichen oder Zeilenumbrüche. Prüfen Sie außerdem, ob die Uhr Ihres Servers korrekt ist (NTP): Eine Abweichung über 300 Sekunden lässt das Anti-Replay-Fenster fehlschlagen.

Das Testevent schlägt mit „curl: …“ oder HTTP 0 fehl

Ihr Server erreicht den Dispatcher nicht: ausgehende Firewall, DNS oder Proxy. Erlauben Sie ausgehende HTTPS-Verbindungen zum in Ihrem Kundenbereich angegebenen Endpoint.

Der Test besteht, aber keine Bestellungen kommen an

• Prüfen Sie, ob Tracking aktivieren auf Ja steht.
• Wenn Einwilligung verlangen aktiv ist, werden nur Bestellungen von Besuchern weitergeleitet, die einem Werbedienst zugestimmt haben. Geben Sie eine Testbestellung auf, nachdem Sie im Banner die Werbe-Cookies akzeptiert haben.
• Prüfen Sie Erweiterte Einstellungen > Logs im Backoffice: Jeder Zustellungsfehler wird dort mit HTTP-Code und Bestell-ID protokolliert (Präfix [DataFirefly SS]).

Conversions werden doppelt gezählt

Modulseitig nicht möglich: Die Event-ID ist pro Bestellung idempotent. Falls Sie außerhalb des Dienstes zusätzlich Browser-Tags einsetzen, stellen Sie sicher, dass sie dieselbe Event-ID (order_ID) senden, damit die Plattformen deduplizieren.

Deinstallation

Die Deinstallation entfernt die gesamte Konfiguration des Moduls (Tenant, Secret, Endpoint, Einstellungen). Es wird keine Datenbanktabelle angelegt: Das Modul speichert nichts außer seiner Konfiguration.