TikTok Pixel i Events API: wdrożenie, deduplikacja i najczęstsze błędy

Pixel czy Events API: co mierzy każdy kanał

Oba kanały wysyłają te same zdarzenia, ale z różnych miejsc i z innym zestawem danych. Piksel widzi przeglądarkę, a Events API – system sklepu albo kontener serwerowy.

W praktyce najczęściej spotyka się trzy warianty: tylko piksel (najprostszy, ale z największymi stratami danych), piksel z Events API przez integrację platformy sklepowej oraz piksel z Events API przez server-side tagging. Ostatni wariant daje najwięcej kontroli i pozwala obsłużyć TikToka z tego samego kontenera co Meta, którego konfigurację opisujemy w poradniku Meta Conversions API przez server-side GTM.

Jak wdrożyć TikTok Pixel z event_id

Kod bazowy piksela pobierasz z Events Managera w TikTok Ads Manager albo instalujesz przez szablon piksela w galerii szablonów GTM. Niezależnie od metody każde zdarzenie, które ma trafić także przez Events API, musi otrzymać event_id w trzecim argumencie funkcji ttq.track.

// Rozszerzone dopasowanie dla zalogowanego klienta lub po złożeniu zamówienia
ttq.identify({
  email: '<SHA-256 adresu e-mail>',
  phone_number: '<SHA-256 numeru telefonu>',
  external_id: '<SHA-256 identyfikatora klienta>'
});

// Zakup z identyfikatorem wspólnym dla piksela i Events API
ttq.track('Purchase', {
  contents: [
    { content_id: 'SKU-001', content_type: 'product', quantity: 1, price: 259.99 }
  ],
  value: 259.99,
  currency: 'PLN'
}, {
  event_id: 'ord-2026-104578'
});

Wartości content_id powinny odpowiadać identyfikatorom produktów w katalogu TikToka. Jeśli prowadzisz kampanie katalogowe, niezgodność identyfikatorów w zdarzeniach i w feedzie produktowym uniemożliwia dopasowanie konwersji do produktów. Jak utrzymać spójne identyfikatory w kilku kanałach, opisujemy w tekście o jednym feedzie dla Google, Meta, TikToka i Allegro.

Dane do tagów najlepiej czerpać z jednej warstwy danych e-commerce, z której korzystają też GA4 i Meta. Gotową specyfikację dla programisty zawiera artykuł o warstwie danych dla e-commerce GA4. Jeśli tag TikToka wdrażasz jako Custom HTML, rozważ zastąpienie go szablonem, co omawiamy w poradniku o szablonach niestandardowych w GTM.

Jak skonfigurować TikTok Events API krok po kroku

Konfiguracja Events API zaczyna się w Events Managerze, a kończy testem zdarzenia z kodem testowym. Poniższe kroki dotyczą integracji przez kontener serwerowy lub własny backend.

1. W Events Managerze wybierz źródło danych typu web i piksel, do którego chcesz wysyłać zdarzenia.
2. W ustawieniach piksela wygeneruj token dostępu do Events API i zapisz go w bezpiecznym miejscu na serwerze.
3. Wybierz metodę integracji: aplikację lub wtyczkę platformy sklepowej, szablon tagu w kontenerze serwerowym GTM albo bezpośrednie wywołania API z backendu.
4. Ustal listę zdarzeń wysyłanych oboma kanałami i nazwy zgodne z tymi, które optymalizujesz w kampaniach.
5. Przekazuj w każdym zdarzeniu event_id, event_time, dane strony oraz dane użytkownika: ttclid, ttp, IP, user agent i zahaszowane identyfikatory.
6. W narzędziu testowania zdarzeń pobierz kod testowy, dodaj go do zdarzeń serwerowych i złóż testowe zamówienie.
7. Sprawdź, czy zdarzenie z piksela i z serwera zostały rozpoznane jako jedno, a potem usuń kod testowy i opublikuj zmiany.

Uproszczona struktura zdarzenia w Events API wygląda tak. Nazwy pól i wersję interfejsu potwierdź w aktualnej dokumentacji TikToka, bo zmieniają się między wersjami:

{
  "event_source": "web",
  "event_source_id": "TWOJ_PIXEL_ID",
  "data": [{
    "event": "Purchase",
    "event_time": 1793095200,
    "event_id": "ord-2026-104578",
    "user": {
      "email": "<SHA-256 adresu e-mail>",
      "phone": "<SHA-256 numeru telefonu>",
      "external_id": "<SHA-256 identyfikatora klienta>",
      "ttclid": "<wartość ttclid z kliknięcia>",
      "ttp": "<wartość pliku _ttp>",
      "ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (...)"
    },
    "properties": {
      "currency": "PLN",
      "value": 259.99,
      "content_type": "product",
      "contents": [{ "content_id": "SKU-001", "quantity": 1, "price": 259.99 }]
    },
    "page": { "url": "https://twojsklep.pl/zamowienie/dziekujemy/" }
  }]
}

