# Facebook Dynamic Ads + Pixel PRO: kompletny przewodnik
> Wprowadzenie Facebook Dynamic Ads + Pixel PRO łączy katalog PrestaShop z Facebookiem i Instagramem. Moduł eksportuje feed produktów wysokiej jakości (XML w formacie Facebook RSS albo CSV), instaluje Pixel Facebooka…
- Strona:
- Język: pl
- Zaktualizowano: 2026-09-14
- Inne języki: [fr](https://www.datafirefly.com/documentation/dffbadspixel/index.md), [en](https://www.datafirefly.com/en/documentation/dffbadspixel-2/index.md), [es](https://www.datafirefly.com/es/documentation/dffbadspixel-3/index.md), [de](https://www.datafirefly.com/de/documentation/dffbadspixel-4/index.md), [it](https://www.datafirefly.com/it/documentation/dffbadspixel-5/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffbadspixel/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffbadspixel/index.md)
- Indeks:
## Wprowadzenie
Facebook Dynamic Ads + Pixel PRO łączy katalog PrestaShop z Facebookiem i Instagramem. Moduł eksportuje feed produktów wysokiej jakości (XML w formacie Facebook RSS albo CSV), instaluje Pixel Facebooka w sklepie i włącza API Konwersji, aby zapewnić niezawodne śledzenie po stronie serwera. Generuje osobny feed dla każdej kombinacji Kraj / Język / Waluta, daje precyzyjną kontrolę nad eksportowanymi danymi (wykluczenia, niestandardowe etykiety, mapowanie kategorii Google) i jest zaprojektowany dla dużych katalogów, do 200 000 produktów.
Zgodny z PrestaShop 8.0 do 9.x, PHP 7.4 do 8.3, w trybie multisklep i wielojęzycznym. Do API Konwersji wymagany jest `cURL`. Brak zależności Composer w środowisku produkcyjnym.
## Instalacja
1. W panelu administracyjnym otwórz **Moduły → Menedżer modułów → Zainstaluj moduł**.
2. Wgraj plik `dffbadspixel.zip`.
3. Moduł instaluje się i automatycznie tworzy swoje tabele (`dffbadspixel_exclusion`, `dffbadspixel_label`, `dffbadspixel_capi_queue`) oraz zakładkę administracyjną **Facebook Dynamic Ads + Pixel**.
Przy instalacji generowany jest unikalny token bezpieczeństwa. Zabezpiecza on adresy URL feedu i CRON-a, a jego wartość znajdziesz w zakładce **Adresy URL i CRON** modułu.
## Zakładka Feed produktów
To serce modułu. Wybierasz w niej format i tryb generowania, zakres produktów oraz szczegółowość eksportowanych danych.
### Format i generowanie
- **Format**: XML (Facebook RSS z przestrzenią nazw Google), CSV albo oba jednocześnie.
- **Tryb generowania**: _w locie_ (strumieniowo przy każdym wywołaniu adresu URL) albo _CRON_ (pliki w cache, zalecane dla dużych katalogów).
- **Kompresja gzip**, **rozmiar partii** (chunking) i opcja **tylko aktywne kraje** pozwalają zoptymalizować wydajność.
### Wybór produktów i szczegółowość
- **Eksport według** kategorii albo marki, z precyzyjnym wyborem (pole filtra ułatwia wyszukiwanie na liście).
- **Poziom szczegółowości**: produkt albo wariant.
- **Budowanie ID feedu**: ID z panelu (z opcją języka i/lub wariantu), indeks albo EAN.
- **Typ opisu** (krótki lub długi), **dostępność** (według stanu magazynowego albo zawsze dostępny), **kolory**, **rozmiary**, dodatkowe zdjęcia albo **tylko zdjęcie główne**.
### Koszty wysyłki, śledzenie i jakość danych
- **Rzeczywiste koszty wysyłki** wyliczane przez przewoźników PrestaShop (strefa, przedziały wagi i ceny), przewoźnik referencyjny albo najtańszy, z konfigurowalnym progiem darmowej dostawy.
- **Parametry UTM** i integracja z **GA4**.
- **Limity jakości**: maksymalne długości tytułu i opisu używane przez walidator (zakładka Diagnostyka).
### Wykluczenia ogólne
Bezpośrednio w zakładce Feed: wyklucz produkty bez stanu magazynowego, bez EAN/MPN albo poniżej ceny minimalnej.
## Wykluczenia zaawansowane
W zakładce **Wykluczenia** dodajesz precyzyjne reguły odrzucające wybrane produkty z feedu. Każda reguła opiera się na typie i wartości:
- **Słowo lub wyrażenie**: wyklucza, jeśli nazwa albo opis zawiera dany termin.
- **Produkt**, **wariant**, **dostawca**: według ID.
- **Wartość cechy** albo **atrybut**: według ID.
## Niestandardowe etykiety i tagi odzieżowe
**Niestandardowe etykiety** (`custom_label_0` do `custom_label_4`) wzbogacają segmentację kampanii: nazwa kategorii, wartość cechy, przedział cenowy albo oznaczenia „nowość” i „bestseller”.
Zakładka **Tagi odzieżowe** dodaje pola Meta przeznaczone dla mody: `age_group`, `gender`, a także `pattern` (wzór) i `material` (materiał) mapowane na cechy produktu.
## Mapowanie kategorii i walut
W zakładce **Mapowanie i waluty** przypisujesz kategorie PrestaShop do kategorii Google/Facebook:
- **Import CSV** w formacie `id_category;google_category` (separator `;` albo `,`, nagłówek opcjonalny).
- **Import z innego modułu** DataFirefly zainstalowanego w sklepie (wersja standardowa, Google Merchant Center, GMC Pro albo TikTok Ads).
- **Automatyczne sugestie według słów kluczowych**: uzupełniają puste dopasowania na podstawie nazwy kategorii.
- Edycja ręczna wiersz po wierszu, z filtrem wyszukiwania.
**Tabela Waluta / Kraj** określa walutę używaną dla każdego kraju przy generowaniu feedów wielokrajowych. Bez przypisania stosowana jest domyślna waluta sklepu.
Zacznij bez mapowania kategorii: Meta akceptuje feed bez pola `google_product_category`. Dodawaj je stopniowo na głównych kategoriach, aby poprawić zasięg emisji.
## Pixel Facebooka
W zakładce **Pixel** włączasz Pixel i podajesz swój **ID Pixela**. Moduł wstrzykuje kod bazowy (PageView) oraz zdarzenia kontekstowe: ViewContent, ViewCategory, Search, InitiateCheckout, AddToCart i AddToWishlist.
- **Zaawansowane dopasowanie** (advanced matching): wysyła dodatkowe dane klienta, zahashowane w SHA-256, aby poprawić jakość grup odbiorców.
- **Konfigurowalne selektory HTML** dla przycisków „lista życzeń” i „zamów”, przydatne, jeśli Twój szablon zmienił domyślny kod HTML.
- **Konfigurowalna kwota Purchase**: z podatkiem lub bez, z kosztami wysyłki i/lub opakowania lub bez nich.
## API Konwersji (asynchroniczne)
API Konwersji wysyła zdarzenia bezpośrednio z Twojego serwera i odzyskuje konwersje, których sam Pixel nie wykrywa (blokery, cookies). W zakładce **API Konwersji**:
1. Włącz API Konwersji i wklej **token dostępu** wygenerowany w Business Managerze Meta.
2. Pozostaw włączony **tryb asynchroniczny** (zalecany): zdarzenia trafiają do kolejki, a następnie są wysyłane partiami przez CRON, bez spowalniania sklepu.
3. W razie potrzeby dostosuj **rozmiar partii** i liczbę **maksymalnych prób** (retry). **Testowy kod zdarzenia** pozwala zweryfikować integrację w Business Managerze.
Zdarzenia są deduplikowane z Pixelem przeglądarkowym dzięki wspólnemu `event_id` (na przykład `order-1234` dla zakupu). Dane użytkownika są hashowane algorytmem SHA-256 przed wysyłką.
### Statusy wyzwalające Purchase
Od wersji 2.1.0 zdarzenie Purchase jest emitowane, gdy zamówienie **przechodzi do statusu wyzwalającego**, a nie przy jego utworzeniu. Zaznacz odpowiednie statusy w zakładce API Konwersji: przy instalacji wstępnie wybrane są statusy oznaczone przez PrestaShop jako opłacone. Jeśli nie zaznaczono żadnego statusu, moduł wraca do tych samych statusów opłaconych.
To zachowanie jest niezbędne przy płatnościach asynchronicznych (przelew, BLIK, SEPA, Klarna): zamówienie powstaje w oczekiwaniu na płatność, a Purchase jest wysyłany dopiero po jej potwierdzeniu. Ponieważ wysyłka odbywa się w pełni po stronie serwera, nie zależy od strony potwierdzenia, nawet jeśli klient nigdy nie wróci do sklepu. Zabezpieczenie przez `event_id` zapobiega duplikatom, gdy zamówienie zmienia status wielokrotnie.
### Wysyłane dane użytkownika
Gdy są dostępne, moduł przesyła: `em` (e-mail), `ph` (telefon), `fn`, `ln`, `ct`, `zp`, `external_id`, `fbp`, `fbc`, `client_ip_address` i `client_user_agent`. Wszystkie dane osobowe są hashowane algorytmem SHA-256 przed wysyłką. `external_id` korzysta z ID klienta (lub identyfikatora gościa dla odwiedzających). `fbc` jest odczytywane z ciasteczka `_fbc`, a jeśli jeszcze nie istnieje, odtwarzane z parametru URL `fbclid`.
## Zgoda RODO i CMP
Zakładka **Zgoda** egzekwuje zgodę marketingową dla Pixela _oraz_ dla wysyłki po stronie serwera. Dopóki nie zostanie udzielona, Pixel pozostaje w trybie `revoke` (Consent Mode Meta), a żadne zdarzenie nie trafia do kolejki ani nie jest wysyłane przez API Konwersji.
Wykrywanie działa kaskadowo:
1. **IAB TCF v2.2**: odczyt `__tcfapi` (cel 1 i vendor Meta 89).
2. **Ciasteczko Twojego CMP**: konfigurowalna nazwa i oczekiwana wartość (Axeptio, Cookiebot, Didomi, moduły RODO dla PrestaShop…).
3. **API JavaScript**: wywołaj `window.dffbConsentGrant()` przy akceptacji i `window.dffbConsentRevoke()` przy odmowie z własnego bannera.
Decyzja odczytana w przeglądarce jest odzwierciedlana w ciasteczku `dffb_consent`, dzięki czemu API Konwersji stosuje dokładnie ten sam wybór po stronie serwera. Dodatkowo na `document` emitowane jest zdarzenie `dffb:consent`.
## Adresy URL feedu i zadanie CRON
Zakładka **Adresy URL i CRON** pokazuje bazowy adres feedu, adres CRON-a oraz listę adresów dla każdej kombinacji Kraj / Język / Waluta.
### Adres URL feedu
```
https://twoj-sklep.pl/index.php?fc=module&module=dffbadspixel&controller=feed&token=TWOJ_TOKEN&id_lang=1&id_currency=1&id_country=8&format=xml
```
Parametry `id_lang`, `id_currency`, `id_country` i `format` (`xml` albo `csv`) wskazują feed do wygenerowania. To ten adres deklarujesz jako źródło feedu w katalogu Meta.
### Zadanie CRON
W trybie CRON zaplanuj wywołanie endpointu, aby generować pliki w cache i opróżniać kolejkę API Konwersji:
```
*/30 * * * * curl -s "https://twoj-sklep.pl/index.php?fc=module&module=dffbadspixel&controller=cron&token=TWOJ_TOKEN" > /dev/null
```
Opcjonalny parametr `job` wskazuje konkretne zadanie: `feeds` (generowanie feedów), `capi` (wysyłka kolejki API Konwersji) albo `all` (domyślnie). Odpowiedzią jest tekstowe podsumowanie.
## Diagnostyka: podgląd i walidacja
Zakładka **Diagnostyka** łączy dwa narzędzia:
- **Kolejka API Konwersji**: liczba zdarzeń oczekujących, nieudanych i wysłanych.
- **Podgląd i walidacja feedu**: generuje próbkę XML oraz raport jakości wskazujący problematyczne wiersze: brak zdjęcia, nieprawidłowy GTIN (weryfikowany cyfrą kontrolną), zbyt długi tytuł albo opis, niewystarczający identyfikator produktu.
## Bezpieczeństwo
W zakładce **Bezpieczeństwo**:
- **Lista dozwolonych IP**: ogranicza dostęp do feedu i CRON-a do wybranych adresów albo zakresów CIDR (na przykład serwerów Meta). Pusta lista oznacza brak ograniczeń.
- **Rotacja tokenu**: generuje nowy token adresów URL. Stary pozostaje akceptowany aż do unieważnienia, co daje czas na aktualizację feedów w Meta.
Po rotacji tokenu pamiętaj o aktualizacji źródeł feedu w Business Managerze, a następnie o unieważnieniu starego tokenu w zakładce Bezpieczeństwo, aby zamknąć okno przejściowe.
## Rozwiązywanie problemów
### Feed zwraca „Forbidden”
Token jest pusty, nieprawidłowy albo wywołujący adres IP nie znajduje się na liście dozwolonych. Sprawdź token w zakładce Adresy URL i CRON oraz wyczyść listę dozwolonych IP na czas testu.
### Feed jest pusty albo niekompletny
Sprawdź wybór kategorii i marek (pusty oznacza cały katalog), reguły wykluczeń oraz stany magazynowe, jeśli aktywne jest wykluczenie produktów niedostępnych. W trybie CRON uruchom najpierw zadanie `job=feeds`, aby wygenerować cache.
### Zdarzenia API Konwersji nie docierają do Meta
Upewnij się, że `cURL` jest dostępny i token dostępu jest ważny, po czym uruchom zadanie `job=capi`. Śledź kolejkę w zakładce Diagnostyka; błędy są zapisywane w **Parametry zaawansowane → Logi** z prefiksem `[dffbadspixel]`.
### Pixel nie uruchamia się na przycisku
Jeśli Twój szablon zmienił kod HTML, dostosuj selektory „lista życzeń” i „zamów” w zakładce Pixel.
## Dobre praktyki
- Używaj **trybu CRON z gzip** przy dużych katalogach: generowanie w locie jest możliwe, ale kosztowniejsze przy każdym wywołaniu.
- Włącz **Pixel i API Konwersji razem**: deduplikacja przez `event_id` zapobiega podwójnemu liczeniu, a jednocześnie poprawia pokrycie.
- Uzupełnij **mapowanie kategorii Google** i **GTIN**, aby zmaksymalizować kwalifikowalność produktów do miejsc docelowych Advantage+ i Shopping.