DataFirefly Server-Side dla Shopware: kompletny przewodnik

Wprowadzenie

DataFirefly Server-Side to darmowy konektor Shopware usługi DataFirefly Server-Side Tracking. Przy każdym zatwierdzonym zamówieniu plugin buduje kompletne zdarzenie zakupu i wysyła je z serwera na serwer, podpisane HMAC-SHA256, do dispatchera DataFirefly hostowanego w UE. Usługa przyjmuje zdarzenie, deduplikuje je i rozsyła do Twoich destynacji: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API i Google Ads.

Plugin jest celowo minimalistyczny po stronie sklepu: nie przechowuje żadnych danych dostępowych destynacji, nie dodaje żadnego skryptu do storefrontu, nie tworzy żadnej tabeli. Przechwytuje, buduje, podpisuje, wysyła; reszta dzieje się po stronie usługi.

Wymagania

• Shopware 6.5.x, 6.6.x lub 6.7.x (instalacja self-hosted; Shopware Cloud nie przyjmuje pluginów serwerowych)
• PHP 8.1 lub nowszy, zależnie od wersji Shopware, z rozszerzeniem curl
• Aktywny abonament na usługę DataFirefly Server-Side Tracking w celu uzyskania klucza połączenia

Instalacja

Przez przesłanie ZIP

1. W administracji Shopware otwórz Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie i wybierz plik ZIP pluginu.
2. Kliknij Zainstaluj, a następnie Aktywuj.

Z wiersza poleceń

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

Połączenie z usługą

Uzyskanie klucza połączenia

1. Zaloguj się do panelu klienta na server-side.datafirefly.com.
2. Otwórz sekcję Połącz swój sklep.
3. Skopiuj jednoliniowy klucz połączenia w formacie dfss_…. Koduje on identyfikator tenanta, sekret podpisu HMAC i endpoint ingestii.

Wklejenie klucza w Shopware

1. Otwórz Rozszerzenia → Moje rozszerzenia → DataFirefly Server-Side → Konfiguracja.
2. Wklej klucz w pole Klucz połączenia.
3. Włącz przełącznik Włącz tracking i zapisz.

To wszystko: od najbliższego zatwierdzonego zamówienia zdarzenie zakupu leci do dispatchera. Brakujący lub źle sformatowany klucz nigdy nie jest błędem blokującym: plugin po prostu uznaje, że nie jest skonfigurowany, i niczego nie wysyła.

Konfiguracja

• Włącz tracking: główny przełącznik. Domyślnie wyłączony.
• Klucz połączenia: klucz dfss_… skopiowany z panelu klienta.
• Wymagaj zgody marketingowej: aktywuje bramkę zgody (domyślnie wyłączona, patrz niżej).
• Nazwa cookie zgody: cookie zapisywane przez Twoje narzędzie do zarządzania zgodami (CMP).
• Wartość cookie zgody (zawiera): opcjonalnie fragment wartości oczekiwany w cookie.

Konfiguracja jest zarządzana per sales channel: możesz włączyć tracking w jednym sklepie, a w innym nie, albo używać różnych kluczy per kanał.

Bramka zgody

Shopware nie zapisuje natywnie pojedynczego cookie zgody marketingowej czytelnego po stronie serwera. Plugin oferuje więc generyczną bramkę, domyślnie wyłączoną: gdy jest aktywna, zdarzenie zakupu wysyłane jest tylko wtedy, gdy skonfigurowane cookie występuje w żądaniu klienta, a jeśli podano oczekiwaną wartość, tylko gdy wartość cookie ją zawiera.

Z DataFirefly Cookie Consent

Zalecana kombinacja na Shopware to nasz plugin DataFirefly Cookie Consent (baner RODO z natywnym Google Consent Mode v2): włącz bramkę i wpisz nazwę cookie zgody zapisywanego przez baner (podaną w jego dokumentacji). Odmowa lub brak zgody marketingowej blokuje wysyłkę po stronie serwera, przed jakąkolwiek transmisją.

Z innym CMP

Wpisz nazwę cookie, które Twój CMP zapisuje, gdy odwiedzający akceptuje cookies marketingowe (na przykład CookieConsent dla Cookiebota), i ewentualnie fragment wartości (na przykład marketing:true). Jeśli Twój CMP nie zapisuje cookie czytelnego po stronie serwera albo zarządzasz zgodą całkowicie wyżej w łańcuchu, pozostaw bramkę wyłączoną.

Zachowanie privacy-first

