Conversions API dla Meta w sklepie online - po co i jak wdrożyć

Jak wdrożyć Conversions API w sklepie internetowym

Są dwie główne drogi. Pierwsza to integracja partnerska, czyli gotowe rozwiązanie platformy sklepowej lub wtyczka, która sama wysyła zdarzenia serwerowe. Dla WooCommerce oficjalnym rozwiązaniem jest wtyczka Meta for WooCommerce z repozytorium WordPress.org, która instaluje piksel i jest oznaczona tagiem Conversions API. Podobne integracje mają inne popularne platformy. To najszybsza droga, ale zakres wysyłanych zdarzeń i danych zależy od autora integracji.

Druga droga to bezpośrednia integracja, czyli własny kod. Dokumentacja Meta dla programistów skupia się właśnie na niej. Token dostępu generuje się w Menedżerze zdarzeń: w ustawieniach piksela, w sekcji Conversions API, przez link do ręcznej konfiguracji widoczny dla osób z uprawnieniami dewelopera (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta). Zdarzenia wysyła się metodą POST na adres w schemacie graph.facebook.com/{wersja API}/{ID piksela}/events.

Jakie parametry wysyła się w zdarzeniu serwerowym

Według dokumentacji Meta wymagane parametry zdarzenia to event_name, event_time, user_data i action_source, a dla zdarzeń ze strony internetowej także event_source_url (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta). Najważniejsze pola:

• event_name - nazwa zdarzenia standardowego, np. Purchase, AddToCart, ViewContent, albo nazwa własna,

• event_time - znacznik czasu Unix w sekundach; zdarzenie może być najwyżej 7 dni starsze od chwili wysyłki,

• action_source - miejsce konwersji, dla sklepu internetowego wartość website,

• event_source_url - adres strony, na której zaszło zdarzenie,

• user_data - dane klienta, część zaszyfrowana funkcją skrótu, część w postaci jawnej,

• custom_data - wartość, waluta i identyfikatory produktów,

• event_id - formalnie opcjonalny, ale zalecany do deduplikacji z pikselem.

Jedno zapytanie może zawierać do 1 000 zdarzeń w tablicy data. Jeśli którekolwiek zdarzenie jest starsze niż 7 dni, Meta zwraca błąd dla całego zapytania i nie przetwarza żadnego zdarzenia (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta). Dlatego zdarzenia najlepiej wysyłać na bieżąco, a nie raz na kilka dni hurtem.

