Meta Conversions API (CAPI): co to jest i jak skonfigurować na stronie

Czym jest Meta Conversions API

Meta Conversions API (w skrócie CAPI lub Facebook Conversions API) to serwerowy kanał przesyłania danych między Twoją stroną internetową a platformą Meta Ads. W odróżnieniu od Meta Pixel, który działa w przeglądarce użytkownika, CAPI wysyła zdarzenia konwersji bezpośrednio z Twojego serwera na serwery Meta za pomocą bezpiecznego żądania HTTPS.

Oficjalna nazwa to Meta Conversions API. Przed zmianą nazwy firmy w 2021 roku narzędzie nazywało się Facebook Conversions API lub Facebook CAPI. Obie nazwy są nadal powszechnie używane w branży i odnoszą się do dokładnie tego samego narzędzia.

Zasada działania: zamiast przeglądarki odwiedzającego wysyłającej dane do Facebooka (jak robi to Piksel), Twój serwer samodzielnie wysyła ustrukturyzowane żądanie JSON z danymi o zdarzeniu — zakupie, rejestracji lub wysłaniu formularza — bezpośrednio do Graph API Meta. Przeglądarka nie jest w tym procesie zaangażowana.

Dlaczego powstało Meta CAPI: problem utraty danych

Od 2021 roku reklamodawcy borykają się z poważnym problemem atrybucji. Jest kilka przyczyn:

1. iOS 14.5+ i framework ATT. Apple zobowiązała wszystkie aplikacje iOS do proszenia użytkownika o zgodę na śledzenie. Większość użytkowników odmawia — i Meta Pixel przestaje rejestrować ich konwersje. Użytkownicy iOS stanowią od 40 do 60% ruchu mobilnego na większości rynków europejskich.
2. Blokery reklam i rozszerzenia prywatności. uBlock Origin, Privacy Badger, przeglądarka DuckDuckGo — te narzędzia blokują żądania JavaScript piksela zanim w ogóle zdąży się załadować. Odsetek użytkowników blokerów reklam w Polsce przekracza 35–40%.
3. Ograniczenia plików cookie stron trzecich. Chrome stopniowo rezygnuje z third-party cookies. Safari i Firefox już je ograniczyły. Bez plików cookie atrybucja na podstawie kliknięć znacznie się pogarsza.
4. Blokery treści w przeglądarkach. Brave, Firefox Enhanced Tracking Protection i inne agresywnie filtrują żądania do znanych domen reklamowych — w tym connect.facebook.net.

Wynik: według danych Meta i niezależnych badań, sam Meta Pixel bez CAPI rejestruje średnio tylko 60–70% rzeczywistych konwersji. Pozostałe 30–40% po prostu znika — wydajesz budżet, ale algorytm nie widzi efektów i błędnie optymalizuje kampanie.

Conversions API rozwiązuje ten problem w sposób fundamentalny: ponieważ żądanie pochodzi z Twojego serwera, a nie z przeglądarki, żaden bloker reklam, ograniczenie iOS ani reguła przeglądarki nie może go zablokować.

CAPI vs Meta Pixel: kluczowe różnice

CAPI nie zastępuje Meta Pixel — uzupełnia go. Te dwa narzędzia rozwiązują różne problemy i najlepiej działają razem.

Złota zasada: uruchamiaj Pixel + CAPI jednocześnie. Pixel lepiej śledzi sygnały behawioralne (kliknięcia, przewijanie, mikrokonwersje), a CAPI obsługuje finalne konwersje (zakupy, leady). Razem dają Meta kompletny sygnał potrzebny do skutecznego uczenia algorytmu.

Jak Meta Conversions API przesyła dane

Technicznie CAPI to żądanie POST do Graph API Meta. Oto uproszczony przykład zdarzenia Purchase:

