# DataFirefly Server-Side: kompletny przewodnik

> Kompletny przewodnik po instalacji, połączeniu i wykorzystaniu darmowego konektora DataFirefly Server-Side dla WooCommerce: śledzenie klient + serwer, deduplikacja, purchase server-side, zgody i abonament usługi.

- Strona: <https://www.datafirefly.com/pl/documentation/datafirefly-server-side/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-server-side/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-server-side/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-server-side/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

DataFirefly Server-Side to **darmowy** konektor WooCommerce usługi _DataFirefly Server-Side Tracking_. Wtyczka przechwytuje zdarzenia z Twojego sklepu i je podpisuje; usługa rozsyła je po stronie serwera do Twoich platform reklamowych i analitycznych. Ten przewodnik obejmuje instalację, połączenie, działanie ścieżki klient + serwer, deduplikację, purchase po stronie serwera, wybór destynacji klienckich, zarządzanie zgodami, niezawodność i abonament.

**Model: darmowa wtyczka + płatna usługa.** Wtyczka nic nie kosztuje i pozostanie darmowa. Aby zdarzenia rzeczywiście _wysyłać_, potrzebny jest abonament usługi DataFirefly Server-Side (od 39 €/miesiąc), która zapewnia przyjmowanie i dystrybucję server-side.

## Wymagania

- WordPress 5.8 lub nowszy
- WooCommerce 5.0 lub nowszy (zgodne z HPOS, czyli High-Performance Order Storage)
- PHP 7.4 lub nowszy
- Działający cron WordPressa (albo prawdziwy cron systemowy) dla kolejki ponowień i wysyłki odroczonej
- Abonament DataFirefly Server-Side, aby otrzymać klucz połączenia

## Instalacja

1. Pobierz plik `datafirefly-serverside-2_2_0.zip` ze swojego konta klienta DataFirefly.
2. W panelu WordPressa przejdź do **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**, wybierz ZIP i kliknij _Zainstaluj teraz_.
3. Włącz wtyczkę. W administracji pojawi się nowe menu **DataFirefly Server-Side**.

## Połączenie jednym kluczem

Moduł konfiguruje się jednym kluczem połączenia, który włącza jednocześnie śledzenie klienckie i serwerowe.

1. Ze swojego konta klienta DataFirefly skopiuj **klucz połączenia** (zaczyna się od `dfss_`).
2. Wklej go w przewidziane pole na ekranie _Połączenie_ wtyczki.
3. Kliknij **Połącz**. Moduł włącza śledzenie klienckie i serwerowe, wysyła zdarzenie testowe do dispatchera i uruchamia tagi klienckie dla skonfigurowanych destynacji.
4. Sprawdź, czy status zmienia się na **Połączono ✓**, i użyj przycisku _Testuj zdarzenie_, aby potwierdzić przepływ.

Klucz `dfss_…` koduje Twój tenant, sekret i endpoint dispatchera. Jest ograniczony do hostów `datafirefly.com` po HTTPS: klucz wskazujący inną domenę jest odrzucany.

### Tryb zaawansowany (wpis ręczny)

Jeśli wolisz nie korzystać z pojedynczego klucza, **tryb zaawansowany** pozwala wpisać ręcznie tenant, sekret i endpoint. Zarezerwuj go dla konfiguracji specyficznych: tryb jednego klucza pokrywa niemal wszystkie przypadki.

## Pełna ścieżka klient + serwer

Wtyczka śledzi całą ścieżkę po stronie przeglądarki, a konwersja zakupowa wychodzi po stronie serwera.

- **Po stronie przeglądarki:** `page_view`, `view_content` (widok produktu), `add_to_cart`, `initiate_checkout` i `add_payment_info`.
- **Po stronie serwera:** `purchase`, wyzwalany z hooków zamówienia WooCommerce.

Obie warstwy dzielą ten sam identyfikator zdarzenia, co umożliwia deduplikację.

### Zdarzenia merchandisingowe (od wersji 2.1.1)

Tracker obejmuje też merchandising katalogu: `view_item_list` (widok listy produktów, np. kategorii albo wyników wyszukiwania), `select_item` (kliknięcie produktu na liście), `view_promotion` i `select_promotion` (widok i kliknięcie promocji). Powiązany kontekst, czyli identyfikator i nazwa listy, identyfikator i nazwa promocji, kreacja i umiejscowienie, jest przekazywany do server-side, wzbogacając analizy ścieżek.

