TikTok Events API: konfiguracja i deduplikacja

TikTok Events API przesyła zdarzenia z serwera sklepu, aplikacji lub CRM bezpośrednio do TikToka. Dla witryny warto uruchomić je obok Piksela, wysyłać te same kluczowe zdarzenia dwoma kanałami i łączyć ich kopie wspólnym event_id. Dostajesz wtedy odporniejszy pomiar, ale tylko pod warunkiem, że zakup nie jest liczony podwójnie. Poniżej wybierzesz metodę integracji, ustawisz deduplikację i wykonasz konkretny test odbiorczy przed skierowaniem budżetu na konwersje.

TikTok Events API i Piksel: jaki układ wybrać

Piksel przekazuje sygnał z przeglądarki. Events API może wysłać to samo działanie z backendu, gdzie potwierdzono płatność albo zmianę statusu leada. TikTok pozwala wdrożyć każdy kanał osobno, lecz dla witryn rekomenduje ich połączenie. Według oficjalnego porównania metod TikToka wspólny układ wspiera pomiar całego lejka, emisję reklam i tworzenie grup odbiorców.

Wybierz model według danych, które naprawdę kontrolujesz:

Sytuacja	Rozsądny start	Warunek odbioru
Prosty landing bez backendu	Piksel	Zdarzenie formularza pojawia się raz
Sklep z gotowym konektorem	Piksel i Events API przez partnera	Zakup ma wartość, walutę i deduplikację
Własny checkout lub CRM	Piksel i integracja bezpośrednia	Status biznesowy uruchamia właściwe zdarzenie
Sprzedaż finalizowana przez handlowca	Events API z CRM, opcjonalnie Piksel dla wcześniejszych etapów	Jeden zaakceptowany lead daje jeden sygnał

Kanał serwerowy nie zmienia zasad zgód ani zakresu dozwolonego wykorzystania danych. Ustal z osobą odpowiedzialną za prywatność, które identyfikatory możesz przekazywać. W planie pomiarowym zapisz także okno raportowania, ponieważ okno atrybucji TikTok Ads odpowiada na inne pytanie niż kompletność zdarzeń.

Konfiguracja TikTok Events API krok po kroku

Najpierw rozpisz jedno zdarzenie, na którym kampania ma się optymalizować. Dla sklepu może to być CompletePayment, wysyłane po potwierdzeniu płatności z wartością i kodem waluty. Dla lead generation wybierz zdarzenie odpowiadające faktycznej kwalifikacji, jeśli taki status istnieje w CRM. Nazwa i moment wywołania muszą być identycznie rozumiane przez marketing oraz dewelopera.

Następnie przejdź ścieżkę w panelu:

1. W TikTok Ads Manager otwórz Tools > Events Manager.
2. Wybierz istniejące źródło danych witryny albo rozpocznij konfigurację nowego.
3. Wybierz integrację partnerską, partnera danych lub bezpośrednie API. Gotowy konektor jest dobrym początkiem, jeśli obsługuje twoje zdarzenie, parametry i deduplikację.
4. Otwórz wybrane źródło, przejdź do Settings, znajdź sekcję Events API i wygeneruj access token dla integracji. Token przechowuj po stronie serwera, poza kodem frontendu i repozytorium.
5. Przekaż deweloperowi Pixel ID, mapę zdarzeń, dozwolone klucze dopasowania oraz regułę generowania event_id.
6. Wyślij najpierw zdarzenia testowe i odbierz je w Test Events, zanim włączysz ruch produkcyjny.

TikTok wymienia integrację partnerską, partnera danych oraz integrację bezpośrednią jako trzy drogi startu. Bezpośrednie API daje największą kontrolę, ale wymaga obsługi tokenu, błędów żądań i monitoringu. Jeśli działasz już na Meta, porównaj zakres z wdrożeniem Conversions API Meta, lecz przygotuj osobną mapę nazw i parametrów dla TikToka.

Deduplikacja przez event_id bez podwójnych zakupów