POST https://graph.facebook.com/v19.0/{PIXEL_ID}/events?access_token={TOKEN}

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1716900000,
    "event_id": "order_12345",
    "action_source": "website",
    "event_source_url": "https://yoursite.com/checkout/success",
    "user_data": {
      "em": ["a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"],
      "ph": ["1234567890abcdef..."],
      "client_ip_address": "203.0.113.1",
      "client_user_agent": "Mozilla/5.0..."
    },
    "custom_data": {
      "value": 299.00,
      "currency": "PLN",
      "order_id": "12345"
    }
  }]
}

Kilka ważnych szczegółów:

1. Haszowanie danych osobowych. Dane osobowe (email, telefon) są przesyłane jako hasze SHA-256, nigdy jako zwykły tekst. To wymóg RODO i zasad Meta.
2. event_id do deduplikacji. Jeśli wysyłasz to samo zdarzenie zarówno przez Pixel, jak i CAPI, użyj tego samego event_id, aby Meta nie liczyła go dwukrotnie.
3. action_source. Określa, skąd pochodzi zdarzenie: website, app, email, phone_call itp.
4. Access Token. Każde żądanie jest uwierzytelniane za pomocą tokena dostępu System User generowanego w Business Managerze.

3 sposoby konfiguracji Meta Conversions API

Meta oferuje kilka podejść w zależności od możliwości technicznych i używanej platformy:

Metoda 1: Integracja z partnerem (bez kodu)

Najprostszy wariant — połączenie CAPI przez gotową integrację w Events Managerze. Meta ma oficjalne partnerstwa z dziesiątkami platform:

• WooCommerce — wtyczka Facebook for WooCommerce automatycznie wysyła zdarzenia przez CAPI
• Shopify — natywna integracja w Shopify Admin → Sales Channels → Facebook
• Magento / Adobe Commerce — oficjalna wtyczka Meta Business Extension
• BigCommerce, PrestaShop, OpenCart — przez Meta Business Extension
• Wix, Squarespace — przez wbudowane integracje marketingowe

Kroki połączenia przez Events Manager:

1. Otwórz Meta Events Manager → wybierz swój piksel.
2. Przejdź do zakładki Settings → sekcja Conversions API.
3. Kliknij Connect a partner.
4. Wybierz swoją platformę (np. WooCommerce) i postępuj zgodnie z instrukcjami.
5. Autoryzuj połączenie i określ, które zdarzenia mają być wysyłane.
6. Zweryfikuj konfigurację w sekcji Test Events.

Metoda 2: Przez Google Tag Manager (GTM)

Jeśli Twoja strona korzysta z GTM, możesz skonfigurować CAPI przez dedykowany tag Meta bez pisania kodu po stronie serwera. Wymaga to Server-Side GTM — oddzielnego kontenera Google Cloud, który pełni rolę serwera proxy.

1. Skonfiguruj kontener Server-Side GTM (Google Cloud Run lub App Engine).
2. W kontenerze serwerowym GTM dodaj tag Facebook Conversions API (oficjalny od Meta lub od stron trzecich, np. Stape.io).
3. Skonfiguruj wyzwalacze — które zdarzenia przekazywać (Purchase, Lead, ViewContent itp.).
4. Wprowadź swój Pixel ID i Access Token.
5. Dodaj event_id — identyczny dla Pixel i CAPI, aby uniknąć duplikatów.
6. Opublikuj kontener i zweryfikuj w Meta Events Manager → Test Events.

Zalety podejścia GTM: nie potrzeba programisty backendowego, logikę można szybko zmieniać przez interfejs GTM, łatwo skalowalne na inne platformy. Wada: Server-Side GTM wymaga hostingu na Google Cloud (~5–20 USD/mies.).

Metoda 3: Bezpośrednia integracja serwerowa (kod)

Najbardziej elastyczny wariant — implementacja CAPI bezpośrednio w Twoim backendzie. Meta udostępnia oficjalne SDK dla Python, PHP, Node.js, Ruby i Java.

Przykład w PHP (WordPress/WooCommerce):