### Deduplikacja przez event_id

Dla każdego zamówienia zdarzenie klienckie i serwerowe niosą ten sam `event_id`, budowany na identyfikatorze zamówienia (na przykład `order_1042`). Meta, GA4 i pozostałe platformy opierają się na nim, żeby **policzyć każdą konwersję tylko raz**. Odzyskujesz więc konwersje gubione przez przeglądarkę, bez podwójnego liczenia.

## Wybór destynacji klienckich (Meta, GA4, TikTok)

Od wersji 2.2.0 każdy tag kliencki włącza się i wyłącza indywidualnie w ustawieniach wtyczki, w wierszu **Destynacje klienckie**:

- **Meta** (piksel Facebooka, `fbevents.js`)
- **Google Analytics 4** (`gtag.js`)
- **TikTok** (piksel TikToka)

Odznaczona destynacja **nigdy nie ładuje swojego skryptu zewnętrznego** w przeglądarce odwiedzających i **nigdy nie ustawia swoich ciasteczek**. Nie używasz Meta? Odznacz: mniej JavaScriptu, mniej żądań, szybsza i lżejsza strona. Destynacje nieskonfigurowane na Twoim koncie DataFirefly są sygnalizowane na ekranie ustawień.

Te pola dotyczą wyłącznie _tagów klienckich_. Dystrybucją server-side do Meta CAPI, GA4, TikToka, Pinteresta i Google Ads steruje konfiguracja Twojego konta w panelu klienta DataFirefly. Zwróć uwagę, że po wyłączeniu GA4 wtyczka nie ustawia już ciasteczka `_ga`, co obniża jakość dopasowania GA4 po stronie serwera; to spójne, jeśli GA4 nie używasz.

## Purchase server-side: niezawodny i niefałszowalny

Konwersja zakupowa jest wyzwalana z hooków zamówienia WooCommerce (płatność zakończona, w trakcie realizacji, zrealizowane), w sposób **idempotentny**: blokada (`_dfss_sent`) gwarantuje, że ten sam zakup nigdy nie zostanie wysłany dwa razy, nawet jeśli odpali się kilka hooków.

- Ponieważ zdarzenie wychodzi z serwera, żaden bloker reklam ani ITP nie może go zatrzymać.
- Z drugiej strony publiczny endpoint zbierania (beacon) **celowo wyklucza** zdarzenie `purchase`: nie da się wstrzyknąć fałszywego zakupu z przeglądarki, aby zawyżyć przychody w Meta czy GA4.
- Kontekst zdarzenia (wartość, waluta, produkty) jest rozstrzygany po stronie serwera: przeglądarka niczego nie „zgaduje".

Aby uwiarygodnić atrybucję nawet przy bramce płatności z przekierowaniem, wtyczka przechwytuje na checkoucie ciasteczka `_fbp`, `_fbc`, `_ga`, `_ttp` i wiąże je z zamówieniem, a także ustawia first-party ciasteczka click-id (90 dni), które przenoszą `fbc`, `ttclid` i `gclid` aż do zakupu.

## Zarządzanie zgodami

**Bramka zgody jest domyślnie włączona**: nic nie jest wysyłane, dopóki nie udzielono zgody marketingowej.

### Natywna zgodność z Cookie Consent v2

Wtyczka natywnie wykrywa moduł **DataFirefly Cookie Consent, RODO i Google Consent Mode v2** i czyta jego ciasteczko zgody (`dfcc_consent`) bezpośrednio po stronie serwera. Jeśli kategoria _marketing_ jest odrzucona, zdarzenie jest odrzucane, niezależnie od tego, co twierdzi przeglądarka. To zalecana kombinacja: baner, Consent Mode v2 i tracking server-side mówią jednym językiem.

### Inne rozwiązania zgód

W braku Cookie Consent v2 wtyczka obsługuje też **WP Consent API**, **Complianz**, **Cookiebot** i **IAB TCF v2**. Możesz zachować swój obecny baner i podłączyć do niego śledzenie.

