DataFirefly Server-Side: kompletny przewodnik

Wprowadzenie

DataFirefly Server-Side to darmowy konektor PrestaShop do usługi DataFirefly Server-Side Tracking. 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).

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
• Zalecane: nasz moduł DataFirefly Cookie Manager (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 (lub wykup abonament, 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ń.

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 (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.

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.

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ą.