// Po udanym płatności zamówienia WooCommerce
add_action('woocommerce_payment_complete', function($order_id) {
    $order = wc_get_order($order_id);

    $payload = [
        'data' => [[
            'event_name'       => 'Purchase',
            'event_time'       => time(),
            'event_id'         => 'wc_order_' . $order_id,
            'action_source'    => 'website',
            'event_source_url' => home_url('/checkout/order-received/'),
            'user_data'        => [
                'em' => [hash('sha256', strtolower(trim($order->get_billing_email())))],
                'ph' => [hash('sha256', preg_replace('/D/', '', $order->get_billing_phone()))],
            ],
            'custom_data' => [
                'value'    => (float) $order->get_total(),
                'currency' => 'PLN',
                'order_id' => strval($order_id),
            ],
        ]]
    ];

    wp_remote_post(
        'https://graph.facebook.com/v19.0/YOUR_PIXEL_ID/events?access_token=YOUR_TOKEN',
        ['body' => json_encode($payload), 'headers' => ['Content-Type' => 'application/json']]
    );
});

Deduplikacja: jak unikać podwójnego liczenia

Gdy Pixel i CAPI działają jednocześnie — zarówno przeglądarka, jak i serwer wysyłają zdarzenie Purchase dla tego samego zamówienia. Bez deduplikacji Meta policzy to jako 2 konwersje zamiast 1, co zniekształci raporty i zaszkodzi optymalizacji.

Rozwiązaniem jest pole event_id. Zasada jest prosta:

1. Wygeneruj unikalny event_id dla każdego zdarzenia (np. purchase_12345 lub UUID).
2. Przekaż ten sam event_id w kodzie Pixel w przeglądarce:

fbq('track', 'Purchase', {value: 299.00, currency: 'PLN'}, {eventID: 'purchase_12345'});

3. Przekaż ten sam event_id w żądaniu serwerowym CAPI (pole event_id w JSON).
4. Meta automatycznie zidentyfikuje duplikat i policzy zdarzenie tylko raz.

Okno deduplikacji: Meta porównuje zdarzenia w oknie 48 godzin. Jeśli dwa żądania mają ten sam event_id, tę samą event_name i są wysłane w ciągu 48 godzin — liczone jest tylko jedno.

Które zdarzenia wysyłać przez CAPI

Meta CAPI obsługuje wszystkie standardowe zdarzenia Pixel i zdarzenia niestandardowe. Priorytety dla transmisji przez CAPI:

Rekomendacja Spilno Agency: zawsze wysyłaj Purchase i Lead przez CAPI — to konwersje, na których uczy się algorytm. Pozostałe zdarzenia możesz zostawić tylko w Pixel.

Jak zweryfikować działanie Meta CAPI

1. Otwórz Meta Events Manager → swój piksel → zakładka Test Events.
2. Skopiuj kod testowy (TEST12345) i dodaj go do żądań CAPI jako parametr test_event_code.
3. Wykonaj testowy zakup lub wywołaj zdarzenie na stronie.
4. W sekcji Test Events zobaczysz otrzymane zdarzenia w czasie rzeczywistym.
5. Sprawdź sekcję Activity — wyświetla jakość i kompletność danych.
6. Zwróć uwagę na Event Match Quality (EMQ) — docelowy wynik od 6 do 10. Im więcej danych o użytkowniku przekazujesz (email + telefon + IP), tym wyższy EMQ.

Typowe błędy przy konfiguracji CAPI

1. Brak deduplikacji. Uruchamiasz Pixel i CAPI bez event_id — Meta liczy duplikaty, a ROAS wydaje się zawyżony.
2. Opóźnienie wysyłania. Wysyłasz zdarzenie CAPI kilka godzin po rzeczywistej konwersji. Pole event_time musi odzwierciedlać rzeczywisty czas zdarzenia (nie czas wysyłania).
3. Nieprawidłowe haszowanie. E-mail musi być zamieniony na małe litery i przycięty PRZED haszowaniem: hashlib.sha256(email.lower().strip().encode()).
4. Brak action_source. To pole jest wymagane. Dla zdarzeń ze strony internetowej — użyj "website".
5. Tylko CAPI bez Pixel. Niektóre dane behawioralne (ViewContent, AddToCart) są lepiej śledzone przez Pixel. Optymalna strategia to oba kanały.