[#przyklad] Uproszczony przykład treści zdarzenia zakupu (JSON): {"data": [{"event_name": "Purchase", "event_time": 1781172000, "action_source": "website", "event_id": "order-10452", "event_source_url": "https://sklep.pl/zamowienie/dziekujemy", "user_data": {"em": ["<skrót SHA256 adresu e-mail>"], "client_ip_address": "203.0.113.10", "client_user_agent": "Mozilla/5.0 ...", "fbp": "fb.1.1781171000.123456789"}, "custom_data": {"currency": "PLN", "value": 249.90, "content_ids": ["SKU-123"], "content_type": "product"}}]}

Dane klienta - co szyfrować, a czego nie

Dokumentacja Meta dzieli dane klienta na dwie grupy. Funkcją skrótu trzeba zaszyfrować m.in. adres e-mail (em), telefon (ph), imię i nazwisko (fn, ln), datę urodzenia, płeć, miasto, region, kod pocztowy i kraj, a external_id - zaleca się szyfrować. Przykłady w dokumentacji używają SHA256. Nie szyfruje się natomiast adresu IP, nagłówka przeglądarki (client_user_agent) ani identyfikatorów z plików cookie fbp i fbc (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta).

Przed szyfrowaniem dane trzeba znormalizować. Adres e-mail: usunąć spacje z początku i końca, zamienić litery na małe. Telefon: zostawić same cyfry, bez zer na początku, z kierunkowym kraju, czyli dla Polski z prefiksem 48. Błąd normalizacji nie zgłasza żadnego komunikatu - zdarzenie zostanie przyjęte, ale Meta nie dopasuje go do użytkownika. Jeśli korzystasz z oficjalnego Business SDK, biblioteka szyfruje dane za ciebie.

[#uwaga] Przesyłanie danych klientów do Meta wymaga podstawy prawnej i zgód zgodnych z RODO oraz polityką prywatności sklepu. Zakres zgód i sposób ich zbierania ustal z prawnikiem lub inspektorem ochrony danych - programista wdroży to, co zostanie ustalone, ale nie podejmie tej decyzji za sklep.

Deduplikacja zdarzeń piksela i Conversions API

Gdy ten sam zakup wysyła piksel i serwer, Meta musi wiedzieć, że to jedno zdarzenie. Zalecana metoda to para identyfikatorów: eventID w pikselu musi być równy event_id w Conversions API, a nazwa zdarzenia w pikselu musi być taka sama jak event_name na serwerze. W pikselu eventID podaje się w czwartym argumencie wywołania, np. fbq('track', 'Purchase', {value: 249.90, currency: 'PLN'}, {eventID: 'order-10452'}). Deduplikacja działa dla zdarzeń otrzymanych w ciągu 48 godzin, a gdy zdarzenia się nie różnią, Meta zwykle zachowuje to, które przyszło pierwsze (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta).

Najprostszy wybór identyfikatora dla zakupu to numer zamówienia, bo zna go zarówno strona podziękowania, jak i serwer. Dla zdarzeń bez zamówienia, takich jak AddToCart, sklep musi wygenerować identyfikator w przeglądarce i przekazać go do serwera, np. w zapytaniu dodającym produkt do koszyka. Typowe problemy z deduplikacją i jakością danych pokazuje diagram:

[#chart:wpr36b]

Jak przetestować Conversions API przed uruchomieniem

Menedżer zdarzeń ma narzędzie Test Events, które pokazuje zdarzenia napływające na żywo. Kod testowy z tego narzędzia wysyła się w polu test_event_code na najwyższym poziomie zapytania, obok tablicy data. Dokumentacja wyraźnie zaznacza, że pole służy tylko do testów i trzeba je usunąć z wysyłki produkcyjnej (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta). Plan testów, który stosujemy przy wdrożeniach:

1. Zdarzenia przeglądania - ViewContent i AddToCart z obu źródeł, z tym samym event_id.

2. Zamówienie testowe - Purchase z poprawną wartością, walutą PLN i identyfikatorami produktów zgodnymi z katalogiem.

3. Płatność bez powrotu - zamówienie opłacone, po którym klient zamyka kartę przed stroną podziękowania; zdarzenie serwerowe nadal musi dotrzeć.

4. Odrzucenie zgód - sklep zachowuje się zgodnie z ustaloną polityką zgód.

5. Usunięcie kodu testowego - po testach test_event_code znika z konfiguracji.

Kiedy wysyłać zdarzenie Purchase z serwera? Najbezpieczniej w chwili, gdy zamówienie zmienia status na opłacone, czyli w obsłudze powiadomienia od bramki płatności albo w zdarzeniu systemowym sklepu. Taki mechanizm łatwo zbudować na webhookach - zasady ich bezpiecznego wdrażania opisujemy we wpisie webhooki w e-commerce - do czego służą i jak je bezpiecznie wdrożyć. Wysyłka powinna trafiać do kolejki z ponawianiem, żeby chwilowa niedostępność API Meta nie oznaczała utraty zdarzenia.

Gotowa integracja czy własny kod Conversions API

Wybór zależy od platformy, liczby źródeł sprzedaży i tego, jak bardzo zależy ci na kontroli danych. Gotowa integracja wystarczy, gdy sklep działa na popularnej platformie, sprzedaje głównie przez stronę i nie ma nietypowego procesu płatności. Własny kod opłaca się, gdy zamówienia powstają w kilku miejscach, np. w sklepie i przez telefon, gdy chcesz wysyłać zdarzenia dopiero po faktycznym opłaceniu albo gdy wtyczka nie przekazuje danych, których potrzebuje zespół reklamowy.

[#chart:wpr36c]

Przy własnym kodzie trzeba też zaplanować utrzymanie. Meta regularnie publikuje nowe wersje Graph API, a starsze z czasem przestają działać, więc integracja wymaga okresowej aktualizacji numeru wersji w adresie zapytania i sprawdzenia, czy nic się nie zmieniło w parametrach. Token dostępu warto przechowywać w zmiennych środowiskowych serwera, a nie w kodzie szablonu sklepu, a błędy odpowiedzi API zapisywać w dzienniku z alertem dla osoby, która może je naprawić.

Trzecią opcją jest wysyłka zdarzeń przez serwerowy kontener Google Tag Manager, do którego trafiają dane ze strony, a stamtąd tag przekazuje je do Conversions API. To rozwiązanie ma sens, gdy sklep i tak buduje pomiar po stronie serwera także dla innych narzędzi. Niezależnie od wybranej drogi po wdrożeniu warto obserwować w Menedżerze zdarzeń wskaźnik jakości dopasowania zdarzeń oraz porównywać liczbę zakupów z panelem sklepu raz w tygodniu.

Jak Vinson pomaga wdrożyć Conversions API Meta

Programiści Vinson zaczynają od audytu obecnego pomiaru: sprawdzamy piksel, zdarzenia w Menedżerze zdarzeń, zgodność identyfikatorów z katalogiem i różnicę między zakupami w sklepie a w raportach. Potem konfigurujemy integrację partnerską albo piszemy własny moduł wysyłający zdarzenia z serwera sklepu, z normalizacją danych, deduplikacją przez event_id, kolejką z ponawianiem i testami. Jako Meta Business Partner łączymy pracę techniczną z obsługą kampanii. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Czy Conversions API zastępuje piksel Meta?

Nie. Meta zaleca używanie piksela i Conversions API razem. Piksel zbiera zdarzenia z przeglądarki i ustawia identyfikator _fbp, a serwer uzupełnia zdarzenia, które piksel zgubił. Oba źródła muszą mieć wspólne event_id, żeby Meta nie liczyła zdarzeń podwójnie.

Jakie parametry są wymagane w Conversions API?

Według dokumentacji Meta wymagane są event_name, event_time, user_data i action_source, a dla zdarzeń ze strony także event_source_url. Do deduplikacji zalecany jest event_id. Przy zakupie warto wysłać w custom_data wartość, walutę i identyfikatory produktów (stan na czerwiec 2026 - sprawdź aktualną dokumentację Meta).

Czy dane klientów w Conversions API trzeba szyfrować?

Tak, część z nich. Adres e-mail, telefon, imię, nazwisko i dane adresowe wysyła się jako skrót SHA256 po normalizacji. Adresu IP, nagłówka przeglądarki oraz identyfikatorów fbp i fbc się nie szyfruje. Zakres przesyłanych danych i zgody ustal z prawnikiem lub inspektorem ochrony danych.

Dlaczego po wdrożeniu Conversions API zakupy liczą się podwójnie?

Najczęściej dlatego, że piksel i serwer wysyłają różne event_id albo serwer nie wysyła go wcale. Zdarzenie musi mieć tę samą nazwę i ten sam identyfikator w obu źródłach, a deduplikacja działa dla zdarzeń otrzymanych w ciągu 48 godzin. Dobrym identyfikatorem zakupu jest numer zamówienia.

Czy w WooCommerce da się wdrożyć Conversions API bez programisty?

Tak, w podstawowym zakresie. Oficjalna wtyczka Meta for WooCommerce z repozytorium WordPress.org instaluje piksel i obsługuje Conversions API. Programista przydaje się, gdy trzeba zmienić moment wysyłki zakupu, dodać zdarzenia z innych źródeł sprzedaży albo naprawić deduplikację i niezgodne identyfikatory produktów.

Conversions API dla Meta to dziś podstawa wiarygodnego pomiaru sprzedaży z reklam na Facebooku i Instagramie - bez niego kampanie uczą się na niepełnych danych. Jeśli chcesz wdrożyć CAPI w swoim sklepie albo naprawić istniejącą integrację, sprawdź wsparcie programistyczne Vinson.