Blog o marketingu i technologii

API konwersji Facebooka (ang. Facebook Conversions API) to rozwiązanie do mierzenia interakcji użytkowników w ramach ekosystemu Facebooka. Dzięki niemu usługodawcy są w stanie połączyć swoje internetowe usługi z rozwiązaniami reklamowymi, niezależnie od ustawień prywatności urządzeń końcowych odbiorców i przesyłać bardziej szczegółowe dane. Facebook Conversions API umożliwia stworzenie jakościowych podstaw pod szczegółową analitykę konsumentów na całym etapie lejka sprzedażowego. Do interpretacji tego typu informacji w ramach Facebooka, istnieje dedykowane narzędzie: Facebook Analytics.

Spis treści

  1. Zastosowania Facebook Conversions API
  2. Wady Facebook Conversions API
  3. Jak działa Facebook Conversions API?
  4. Wysyłanie zapytania

Zastosowania Facebook Conversions API

Facebook Conversions API jest rozwiązaniem serwerowym (ang. server-side), przeznaczonym do przesyłania większych ilości danych o odbiorcach korzystających z naszych usług. W przeciwieństwie do innego narzędzia nazywającym się Facebook Pixel, API konwersji Facebooka działa niezależnie od urządzeń odbiorców. Co to oznacza? Mianowicie:

  • mierzenie danych jest ograniczone głównie konstrukcją usługi: klienci nie mają świadomości o tym, iż są obserwowani przez narzędzia analityczne
  • odbiorcy nie są w stanie zablokować integracji: jest to bardzo ważne w okresie rosnącej popularności rozwiązań producentów oprogramowania do ochrony prywatności. Wszystkie operacje nie dzieją się, tak jak ma to miejsce np. w Facebook Pixel, na urządzeniu konsumenta, tylko po stronie serwera, przez co przeglądarki i inne programy nie wykrywają integracji tego typu
  • informacje są bardziej precyzyjne: obecnie odbiorcy przy minimalnej świadomości programistycznej są w stanie manipulować końcowymi danymi, przez co mogą zaburzyć dokładność pomiarów (np. wysyłając celowo X razy informację o zakupie Y produktów za cenę Z, faktycznie tego nie robiąc)
  • dokładniejsza segmentacja audiencji: Facebook Conversions API pozwala (i zaleca) na przesyłanie wielu szczegółowych informacji, takich jak adres e-mail, numer telefonu, wewnętrzny identyfikator odbiorcy w ramach usługi, kod pocztowy itd. Ta możliwość, w połączeniu z brakiem możliwości jakiejkolwiek manipulacji po stronie odbiorcy, pozwala na dokładniejsze podzielenie odbiorców w podgrupy, np.: grupa osób, która zrealizowała zakupy, ale wcześniej zrobiła szereg innych czynności

Jak widać, możliwości jest bardzo dużo i niewątpliwie, rosnąca popularność tego rozwiązania, przyczyni się do dokładniejszego spojrzenia na kwestie analityczne obsługiwanych usług.

Wady Facebook Conversions API

Interfejs programistyczny Facebooka dostarcza wiele ścieżek określania profilu naszych odbiorców, jednak wiąże się ono z pewnymi wadami:

  • mierzenie danych jest ograniczone głównie konstrukcją usługi: wada, która jednocześnie jest zaletą. Jak na początku wspomniałem, Facebook Conversions API jest rozwiązaniem serwerowymi (ang. server-side), a nie klienckim (ang. client-side), takim jak np. Facebook Pixel. Implementacja tego API wiąże się z modyfikacją usługi, co może wiązać się z utrudnieniami na etapie programistycznym
  • wymagana wiedza programistyczna: załączenie tego rozwiązania jest niemożliwe bez posiadania specjalistycznej wiedzy. Mimo obecności już gotowych rozwiązań na rynku dochodzi szereg problemów na etapie serwisowania oprogramowania (m.in. elastyczność podpięcia, aktualizacje itd.). Działania tego typu wymagają przeznaczenia odpowiednich zasobów (finansowych i/lub czasowych)
  • problem ze skalowaniem: popularne narzędzie Facebook Pixel wysyła informacje po stronie klienta (ang. client-side) — jedynym obowiązkiem osób dokonujących integracji, jest zainstalowanie odpowiedniego skryptu śledzącego i oznaczenie miejsc raportowania (szczegółowo opisałem to tutaj). Pozostałe procesy dzieją się samodzielnie i niezależnie od infrastruktury usługi, dane są przesyłane do Facebooka. Przy rozwiązaniach serwerowych, trzeba uwzględnić natężenie ruchu, a co za tym idzie, generowane obciążenie: im więcej ruchu, tym jest ono większe
  • szczegółowa analiza ścieżek klienta: samo wysyłanie informacji nic nie daje, jeśli nie wyznaczy się obiegu odbiorcy w ramach oferowanej usługi. Jak będziesz mieć okazję przekonać się poniżej, kluczowe dla przesyłania informacji jest to, by móc "łapać" odbiorcę w momentach, w których ujawni swoją tożsamość: poprzez zostawienie adresu e-mail, zarejestrowanie się itd. Samo wysłanie konwersji jest tylko oznaczeniem tego, że dana interakcja została wykonana: bez danych identyfikujących nie będziesz w stanie określić, kto to zrobił i dotrzeć do niego w późniejszym czasie (np. poprzez remarketing)