Często zadawane pytania o Meta Conversions API

Czy Meta Pixel jest wymagany do działania CAPI?

Nie, technicznie CAPI może działać samodzielnie. Jednak Meta zaleca używanie obu narzędzi razem: Pixel do danych behawioralnych w przeglądarce, CAPI do finalnych konwersji na serwerze. Razem zapewniają najszersze pokrycie.

Czy CAPI jest zgodny z RODO?

CAPI jest z natury bardziej przyjazny prywatności niż Pixel, ponieważ nie używa plików cookie przeglądarki. Jednak odpowiedzialność za uzyskanie zgody od użytkownika (Consent Mode) spoczywa na Tobie. Przed wysłaniem danych przez CAPI upewnij się, że masz podstawę prawną (zgoda lub uzasadniony interes) do przetwarzania danych osobowych zgodnie z RODO.

Ile czasu zajmuje konfiguracja CAPI?

Zależy od metody: integracja z partnerem (WooCommerce, Shopify) — od 30 minut do 2 godzin. Server-Side GTM — od 4 do 8 godzin (wymaga konfiguracji Google Cloud). Bezpośrednia integracja serwerowa — od 1 do 3 dni w zależności od złożoności backendu.

Czym jest Event Match Quality (EMQ)?

Event Match Quality (EMQ) to wskaźnik od 0 do 10 w Meta Events Managerze, który mierzy, jak dobrze Twoje zdarzenia serwerowe pasują do profili użytkowników Facebooka. Wyższy EMQ = lepsza atrybucja = dokładniejsza optymalizacja. Aby osiągnąć EMQ 7+, przekazuj: email (zahaszowany), telefon (zahaszowany), adres IP, User Agent, pliki cookie fbp/fbc.

Czy CAPI może wysyłać konwersje offline?

Tak. CAPI obsługuje pole action_source: "physical_store" i inne źródła offline. Pozwala to przesyłać dane z systemów CRM, kas fiskalnych lub call center — i przypisywać sprzedaż offline do kampanii online.

Podsumowanie

Meta Conversions API to już nie opcja — to konieczność dla każdej firmy poważnie inwestującej w reklamy na Facebooku i Instagramie. Przy iOS 14.5+, blokerach reklam i ograniczeniach plików cookie, sam Pixel traci od 30 do 40% danych o konwersjach — co bezpośrednio osłabia optymalizację kampanii reklamowych.

Zalecane podejście: uruchamiaj Pixel + CAPI jednocześnie, zawsze konfiguruj deduplikację przez event_id i monitoruj Event Match Quality. Jeśli dopiero zaczynasz — skorzystaj z integracji z partnerem przez Events Manager. Dla maksymalnej kontroli — Server-Side GTM lub bezpośrednia integracja serwerowa.

Masz pytania dotyczące konfiguracji Meta CAPI dla Twojego projektu? Skontaktuj się z Spilno Agency — skonfigurujemy śledzenie po stronie serwera i odzyskamy utracone dane konwersji.

Instrukcja krok po kroku: konfiguracja CAPI przez Server-Side GTM

Krok 1: Otwórz Events Manager i wybierz swój zestaw danych

Przejdź do Meta Events Manager i otwórz zestaw danych, do którego chcesz podłączyć CAPI. Jeśli nie masz jeszcze zestawu, kliknij ’Połącz dane’, aby utworzyć nowy.

Krok 2: Połącz konta reklamowe z zestawem danych

Wybierz konta reklamowe, które powinny mieć dostęp do tego zestawu danych. Zazwyczaj jest to Twoje główne konto Meta Ads.

Krok 3: Kliknij 'Połącz dane’

Na ekranie głównym Events Manager kliknij przycisk ’Połącz dane’, aby rozpocząć proces podłączania źródła danych.

Krok 4: Wybierz 'Internet’ jako źródło danych

Z listy źródeł danych wybierz ’Internet’ — oznacza to śledzenie zdarzeń na Twojej witrynie. Kliknij ’Dalej’.

