Meta CAPI events: mapowanie zdarzeń i diagnostyka Conversions API

Meta CAPI events opisują działania użytkownika przekazywane do Meta na potrzeby pomiaru i optymalizacji reklam. Conversions API przyjmuje zdarzenie z serwera, systemu sklepowego lub integracji, a Meta Pixel wysyła je z przeglądarki. Oba kanały mogą opisywać tę samą czynność, ale różnią się miejscem powstania danych i warunkami ich wysłania.

Pixel zależy od uruchomienia kodu w przeglądarce, konfiguracji strony i dostępnych zgód. Backend sklepu może znać status zamówienia, ale musi samodzielnie przekazać poprawną nazwę i parametry zdarzenia. CAPI nie zastępuje automatycznie Pixela. Jeżeli działają równolegle, sprawdź, czy nie powielają wysyłki albo czy odpowiadające sobie kopie można deduplikować.

W Pixelu nazwa standardowego zdarzenia jest przekazywana w wywołaniu `fbq('track', ...)`, a w Conversions API w polu `event_name`. Źródłem może być kod strony, wtyczka WooCommerce, serwer aplikacji, CRM albo integracja partnera. Dwie integracje mogą mieć różne nazwy ustawień, a mimo to wysyłać tę samą czynność do Meta.

Przed dołożeniem nowej integracji ustal, co już wysyłają aktywne wtyczki, Google Tag Manager i kod własny. Zapisz właściciela każdej wysyłki oraz warunek jej uruchomienia. Konfigurację części przeglądarkowej i jej współpracę z CAPI opisujemy też w poradniku konfiguracji Pixela Facebooka w GTM, WordPressie i CAPI.

Wysyłaj standardowe zdarzenie wtedy, gdy działanie w sklepie odpowiada jego znaczeniu. `ViewContent` powinno oznaczać wyświetlenie konkretnej treści, a `Purchase` zakup zgodny z regułą biznesową sklepu, nie samo otwarcie strony podziękowania.

Samo przejście do kroku płatności nie oznacza dodania informacji płatniczej. Jeśli checkout nie zbiera ani nie zapisuje takich danych, nie wywołuj `AddPaymentInfo` przy wejściu na ekran wyboru metody. Puste albo przedwczesne zdarzenie nie opisuje działania użytkownika.

Wartość `value` przekazuj jako liczbę, a `currency` jako kod waluty, na przykład `PLN`. `content_ids` powinno zawierać identyfikatory zgodne z katalogiem Meta, jeśli sklep korzysta z reklam katalogowych. Sprawdź identyfikatory wariantów: katalog może używać ID wariantu, podczas gdy integracja wysyła ID produktu nadrzędnego.

Dla zakupów ustal, czy wartość obejmuje podatek, dostawę i rabaty. Stosuj tę samą definicję w Pixelu, CAPI, GA4 i raportach finansowych. Odmienna metoda wyliczenia może powodować rozbieżne przychody nawet wtedy, gdy wszystkie systemy odbierają zdarzenia.

Perspektywa KC Mobile: Przy audycie `Purchase` sprawdzamy rekord zamówienia i historię jego statusów, a dopiero potem liczbę w panelu reklamowym. Jeśli strona podziękowania wysyła zdarzenie przed potwierdzeniem płatności albo przy każdym odświeżeniu, pomiar opisuje wejście na adres URL zamiast zakupu.

Wybieraj standardowe `event_name`, gdy jego znaczenie pasuje do działania i chcesz przekazać Meta rozpoznawalny typ sygnału. Zdarzenie niestandardowe stosuj dla odrębnego etapu biznesowego, którego nie da się uczciwie opisać nazwą standardową. Nie zmieniaj nazwy tylko po to, aby wcześniejszy etap wyglądał jak zakup lub lead.

Poprawne wysłanie formularza może odpowiadać `Lead`, ale samo kliknięcie przycisku nie wystarczy, jeśli walidacja zakończyła się błędem. Potwierdzona rezerwacja może mieć nazwę standardową pasującą do procesu albo własną nazwę, jeśli nie ma odpowiednika. Kwalifikację leada przez handlowca można przesłać jako osobny etap z CRM, jeżeli system stabilnie rejestruje tę zmianę.