Deduplikacja jest potrzebna, gdy Piksel i Events API raportują dwie kopie tej samej konwersji. TikTok wymaga wtedy identycznej nazwy zdarzenia i identycznego event_id w obu kanałach. Dokumentacja deduplikacji TikToka podaje, że kopie z tym samym zdarzeniem i identyfikatorem są rozpoznawane w oknie 48 godzin. Pierwsze odebrane zdarzenie zostaje zachowane; druga kopia może uzupełnić jego dane, gdy dotrze odpowiednio szybko.

Najbezpieczniej utworzyć identyfikator raz w systemie źródłowym. Zamówienie numer 84721 może dostać wartość purchase_84721_9f3c. Ten sam ciąg trafia do wywołania Piksela na stronie potwierdzenia oraz do żądania Events API po zapisaniu płatności. Kolejne zamówienie musi mieć inny identyfikator.

Nie generuj dwóch niezależnych UUID w przeglądarce i backendzie. Nie używaj też stałej wartości dla wszystkich zakupów. W obu przypadkach TikTok nie otrzyma stabilnego klucza łączącego kopie. Jeżeli kanały przesyłają rozłączne zdarzenia, na przykład ViewContent wyłącznie przez Piksel i CompletePayment wyłącznie przez serwer, ich deduplikacja nie jest potrzebna.

Test odbiorczy: trzy zakupy i jedna tabela

Przed uruchomieniem kampanii wykonaj trzy hipotetyczne zamówienia testowe po 100 zł. Każde powinno wygenerować jedną kopię przeglądarkową i jedną serwerową z tym samym event_id. W Events Manager > wybrane źródło > Test Events przełącz filtr na zdarzenia Events API, a potem osobno sprawdź kanał przeglądarkowy.

Zapisz wynik w prostej tabeli:

Zamówienie	Kopia Pixel	Kopia Events API	event_id zgodny	Oczekiwany wynik po deduplikacji
84721	1	1	tak	1 zakup, 100 zł
84722	1	1	tak	1 zakup, 100 zł
84723	1	1	tak	1 zakup, 100 zł

Reguła decyzji jest konkretna: nie kieruj kampanii na CompletePayment, dopóki wszystkie trzy testy nie pokazują właściwej nazwy, czasu, wartości, waluty oraz wspólnego event_id w dwóch kanałach. Oczekujesz trzech zakupów o łącznej wartości 300 zł po przetworzeniu, a nie sześciu zdarzeń i 600 zł. Jeśli choć jeden test ma rozbieżność, popraw mapowanie i powtór całą serię od początku.

Sygnał z poprawnie odebranego zakupu może później zasilać grupy niestandardowych odbiorców TikTok. Najpierw upewnij się jednak, że zdarzenie oznacza realne zamówienie, a zwroty i anulowania mają ustalony sposób obsługi.

Diagnostyka po wdrożeniu i cotygodniowa kontrola

Test Events służy do podglądu wywołanych działań, a sekcja Diagnostics pokazuje problemy między innymi z brakującymi parametrami. Karta diagnostyczna wskazuje wagę problemu, dotknięte źródło danych, reklamy oraz przykładowe zdarzenia. Po poprawce daj panelowi czas na przetworzenie i sprawdź, czy problem przestał występować dla nowych danych.

Raz w tygodniu porównaj liczbę opłaconych zamówień w systemie sprzedażowym z liczbą odebranych zdarzeń. Przykład: sklep ma 200 opłaconych zamówień, a źródło danych 150 zdarzeń CompletePayment. Pokrycie wynosi 150 ÷ 200 × 100% = 75%. Traktuj spadek o co najmniej 10 punktów procentowych tydzień do tygodnia jako sygnał do kontroli logów, zgód, zmian w checkout i diagnostyki. Ten próg jest regułą operacyjną, a nie benchmarkiem TikToka.

Konwersje przypisane reklamom będą stanowiły inną liczbę niż wszystkie zdarzenia odebrane przez źródło, ponieważ część sprzedaży pochodzi z innych kanałów. Do oceny kosztu używaj stałej definicji wyniku i zestawiaj go z fazą uczenia kampanii TikTok Ads. Dzięki temu problem techniczny nie zostanie błędnie uznany za zmianę skuteczności kampanii.