Krok 5: Wybierz 'Skonfiguruj Conversions API’

Na ekranie podłączania danych witryny wybierz opcję ’Skonfiguruj Conversions API’. Meta pokazuje szacunkowe obniżenie kosztu wyniku o ~19% przy używaniu CAPI.

Krok 6: Metoda GTM jest zalecana

Meta automatycznie zaleca konfigurację CAPI przez Google Tag Manager, wskazując na ~31% redukcję kosztu za wynik. Kliknij ’Dalej’, aby kontynuować.

Krok 7: Czego będziesz potrzebować

Do konfiguracji CAPI przez GTM potrzebujesz: kontenera GTM web (już zainstalowanego na witrynie) i kontenera serwera GTM (nowego, na Google Cloud lub Stape). Cały proces zajmuje ~30 minut i nie wymaga programisty.

Krok 8: Wybierz swój kontener GTM web

Z listy rozwijanej wybierz swoje konto Google Tag Manager i kontener GTM web zainstalowany na Twojej witrynie. Jeśli GTM nie jest jeszcze podłączony, najpierw dodaj go do witryny.

Krok 9: Wybierz hosting dla kontenera serwera

Wybierz hosting dla kontenera serwera: Google Cloud (~5–20 USD/mies., automatyczna konfiguracja w ~30 min) lub Stape (freemium, łatwiejsza konfiguracja w ~15 min). Dla początkujących zalecamy Google Cloud.

Krok 10: Utwórz nowy kontener serwera w GTM

Przejdź do swojego konta Google Tag Manager i kliknij ’Utwórz kontener’. Potrzebujesz nowego kontenera z typem platformy ustawionym na ’Serwer’.

Krok 11: Ustaw typ platformy na 'Serwer’

Wpisz nazwę kontenera (np. yoursite.com - server) i w polu ’Platforma’ wybierz ’Serwer’. Kliknij ’Utwórz’.

Krok 12: Automatyczna konfiguracja serwera Google Cloud

Wybierz ’Automatycznie zapewnij serwer’ — GTM wdroży kontener Cloud Run w Twoim projekcie Google Cloud. To najprostszy sposób bez ręcznej konfiguracji infrastruktury.

Krok 13: Wybierz konto rozliczeniowe i utwórz serwer

Wybierz konto rozliczeniowe Google Cloud (lub utwórz nowe) i kliknij ’Wybierz konto rozliczeniowe i utwórz serwer’. Google automatycznie wdroży instancję Cloud Run (~5–10 minut).

Krok 14: Serwer został pomyślnie utworzony

GTM wyświetli URL kontenera serwera (format: https://server-side-tagging-xxxxxxxx-uc.a.run.app) i ID projektu Google Cloud. Skopiuj ten URL — będzie potrzebny w następnym kroku.

Krok 15: GTM — serwer utworzony. Skopiuj URL Cloud Run

Po zakończeniu automatycznej konfiguracji GTM wyświetli dialog ’Serwer utworzony’ z konfiguracją kontenera i adresem URL Cloud Run. Skopiuj ten URL — będzie potrzebny w następnym kroku w Meta Events Manager.

Krok 16: Znajdź swój identyfikator pomiaru GA4

Przejdź do Google Analytics 4 → Administrator → Strumienie danych → Twój strumień. Tutaj znajdziesz identyfikator pomiaru w formacie G-XXXXXXXXXX. Meta potrzebuje tego ID do prawidłowej atrybucji.

Krok 17: Skopiuj identyfikator pomiaru GA4

Kliknij ikonę kopiowania obok identyfikatora pomiaru (G-XXXXXXXXXX). Na dole ekranu pojawi się potwierdzenie 'Skopiowano do schowka’.

Krok 18: Wpisz ID GA4 i opublikuj

Wróć do Meta Events Manager. W kroku ’Opublikuj’ wklej skopiowany identyfikator pomiaru GA4 w odpowiednie pole i kliknij ’Opublikuj’. CAPI przez GTM jest teraz aktywne!