Zapewniam jednak, iż warto pokonać wyżej wymienione trudności i zacząć działać już dziś: zmiany w zakresie przepływu danych następują szybko.

Jak działa Facebook Conversions API?

Kluczem do zrozumienia działania Facebook Conversions API jest ustalenie niezbędnych struktur danych, z jakimi zachodzi styczność podczas raportowania konwersji oraz sposoby wiązania danych z konkretnym odbiorcą. Niezbędna tutaj także jest znajomość funkcjonowania Facebook Pixel, którą opisałem w tym wpisie. Dodatkowo poruszę kwestię związaną z walidacją duplikatów zapytań.

Wiązanie danych z konkretnym odbiorcą

Na chwilę pisania artykułu, podstawowym sposobem identyfikacji odbiorców są ciasteczka (ang. cookies) — specjalnych pakietów, przechowujących dane. Facebook, jako podmiot zewnętrzny dla naszej usługi, korzysta z plików cookies kategorii trzeciej (ang. third-party cookies), dzięki czemu wiąże nas ze swoimi bazami danych i śledzi aktywność na każdej witrynie, gdzie jest zainstalowany Facebook Pixel. Dane, jakie zapisuje, są dwa:

  • ciastko _fbp: identyfikator naszej przeglądarki (generowany przez Facebooka)
  • ciastko _fbc: identyfikator lokalizacji, z której dotarliśmy na stronę, np. reklamy (generowany na podstawie danych od Facebooka)

Ponadto, istnieje możliwość (lub przymus, jeśli nie jest możliwe dostarczenie dwóch powyższych identyfikator i chcemy docierać do naszego odbiorcy) uzupełnienia stosu danych o naszym konsumencie, wśród których zalicza się m.in.:

  • adres e-mail
  • numer telefonu
  • miasto, województwo, kod pocztowy

Lista wszystkich parametrów znajduje się tutaj.

Ciasteczko _fbc

Ciasteczko _fbc różni się od _fbp tym, iż jest ono generowane na podstawie informacji przesłanych przez Facebook, a nie przez niego samego. Oznacza to tyle, że należy je samodzielnie wygenerować. Przydatny może być poniższy fragment kodu (który napisałem na potrzeby tego wpisu w PHP, jednym z najpopularniejszych języków programowania na świecie):

<?php

class FacebookParameterBuilder
{

    private $version = "fb";
    private $index;
    private $creationTime;
    private $value;

    public function setIndex(int $index)
    {
        $this->index = $index;
    }

    public function setCreationTime(float $creationTime)
    {
        $this->creationTime = $creationTime;

        return $this;
    }

    public function setValue(string $value)
    {
        $this->value = $value;

        return $this;
    }

    public function build()
    {
        if ($this->index == null || $this->creationTime == null || $this->value == null
            || empty($this->index) || empty($this->creationTime) || empty($this->value))
        {
            throw new InvalidArgumentException('All fields must be filled');
        }

        return $this->version . "." . $this->index . "." . $this->creationTime . "." . $this->value;
    }

}

Ciastko _fbc składa się z czterech elementów:

  • version: jest to prefiks ciastka, zawsze ma wartość fb
  • subdomainIndex, bądź index: definiuje lokację stworzenia naszego ciasteczka (jeśli cookie jest generowany w warstwie serwerowej, powinien być zawsze 1)
  • creationTime: czas w formacie UNIX, który oznacza chwile stworzenia ciasteczka
  • value: właściwa wartość ciastka, która jest generowana z parametru fbclid zawartego w linku, na który przekierowuje nas Facebook

Każdy z tych elementów jest oddzielony znakiem kropki (.), na przykład:

fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

Struktura zdarzenia

Strukturę zdarzenia należy podzielić na część serwerową i zawartą w niej część własną.

Część serwerowa określa główny fragment struktury zapytania, w niej określamy takie podstawowe informacje jak nazwa konwersji, czas jej przesłania, czy źródło:

{
    "event_name": "Purchase",
    "event_time": 0000000000,
    "user_data": {
        "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"
    },
    "custom_data": {
        "currency": "PLN",
        "value": "100"
    }
}
Przykładowe zapytanie warstwy serwerowej

