# DataFirefly Server-Side: kompletny przewodnik
> Kompletny przewodnik po darmowym module DataFirefly Server-Side dla PrestaShop 8 i 9: instalacja, dane uwierzytelniające, zdarzenie testowe, bramka zgody z Cookie Managerem i rozwiązywanie problemów.
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-05
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-server-side-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-server-side-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-server-side-prestashop/index.md)
- Indeks:
## Wprowadzenie
DataFirefly Server-Side to darmowy konektor PrestaShop do usługi [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/). Przy każdym zatwierdzonym zamówieniu moduł buduje kompletne zdarzenie zakupu i wysyła je z serwera na serwer, podpisane HMAC-SHA256, do dispatchera DataFirefly hostowanego w UE (Niemcy). Usługa rozsyła następnie zdarzenie do skonfigurowanych przez Ciebie miejsc docelowych: Meta Conversions API, GA4 Measurement Protocol, TikTok Events API, Pinterest Conversions API i Google Ads.
Podział ról jest prosty: moduł **przechwytuje i podpisuje**, usługa **przyjmuje, deduplikuje i rozsyła**. Moduł jest darmowy; rozsyłanie wymaga abonamentu na usługę (Starter od 39 € miesięcznie).
Awaria trackingu nigdy nie zepsuje Twojego checkoutu: moduł jest z założenia fail-safe (limity czasu 2 s / 4 s, błędy zapisywane w logach PrestaShop, żaden wyjątek nie trafia do ścieżki zamówienia).
## Wymagania
- PrestaShop 1.7.6 lub nowszy, 8.x albo 9.x
- PHP 7.4 lub nowszy, z rozszerzeniem cURL (obecne na niemal każdym hostingu)
- Aktywne konto DataFirefly Server-Side Tracking, subskrypcja na [server-side.datafirefly.com](https://server-side.datafirefly.com/)
- Zalecane: nasz moduł [DataFirefly Cookie Manager](https://www.datafirefly.com/pl/produkt/cookie-manager-tarteaucitron-zgodnosc-z-rodo-dla-prestashop/) (baner tarteaucitron zgodny z RODO wraz z Google Consent Mode v2) do natywnej bramki zgody
## Instalacja
1. Pobierz ZIP modułu ze swojego konta DataFirefly.
2. W panelu administracyjnym PrestaShop otwórz **Moduły > Menedżer modułów > Zainstaluj moduł** i wgraj plik `datafirefly_serverside.zip`.
3. Kliknij **Zainstaluj**. Moduł rejestruje się na hooku zatwierdzenia zamówienia; nie są potrzebne żadne override ani zmiany w szablonie.
Po instalacji tracking jest **wyłączony**, a wymóg zgody **włączony**: nic nie zostanie wysłane, dopóki nie skonfigurujesz i nie włączysz modułu.
## Pobranie danych uwierzytelniających
1. Zaloguj się do [panelu klienta DataFirefly](https://admin.datafirefly.com/app/login) (lub [wykup abonament](https://admin.datafirefly.com/pricing), jeśli jeszcze tego nie zrobiłeś).
2. Otwórz sekcję **Połącz swój sklep** dla swojej witryny.
3. Skopiuj trzy wyświetlone wartości: **Tenant ID** (w formacie `shop_twojsklep_xxxx`), **sekret HMAC** (64-znakowy klucz podpisujący) oraz **endpoint zdarzeń**.
Sekret HMAC to klucz prywatny: nie udostępniaj go i nie wklejaj nigdzie poza konfiguracją modułu. W razie wycieku wygeneruj go ponownie w panelu klienta.
## Konfiguracja
Otwórz **Moduły > Menedżer modułów > DataFirefly Server-Side > Konfiguruj**. Formularz zawiera pięć ustawień:
- **Włącz tracking**: główny przełącznik. Dopóki jest ustawiony na Nie, żadne zdarzenie nie jest wysyłane.
- **Tenant ID**: identyfikator Twojego sklepu w usłudze, skopiowany z panelu klienta.
- **Sekret HMAC**: 64-znakowy klucz podpisujący. Każde zdarzenie jest nim podpisywane przed wysyłką.
- **Events endpoint**: adres URL przyjmowania zdarzeń przez dispatchera. Wartość domyślna jest właściwa w niemal każdym przypadku; zmień ją tylko wtedy, gdy panel klienta wskazuje inną.
- **Wymagaj zgody**: włączone domyślnie. Gdy jest aktywne, zakup jest przekazywany wyłącznie wtedy, gdy odwiedzający wyraził zgodę marketingową (patrz niżej). Wyłącz je tylko wtedy, gdy obsługujesz zgody wcześniej innym rozwiązaniem.
Zapisz, a następnie przejdź do testu.
## Test połączenia
Kliknij **Wyślij zdarzenie testowe** w formularzu konfiguracji. Moduł wyśle syntetyczne, podpisane `page_view` do dispatchera, bez ingerencji w prawdziwe zamówienia.
- **„Zdarzenie testowe dostarczone" (HTTP 200)**: Twój Tenant ID, sekret i endpoint są poprawne. Sklep jest połączony, nawet jeśli po stronie usługi nie skonfigurowano jeszcze żadnego miejsca docelowego.
- **„Zdarzenie testowe nieudane"**: kod HTTP i komunikat dispatchera są wyświetlane w celu diagnozy (patrz Rozwiązywanie problemów).
## Zgoda (RODO)
Gdy opcja **Wymagaj zgody** jest aktywna, moduł odczytuje bezpośrednio po stronie serwera, w momencie zatwierdzenia zamówienia, cookie zgody w formacie tarteaucitron zapisane przez nasz moduł [DataFirefly Cookie Manager](https://www.datafirefly.com/pl/produkt/cookie-manager-tarteaucitron-zgodnosc-z-rodo-dla-prestashop/) (Google Consent Mode v2). Nazwa cookie jest automatycznie pobierana z konfiguracji Cookie Managera (domyślnie `tarteaucitron`).
Zakup jest przekazywany, jeśli odwiedzający wyraził zgodę na **co najmniej jedną usługę reklamową**: Meta Pixel, Google Ads, TikTok Pixel lub LinkedIn Insight. Podejście jest privacy-first: brak cookie albo cookie nieczytelne oznacza brak wysyłki.
To zalecane połączenie w PrestaShop: Cookie Manager obsługuje baner, Consent Mode v2 i dowód zgody, a ten moduł stosuje tę samą decyzję do trackingu server-side. Jedno źródło prawdy dla całego łańcucha.
Jeśli obsługujesz zgody innym rozwiązaniem, wyłącz **Wymagaj zgody** i zastosuj własną logikę wcześniej: wtedy to Twoje rozwiązanie odpowiada za to, aby żadne zamówienie nie pochodziło od odwiedzającego bez zgody.
## Co jest wysyłane
Przy każdym zatwierdzonym zamówieniu moduł buduje zdarzenie `purchase` zawierające:
- **Transakcja**: zapłacona kwota, waluta ISO, numer zamówienia, produkty (id, nazwa, ilość, cena jednostkowa brutto) oraz łączna liczba pozycji.
- **Dane dopasowania**: e-mail i identyfikator klienta, telefon, imię, nazwisko, miasto, kod pocztowy i kraj ISO z adresu rozliczeniowego (z fallbackiem na adres dostawy).
- **Identyfikatory przeglądarki** przechwycone w momencie zamówienia: `_fbp` i `_fbc` (Meta), `_ttp` (TikTok) oraz client id GA4 wyodrębniony z cookie `_ga`.
Każde pole opcjonalne jest dodawane wyłącznie wtedy, gdy jest obecne i poprawne: dispatcher waliduje ściśle, a dobrze zbudowane zdarzenie to zdarzenie dostarczone. Identyfikator zdarzenia jest powiązany z zamówieniem (`order_ID`) w sposób idempotentny, i to on umożliwia deduplikację klient plus serwer po stronie platform, jeśli używasz równolegle tagów przeglądarkowych.
Po stronie transportu każde żądanie niesie trzy nagłówki: tenant, znacznik czasu (weryfikowany w oknie anty-replay o długości 300 sekund) oraz podpis HMAC-SHA256 dokładnej treści żądania. Twoje dane uwierzytelniające Meta, GA4, TikTok, Pinterest i Google Ads pozostają w panelu DataFirefly: nie widzi ich ani sklep, ani przeglądarka.
## Podgląd zdarzeń po stronie usługi
W panelu klienta **Event Inspector** pokazuje zdarzenia pojedynczo, z zamaskowanymi danymi osobowymi (zgodnie z RODO). Sprawdzisz tam, co faktycznie trafia do każdego miejsca docelowego. Dostępność platform jest widoczna w każdej chwili na [publicznej stronie statusu](https://serverside.datafirefly.com/status).
## Rozwiązywanie problemów
### Zdarzenie testowe kończy się błędem „not_configured"
Jedno z trzech pól (Tenant ID, sekret, endpoint) jest puste. Skopiuj ponownie wszystkie trzy wartości z panelu klienta i zapisz przed kolejnym testem.
### Zdarzenie testowe kończy się błędem HTTP 401 lub 403
Podpis został odrzucony: sekret HMAC nie odpowiada tenantowi albo Tenant ID jest błędny. Skopiuj obie wartości bez spacji i znaków końca wiersza. Sprawdź też, czy zegar serwera jest poprawny (NTP): przesunięcie większe niż 300 sekund powoduje odrzucenie w oknie anty-replay.
### Zdarzenie testowe kończy się błędem „curl: …" albo HTTP 0
Twój serwer nie może połączyć się z dispatcherem: firewall wychodzący, DNS albo proxy. Zezwól na wychodzące połączenia HTTPS do endpointu wskazanego w panelu klienta.
### Test przechodzi, ale zamówienia nie docierają
- Sprawdź, czy **Włącz tracking** jest ustawione na Tak.
- Jeśli **Wymagaj zgody** jest aktywne, przekazywane są wyłącznie zamówienia odwiedzających, którzy wyrazili zgodę na usługę reklamową. Złóż zamówienie testowe po zaakceptowaniu cookies reklamowych w banerze.
- Zajrzyj do **Ustawienia zaawansowane > Logi** w panelu administracyjnym: każde niepowodzenie dostarczenia jest tam zapisane wraz z kodem HTTP i numerem zamówienia (prefiks `[DataFirefly SS]`).
### Konwersje liczone są dwukrotnie
Po stronie modułu to niemożliwe: identyfikator zdarzenia jest idempotentny na zamówienie. Jeśli używasz również tagów przeglądarkowych poza usługą, upewnij się, że wysyłają ten sam identyfikator zdarzenia (`order_ID`), aby platformy mogły deduplikować.
## Deinstalacja
Deinstalacja usuwa całą konfigurację modułu (tenant, sekret, endpoint, ustawienia). W bazie nie są tworzone żadne tabele: moduł nie przechowuje niczego poza swoją konfiguracją.