## Niezawodność: kolejka ponowień i dziennik aktywności

Zdarzenie, które nie mogło zostać dostarczone, nie ginie: trafia do kolejki i jest **automatycznie wysyłane ponownie** przez crona co 5 minut.

**Dziennik aktywności** pokazuje na bieżąco, bez żargonu, co zostało dostarczone, co czeka w kolejce i co odrzucono, wraz z kodem HTTP i liczbą prób. To pierwszy odruch diagnostyczny.

Cron WordPressa uruchamia się tylko przy ruchu. W sklepie o niskim ruchu skonfiguruj prawdziwy cron systemowy wywołujący `wp-cron.php`, żeby kolejka ponowień opróżniała się regularnie.

## Bezpieczeństwo

- Żadnych sekretów w przeglądarce: po stronie klienta wystawiane są wyłącznie identyfikatory publiczne (piksel, measurement id).
- Sekret podpisu i Twoje dane dostępowe destynacji pozostają po stronie serwera.
- Każde zdarzenie jest podpisywane HMAC-em przed dotarciem do dispatchera, hostowanego w UE (Niemcy).
- Wtyczka jest dystrybuowana na licencji GPLv2 lub nowszej i przestrzega standardów kodowania WordPressa.

## Abonament usługi DataFirefly Server-Side

Wtyczka przechwytuje i podpisuje; usługa _DataFirefly Server-Side Tracking_ przyjmuje i dystrybuuje po stronie serwera do pięciu destynacji: **Meta CAPI, GA4 (Measurement Protocol), TikTok Events API, Pinterest Conversions API i Google Ads**. Dispatcher jest hostowany w Niemczech, przyjmowanie jest podpisywane HMAC-em, dane osobowe są maskowane, a wyzwalanie respektuje zgodę. Jedna integracja, jedna skonsolidowana faktura, możliwość wielu witryn.

Poznaj oferty i wykup abonament na [server-side.datafirefly.com](https://server-side.datafirefly.com/):

- **Starter**: 39 €/miesiąc, 1 witryna, do 500 tys. zdarzeń
- **Growth**: 119 €/miesiąc, 5 witryn, do 2 mln zdarzeń
- **Scale**: 349 €/miesiąc, 20 witryn, do 10 mln zdarzeń

## Rozwiązywanie problemów

### Status pozostaje „Niepołączono"

Sprawdź, czy klucz rzeczywiście zaczyna się od `dfss_` i został skopiowany w całości. Klucz wskazujący inną domenę niż `datafirefly.com` (HTTPS) jest odrzucany. Spróbuj ponownie przyciskiem _Testuj zdarzenie_.

### Purchase nie dociera

Purchase wychodzi z hooków zamówienia: upewnij się, że zamówienie osiąga status płatności (zakończona / w realizacji / zrealizowane). Sprawdź dziennik aktywności, czy zdarzenie czeka w kolejce albo zostało odrzucone, i zweryfikuj cron, jeśli zdarzenia zalegają.

### Skrypt Meta (albo GA4, TikToka) się nie ładuje

Dwie możliwe przyczyny: destynacja jest odznaczona w **Destynacje klienckie** (zachowanie celowe od wersji 2.2.0) albo nie jest skonfigurowana na Twoim koncie DataFirefly; ekran ustawień wtedy to wskazuje. Po zmianie po stronie konta użyj przycisku _Odśwież identyfikatory destynacji_.

### Konwersje liczone podwójnie

Sprawdź, czy inna wtyczka śledząca nie wysyła już konkurencyjnego `purchase` bez wspólnego `event_id`. Z samym DataFirefly Server-Side `event_id` oparty na zamówieniu gwarantuje deduplikację.

### Nic nie wychodzi, choć zgoda wydaje się udzielona

Bramka jest domyślnie aktywna. Sprawdź, czy kategoria _marketing_ jest rzeczywiście zaakceptowana w Twoim rozwiązaniu zgód i czy jest ono wykrywane (Cookie Consent v2, WP Consent API, Complianz, Cookiebot albo IAB TCF v2).

Potrzebujesz pomocy? Skontaktuj się ze wsparciem DataFirefly ze swojego konta klienta, dołączając zrzut dziennika aktywności (kod HTTP + liczba prób).