Część własna z kolei definiuje własności każdego ze zdarzeń: opisuje konkretne wartości i zawiera niestandardowe informacje. Pola tego typu muszą być w obiekcie custom_data.

Duplikaty zdarzeń

Niespójności w analityce są jedną z najbardziej niechcianych rzeczy, na szczęście Facebook Conversions API posiada mechanizm eliminujący tę niedogodność. Jeśli dane są przesyłane jednocześnie poprzez kod śledzący Facebook Pixel i API konwersji, wystarczy do części serwerowej załączyć pole z unikalną wartością dla każdego z wydarzeń: event_id. Dzięki temu, dla wszystkich kombinacji związanych z tożsamą konwersją i tym samym unikalnym identyfikatorem, wydarzenia nie zostaną przetworzone.

Następnie, należy oznaczyć wydarzenia przesyłane przez Facebook Pixel tym samym zestawem informacji:

fbq('track', 'Purchase', {currency: "PLN", value: 50.00}, {eventID: "EVENT_ID"});
Przykładowa implementacja zdarzenia w Facebook Pixel z uwzględnieniem mechanizmu duplikacji zdarzeń

Wysyłanie zapytania

Po stworzeniu struktury zdarzeń i zadbaniu o wymagane dane należy opakować nasze wydarzenia w obiekt data:

{
    "data": [
        {
           "event_name": "Purchase",
           "event_time": 0000000000,
           "user_data": {
               "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"
           },
           "custom_data": {
               "currency": "PLN",
               "value": "100"
          }
       }
    ]
}

Przy tworzeniu całego ciała zapytania warto pamiętać, iż limit zdarzeń na jedno zapytanie wynosi 1000.

Następnie, pozostaje wykonanie zapytania typu POST na określony adres URL (na przykładzie pakietu curl):

curl -X POST \
  -F 'data=[
       {
           "event_name": "Purchase",
           "event_time": 0000000000,
           "user_data": {
               "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"
           },
           "custom_data": {
               "currency": "PLN",
               "value": 100
           }
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v9.0/<PIXEL_ID>/events
Przykładowe polecenie pakietu curl

Token dostępu

Każda wysłana paczka danych musi być podpisana odpowiednim kluczem autoryzacyjnym. Wygenerować można go w ustawieniach Piksela, podłączonego pod konto reklamowe:

Następnie, w parametrze zapytania access_token należy zamienić przykładową wartość <ACCESS_TOKEN> na wygenerowany klucz.

Tutaj warto także wspomnieć o podsekcji Konfiguracja za pośrednictwem integracji partnerskiej, gdzie Facebook udostępnia już gotowe rozwiązania dla wybranych platform z instrukcją krok po kroku.

Przykładowe menu wyboru platform
Początek ścieżki dialogowej dla integracji WooCoomerce

Testowanie zdarzeń

Jednym z narzędzi diagnostycznych do prawidłowej weryfikacji instalacji śledzenia danych jest Testowanie zdarzeń. W ramach niego dostajemy pogrupowane wydarzenia wraz ze szczegółami, które są przesyłane.

Oprócz mierzenia interakcji z poziomu przeglądarki Facebook umożliwia podpisywanie zapytań specjalnym parametrem testowym, który powoduje wyszczególnienie zdarzeń w tej sekcji. Wystarczy, iż to ciała zapytania dołożymy parametr test_event_code z wyróżnioną zawartością.

{
    "data": [
        {
           "event_name": "Purchase",
           "event_time": 0000000000,
           "user_data": {
               "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"
           },
           "custom_data": {
               "currency": "PLN",
               "value": 100
          }
       }
    ],
    "test_event_code": "TEST00000"
}
Zapytanie warstwy testowej z kodem testowym

Obsługa błędów

Obsługa błędów jest istotna dla pracy z Facebook Conversions API i lokalizowania źródeł nieprawidłowego funkcjonowania raportowania danych z usługi. Domyślnie zapytanie powinno zwracać kod zapytania HTTP 2xx, jeśli wystąpi błąd: 4xx. W celu uzyskania dokładnej informacji o niepowodzeniu należy zmodyfikować URL zapytania w następujący sposób:

https://graph.facebook.com/v9.0/<PIXEL_ID>/events?trace=[1-3]

W miejsce wartości parametru trace funkcjonują następujące wartości:

  • 1 - wyświetlenie szczegółów błędu
  • 2 - wyświetlenie ogólnych informacji
  • 3 - wyświetlenie informacji deweloperskich

Facebook Conversions API to inny standard przesyłania danych, jednak jak możesz zauważyć — bardzo wartościowy i nadający nowe znaczenie analityce działań z kanału dystrybucji treści, jakim jest Facebook.