# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-05
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side-shopware/index.md), [it](https://www.datafirefly.com/it/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)
- Indeks:
## Wprowadzenie
DataFirefly Server-Side to darmowy konektor Shopware usługi [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). 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.
**Model biznesowy:** plugin jest darmowy; rozsyłanie zdarzeń wymaga abonamentu na usługę (Starter 39 EUR/mies., Growth 119 EUR/mies., Scale 349 EUR/mies.). Szczegóły i subskrypcja na [server-side.datafirefly.com](https://server-side.datafirefly.com/).
## 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
```
Plugin nie dodaje niczego do storefrontu: po instalacji nie jest potrzebny żaden `build-storefront`.
## Połączenie z usługą
### Uzyskanie klucza połączenia
1. Zaloguj się do panelu klienta na [server-side.datafirefly.com](https://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.
Klucz połączenia zawiera Twój sekret podpisu: traktuj go poufnie, jak hasło. W razie wycieku wygeneruj go ponownie w panelu klienta i podmień w konfiguracji pluginu.
### 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](https://www.datafirefly.com/pl/produkt/zgoda-na-cookies-rodo-consent-mode-shopware/) (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.
W razie wątpliwości plugin nie wysyła: to decyzja projektowa. Żadne zdarzenie nie może wyjść "przez przypadek" bez zgody, gdy bramka jest aktywna.
## 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=`: czyta konfigurację konkretnego sales channelu (domyślnie: konfiguracja globalna).
- `--source-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_`): 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_`), 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.