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

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.

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.

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.

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.

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.

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.