Dla każdej nazwy prowadź prostą specyfikację: znaczenie, warunek wysyłki, źródło, parametry i właściciel techniczny. `event_name` mówi, jaka czynność zaszła, natomiast `custom_data` może zawierać jej szczegóły, takie jak wartość czy identyfikator produktu. Po zmianie nazwy sprawdź reguły konwersji niestandardowych i raporty korzystające z dotychczasowego zdarzenia.

Każde zdarzenie serwerowe powinno opisywać czynność, czas i źródło zgodnie ze specyfikacją Conversions API. Konkretna wtyczka może automatycznie wypełniać część pól, dlatego porównuj payload wysłany do Meta z ustawieniami integracji.

`event_id` identyfikuje konkretną instancję zdarzenia i służy przede wszystkim do dopasowania kopii wysłanej przez Pixel oraz CAPI. Nie jest obowiązkowym polem każdego zdarzenia CAPI. Jeżeli zdarzenie wysyła wyłącznie serwer i nie ma odpowiadającej mu kopii przeglądarkowej do połączenia, nie należy dopisywać go jako uniwersalnego wymogu. Dokumentacja Meta opisuje deduplikację zdarzeń Pixela i serwera.

`event_time` powinien wskazywać czas wystąpienia czynności, a nie późniejszy moment przetworzenia kolejki. `action_source` opisuje źródło działania, a `event_source_url` wskazuje adres związany ze zdarzeniem internetowym. Dla wysyłek opóźnionych z kolejki sprawdź, czy nadal przekazujesz pierwotny czas zdarzenia.

Dane w `user_data` mogą wspierać dopasowanie, ale ich zakres musi odpowiadać podstawie przetwarzania, zgodom i dokumentacji Meta. Nie przekazuj danych, których firma nie ma prawa użyć w tym celu. Ustal z osobą odpowiedzialną za prywatność, jakie pola integracja może wysyłać i jak uwzględnia ustawienia zgód.

Kwotę w `value` przesyłaj jako liczbę w uzgodnionej jednostce waluty. Nie dodawaj symbolu waluty ani separatora tysięcy do wartości liczbowej. W `content_ids` sprawdź typ identyfikatora i `content_type`, aby produkt można było dopasować do właściwego katalogu.

Deduplikacja pozwala Meta rozpoznać zdarzenie przeglądarkowe i serwerowe jako dwie kopie tej samej czynności. W typowym scenariuszu standardowe zdarzenia muszą mieć zgodny `event_name` oraz ten sam identyfikator: `eventID` w Pixelu i `event_id` w CAPI. Zasady Meta opisują mechanizm deduplikacji Pixela i zdarzeń serwerowych.

Dla zakupu sklep może utworzyć identyfikator zdarzenia przy zmianie zamówienia na stan spełniający przyjętą regułę. Integracja przekazuje go do `eventID` w Pixelu i `event_id` w CAPI, wraz z tą samą nazwą `Purchase`. Ponowienie wysyłki tej samej czynności powinno zachować pierwotny identyfikator, a nowa czynność powinna dostać osobny.

Deduplikacja pary Pixel i CAPI nie rozwiąże automatycznie problemu dwóch niezależnych integracji serwerowych, które wysyłają to samo zdarzenie z różnymi ID. Sprawdź, czy aktywna wtyczka WooCommerce, serwerowy GTM i kod własny nie tworzą równoległych wysyłek.

Nie generuj osobnego, losowego ID po stronie przeglądarki i serwera dla tej samej czynności, jeśli oczekujesz deduplikacji. Szczegóły połączenia, konfiguracji i testowania opisujemy w poradniku konfiguracji i testów Facebook Conversions API.

Testuj pojedyncze działanie i porównaj jego payload z tym, co zapisuje sklep. W Menedżerze zdarzeń otwórz właściwe źródło danych i skorzystaj z testowania zdarzeń; jeśli integracja obsługuje kod testowy, przekaż go według jej instrukcji.