• Bramka aktywna + niezkonfigurowana nazwa cookie → nic nie jest wysyłane.
• Bramka aktywna + cookie nieobecne lub puste → nic nie jest wysyłane.
• Bramka aktywna + oczekiwana wartość skonfigurowana, ale nieobecna w wartości cookie → nic nie jest wysyłane.
• Brak żądania (przepływ CLI lub headless bez żądania HTTP) → nic nie jest wysyłane.

Test połączenia

Plugin dostarcza komendę konsoli, która wysyła syntetyczny page_view do dispatchera, nie dotykając prawdziwych zamówień:

bin/console datafirefly:serverside:test

Dostępne opcje:

• --sales-channel-id=<id>: czyta konfigurację konkretnego sales channelu (domyślnie: konfiguracja globalna).
• --source-url=<url>: dołącza sourceUrl do zdarzenia testowego.

Kod HTTP 2xx potwierdza, że klucz połączenia, podpis i endpoint są poprawne, nawet jeśli po stronie usługi nie skonfigurowano jeszcze żadnej destynacji.

Działanie techniczne

Zdarzenie purchase

Plugin subskrybuje zdarzenie zatwierdzenia zamówienia w Shopware. Przy każdym wyzwoleniu buduje zdarzenie purchase z idempotentnym identyfikatorem opartym na zamówieniu (order_<id>): jeśli używasz także tagów przeglądarkowych, usługa stosuje deduplikację klient + serwer i każda konwersja liczona jest tylko raz.

Wysyłane dane

• Transakcja: zapłacona wartość, waluta, numer zamówienia, produkty, ilości, liczba pozycji.
• Dopasowanie: e-mail, identyfikator klienta, telefon, imię, nazwisko, miasto, kod pocztowy i kraj z adresu rozliczeniowego.
• Identyfikatory przeglądarkowe przechwycone w momencie zamówienia: _fbp, _fbc, _ttp i client id GA4 (cookie _ga).

Budowa jest defensywna: każde pole opcjonalne jest dodawane tylko wtedy, gdy jest obecne i poprawne (dispatcher waliduje ściśle: kraj na 2 znakach, waluta na 3 itd.). W przepływach headless, w których niektóre asocjacje zamówienia mogą brakować, odpowiadające pola są po prostu pomijane, nigdy fabrykowane.

Podpis HMAC

Każde zdarzenie jest podpisane HMAC-SHA256 sekretem Twojego tenanta: podpisywane bajty są dokładnie bajtami wysyłanymi, ze znacznikiem czasu weryfikowanym w oknie 300 sekund przeciw powtórce (replay). Przekazywane nagłówki to identyfikator tenanta, timestamp i podpis. Twoje dane dostępowe Meta, GA4, TikTok, Pinterest i Google Ads pozostają po stronie usługi, nigdy w sklepie, nigdy w przeglądarce.

Fail-safe

Cały podsystem jest zaprojektowany tak, aby nigdy nie wpływać na checkout: timeouty 2 sekundy (połączenie) i 4 sekundy (łącznie), wszystkie błędy przechwytywane i logowane jako warning w logach Shopware z kodem HTTP i numerem zamówienia; żaden wyjątek nie przedostaje się do procesu składania zamówienia.

Rozwiązywanie problemów

• Żadne zdarzenie nie wychodzi: sprawdź, czy przełącznik jest włączony dla właściwego sales channelu, czy klucz zaczyna się od dfss_ bez spacji i znaku nowej linii oraz czy bramka zgody nie jest aktywna bez skonfigurowanego cookie.
• Komenda testowa kończy się błędem: kod 0 z komunikatem curl wskazuje problem z ruchem wychodzącym (firewall); kod 401/403 oznacza klucz nieprawidłowy lub wygenerowany ponownie: skopiuj go na nowo z panelu klienta.
• Zdarzenia oznaczone w logach jako niedostarczone: kod HTTP i numer zamówienia są logowane w logach Shopware (kanał warning). Kod 4xx sygnalizuje payload odrzucony przez ścisłą walidację dispatchera; szczegóły sprawdzisz w Event Inspectorze w panelu klienta.
• Zdublowane konwersje w Meta lub GA4: upewnij się, że Twoje tagi przeglądarkowe wysyłają ten sam identyfikator zdarzenia (order_<id>), aby skorzystać z deduplikacji.

Changelog

• 1.0.0 (01.07.2026): wersja początkowa: idempotentne zdarzenie purchase server-side, podpis HMAC-SHA256 z oknem anty-replay, jednoliniowy klucz połączenia, opcjonalna bramka zgody oparta na cookie CMP, konfiguracja per sales channel, konsolowa komenda testowa, konstrukcja fail-safe.