Zwróć uwagę na event_time. W tej strukturze to znacznik czasu w sekundach, a nie w milisekundach, jak w niektórych innych API. Pomyłka sprawia, że zdarzenie ma datę z odległej przyszłości i zostaje odrzucone.

Deduplikacja w TikToku: zasady i event_id

Deduplikacja zdarzeń w TikToku dotyczy tylko zdarzeń wysyłanych podwójnie. Jeśli AddToCart idzie wyłącznie z piksela, a Purchase wyłącznie z serwera, nie ma czego scalać. Gdy ten sam zakup idzie oboma kanałami, obowiązują następujące zasady:

1. Oba zdarzenia muszą mieć identyczną nazwę (event) i identyczny event_id.
2. TikTok porównuje zdarzenia w oknie 48 godzin od pierwszego z nich.
3. Pierwsze otrzymane zdarzenie zostaje zachowane i uzupełnione, a duplikat nie jest liczony osobno.
4. Ta sama reguła działa dla duplikatów w obrębie jednego kanału, np. dwóch zdarzeń z piksela po odświeżeniu strony podziękowania.

Najlepszym event_id dla zakupu jest numer zamówienia, bo jest znany i w przeglądarce, i w systemie sklepu. Dla pozostałych zdarzeń identyfikator generujesz raz na stronie i przekazujesz do obu tagów. Te same metody generowania identyfikatorów, wraz z gotową zmienną GTM, opisujemy w artykule o deduplikacji piksela i Conversions API w Meta. Mechanizm jest bardzo podobny w OpenAI Pixel i Conversions API, choć pola nazywają się tam inaczej.

ttclid, _ttp i dane klienta: jak poprawić dopasowanie

TikTok dopasowuje zdarzenie do użytkownika na podstawie identyfikatorów, które mu przekażesz. Im więcej poprawnych identyfikatorów w zdarzeniu, tym więcej konwersji trafi do raportów i do optymalizacji.

Parametr ttclid TikTok dokleja do adresu strony docelowej po kliknięciu reklamy. Piksel zapisuje go sam, ale dla zdarzeń serwerowych musisz go zachować – np. w pliku cookie lub w danych zamówienia – i dołączyć do zdarzenia. Plik _ttp zapisuje piksel jako identyfikator przeglądarki; jego wartość odczytasz w kontenerze serwerowym, jeśli działa na subdomenie sklepu. Przekierowania gubiące parametry adresu usuwają ttclid, więc przetestuj każdy link docelowy.

Dane kontaktowe – e-mail, telefon, external_id – wysyłasz zahaszowane SHA-256 po normalizacji: e-mail małymi literami i bez spacji, identyfikator klienta jako stała wartość z Twojego systemu. Format telefonu przed haszowaniem sprawdź w dokumentacji TikToka, bo platformy różnią się w tej kwestii; przykładowo Meta oczekuje samych cyfr z kodem kraju, bez znaku plus. Ogólne zasady normalizacji i najczęstsze błędy, takie jak podwójne haszowanie, opisujemy w poradniku o Event Match Quality w Meta – większość z nich dotyczy też TikToka. Diagnostykę jakości zdarzeń znajdziesz w Events Managerze, przy szczegółach piksela.

Zgody i server-side: jak nie obejść decyzji użytkownika

TikTok Pixel zapisuje pliki cookie i przesyła dane do celów reklamowych, więc wymaga zgody marketingowej. W GTM ustaw mu wymóg dodatkowej zgody na ad_storage i uruchamiaj go także na zdarzeniu, które CMP wysyła po akceptacji. Piksel udostępnia też metody wstrzymania i udzielenia zgody w kodzie (ttq.holdConsent(), ttq.grantConsent(), ttq.revokeConsent()); sprawdź w dokumentacji, czy obsługuje je Twoja wersja kodu bazowego. Całą konfigurację zgód opisuje checklista Consent Mode v2.

W kontenerze serwerowym tag TikToka nie zna decyzji z banera. Dodaj w regule warunek oparty na parametrze gcs przychodzącego żądania GA4 – wartość zaczynająca się od G11 oznacza zgodę na ad_storage. Jak sprawdzić, że parametr dociera poprawnie, pokazujemy w poradniku jak sprawdzić, czy Consent Mode działa. Events API nie służy do omijania odmowy, a przekazywanie danych klientów do TikToka opisz w polityce prywatności i skonsultuj z prawnikiem.

Najczęstsze błędy w TikTok Pixel i Events API

Poniższe błędy odpowiadają za większość problemów z liczbą konwersji w TikTok Ads Manager. Wiele z nich wykryjesz, porównując liczbę zakupów w TikToku z panelem sklepu.

Po usunięciu błędów liczby w TikToku i w GA4 nadal nie będą identyczne, bo platformy stosują inne modele atrybucji. Skąd biorą się różnice i jak je interpretować, wyjaśniamy w artykule o rozbieżnościach konwersji między GA4, Google Ads i Meta. Do oceny opłacalności kampanii przyda się z kolei porównanie wskaźników w tekście o ROAS, POAS i MER. Pozostałe poradniki o pikselach i API konwersji znajdziesz w podtemacie Meta Pixel i Conversions API.