1. W Menedżerze zdarzeń wybierz źródło danych przypisane do właściwego Pixel ID.
2. Otwórz testowanie zdarzeń i pobierz kod testowy, jeśli jest potrzebny dla wybranej integracji.
3. W sklepie wykonaj jedną czynność, na przykład wyświetl produkt lub dodaj go do koszyka.
4. Dla testu zakupu użyj testowej metody płatności i zapisz numer zamówienia oraz oczekiwany status.
5. Porównaj nazwę, czas, źródło, event_id, wartość, walutę i ID produktu z rekordem w WooCommerce.
6. Sprawdź diagnostykę źródła oraz to, czy zgodne kopie Pixela i CAPI zostały deduplikowane.

Jeśli zdarzenia nie ma w teście, sprawdź najpierw, czy sklep próbował je wysłać. W integracji serwerowej przejrzyj log wtyczki lub aplikacji, odpowiedź API, uprawnienia i wskazane źródło danych. Nie zapisuj tokena dostępu w logach dostępnych osobom nieuprawnionym.

Zamówienia testowe oznaczaj odrębnym statusem, prefiksem numeru albo metadanymi dostępnymi w systemie sklepu. W raportach WooCommerce i eksporcie sprzedaży filtruj je po tym znaczniku lub wyklucz z raportów przychodowych. W GA4 i raportach reklamowych używaj testowego strumienia lub zakresu testowego, jeżeli wdrożenie to umożliwia; nie mieszaj testowych transakcji z oceną wyników kampanii.

Jeżeli Meta odbiera zdarzenie, ale nie widzisz go w raporcie kampanii, oddziel odbiór techniczny od atrybucji. Sprawdź zakres dat, opóźnienie przetwarzania, ustawienie atrybucji i to, czy analizujesz właściwe zdarzenie. Poprawny odbiór nie gwarantuje przypisania do konkretnej reklamy.

Rozbieżności zwykle wynikają z tego, że techniczne zdarzenie nie odpowiada temu, co firma uznaje za zakończoną czynność. Prześledź drogę od działania użytkownika przez logikę WooCommerce do payloadu odbieranego przez Meta.

Statusy WooCommerce zależą od konfiguracji bramki i rodzaju płatności. Nie przyjmuj bez sprawdzenia, że `processing` albo `completed` zawsze oznacza taki sam moment finansowy. Ustal osobne warunki dla płatności online, przelewu tradycyjnego i pobrania, a następnie udokumentuj, które z nich uruchamiają `Purchase`.

Przy wdrożeniu lub audycie pomiaru konwersji sprawdzamy źródła zdarzeń i ich zgodność z logiką sklepu. Opis zakresu prac przy CAPI znajduje się też w materiale o kosztach wdrożenia CAPI i pomiaru konwersji.

Zestaw zdarzeń powinien pokazywać końcowy wynik biznesowy i etapy potrzebne do diagnozy ścieżki. Zacznij od konwersji potwierdzanej przez system transakcyjny, a wcześniejsze kroki dodawaj wtedy, gdy pomagają znaleźć konkretny problem.

Nie wybieraj częstszego zdarzenia jako celu tylko dlatego, że ma więcej wystąpień. Wcześniejsze etapy pomagają diagnozować ścieżkę, lecz nie powinny być przedstawiane jako przychód ani zakup. Każde nowe zdarzenie opisz, przypisz do systemu źródłowego i sprawdź na kontrolowanym przypadku.

Na skuteczność kampanii wpływają także struktura reklam, kreacje i odbiorcy. Praktyczne wskazówki dotyczące ich poprawy opisujemy w poradniku jak poprawić kampanie Facebook.

• Meta CAPI Gateway: co to jest i kiedy warto go wdrożyć?
• Jak poprawić konwersję na stronie firmowej na Facebooku
• Optymalizacja kampanii produktowej Google Ads: diagnoza i plan zmian