{"id":10130,"date":"2026-09-20T19:03:00","date_gmt":"2026-09-20T17:03:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=10130"},"modified":"2026-09-09T13:23:11","modified_gmt":"2026-09-09T11:23:11","slug":"tutorial-wdrozenie-tiktok-events-api-w-sklepach-internetowych","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/pl\/digital-marketing-pl\/tutorials-pl-digital-marketing-pl\/tutorial-wdrozenie-tiktok-events-api-w-sklepach-internetowych\/","title":{"rendered":"Tutorial: Wdro\u017cenie TikTok Events API w sklepach internetowych"},"content":{"rendered":"
Sam piksel TikTok raportuje mniej zakup\u00f3w, ni\u017c sklep faktycznie realizuje. Blokery, ochrona przed \u015bledzeniem w przegl\u0105darce oraz osoby zamykaj\u0105ce kart\u0119, zanim strona potwierdzenia sko\u0144czy si\u0119 renderowa\u0107, usuwaj\u0105 zdarzenia, kt\u00f3re naprawd\u0119 wyst\u0105pi\u0142y. Wys\u0142anie tych samych zakup\u00f3w po raz drugi z serwera zamyka t\u0119 luk\u0119 \u2014 i tworzy nowy problem, poniewa\u017c TikTok otrzymuje teraz dwa zg\u0142oszenia jednego zakupu.<\/p>\n
Rozwi\u0105zuje to wsp\u00f3lne event_id<\/code>: jedna warto\u015b\u0107 generowana na zakup i wysy\u0142ana bez zmian obiema drogami. Poni\u017cszy przewodnik buduje t\u0119 architektur\u0119 od pocz\u0105tku do ko\u0144ca dla sklepu \u2014 zdarzenie w przegl\u0105darce, identyfikatory, kt\u00f3rych serwer sam z siebie nie widzi, \u017c\u0105danie serwerowe oraz weryfikacj\u0119, czy deduplikacja faktycznie dzia\u0142a.<\/p>\n\nPiksel dostarcza kontekst przeglądarki, serwer niezawodność – wspólne event_id utrzymuje je jako jedną konwersję.<\/figcaption><\/figure>\n
Krok 1: Wygenerowanie event_id jeden raz<\/h2>\n
event_id<\/code> musi powsta\u0107 w jednym miejscu i zosta\u0107 u\u017cyte ponownie, co wyklucza generowanie go niezale\u017cnie po obu stronach \u2014 dwie losowe warto\u015bci opisuj\u0105 z punktu widzenia TikToka dwie odr\u0119bne konwersje. Dla sklepu naturalnym \u017ar\u00f3d\u0142em jest numer zam\u00f3wienia: istnieje ju\u017c w momencie zakupu, jest stabilny i dost\u0119pny zar\u00f3wno dla strony potwierdzenia, jak i dla backendu.<\/p>\n
Prefiks rozdziela typy zdarze\u0144, bo jedno zam\u00f3wienie potrafi wygenerowa\u0107 wi\u0119cej ni\u017c jedno \u015bledzone zdarzenie. event_id<\/code> w postaci purchase-10432<\/code> dla zakupu i checkout-10432<\/code> dla rozpocz\u0119cia checkoutu utrzymuje ka\u017cd\u0105 par\u0119 przy w\u0142asnym odpowiedniku. Skutkiem ubocznym jest to, \u017ce od\u015bwie\u017cenie strony potwierdzenia generuje to samo event_id<\/code> ponownie i zostaje zdeduplikowane zamiast policzone dwa razy.<\/p>\n
Krok 2: Zdarzenie w przegl\u0105darce<\/h2>\n
W pikselu TikTok identyfikator podr\u00f3\u017cuje w trzecim argumencie ttq.track<\/code>, oddzielnie od w\u0142a\u015bciwo\u015bci zdarzenia:<\/p>\n
Nazwa zdarzenia r\u00f3wnie\u017c musi by\u0107 zgodna po obu stronach. TikTok paruje oba zg\u0142oszenia po kombinacji nazwy zdarzenia i event_id<\/code>, wi\u0119c CompletePayment<\/code> w przegl\u0105darce i Purchase<\/code> na serwerze to dwa r\u00f3\u017cne zdarzenia, kt\u00f3re nigdy si\u0119 wzajemnie nie zdeduplikuj\u0105 \u2014 niezale\u017cnie od tego, jak starannie dopasowano identyfikator.<\/p>\n
Krok 3: Przechwycenie identyfikator\u00f3w, kt\u00f3rych serwer nie widzi<\/h2>\n
Dwie warto\u015bci istniej\u0105 wy\u0142\u0105cznie w przegl\u0105darce. ttclid<\/code> pojawia si\u0119 jako parametr URL, gdy odwiedzaj\u0105cy trafia z reklamy TikTok, a _ttp<\/code> to plik cookie pierwszej strony ustawiany przez piksel. Obie poprawiaj\u0105 dopasowanie \u017c\u0105dania serwerowego i obie trzeba utrwali\u0107 ju\u017c przy wej\u015bciu \u2014 strona potwierdzenia znajduje si\u0119 zwykle kilka przej\u015b\u0107 dalej, a parametru URL dawno tam nie ma:<\/p>\n
\/\/ Przy wejsciu: utrwalenie click id na reszt\u0119 wizyty\nconst ttclid = new URLSearchParams(window.location.search).get('ttclid');\nif (ttclid) {\n document.cookie = 'shop_ttclid=' + encodeURIComponent(ttclid) +\n ';max-age=2592000;path=\/;secure;samesite=Lax';\n}<\/code><\/pre>\n
W checkoucie obie warto\u015bci s\u0105 odczytywane z plik\u00f3w cookie i zapisywane przy rekordzie zam\u00f3wienia, \u017ceby backend mia\u0142 je pod r\u0119k\u0105 przy budowaniu zdarzenia serwerowego. Adres IP i user agent odwiedzaj\u0105cego pochodz\u0105 z pierwotnego \u017c\u0105dania HTTP i nale\u017c\u0105 do tego samego rekordu \u2014 \u017c\u0105danie wys\u0142ane p\u00f3\u017aniej z serwera nie ma ani jednego, ani drugiego z w\u0142asnych \u017ar\u00f3de\u0142.<\/p>\n
Krok 4: \u017b\u0105danie serwerowe<\/h2>\n
Events API przyjmuje POST na endpoint event\/track\/<\/code> w TikTok Business API, uwierzytelniony tokenem dost\u0119pu z TikTok Events Managera i zaadresowany do piksela przez event_source_id<\/code>. Pola identyfikuj\u0105ce s\u0105 normalizowane, a nast\u0119pnie haszowane SHA-256; nic identyfikuj\u0105cego nie opuszcza serwera jawnie:<\/p>\n
Normalizacja przed haszowaniem rozstrzyga, czy identyfikatory w og\u00f3le co\u015b trafi\u0105: e-mail przyci\u0119ty i zamieniony na ma\u0142e litery, numer telefonu sprowadzony do cyfr w mi\u0119dzynarodowym formacie E.164. Ta sama warto\u015b\u0107 zahaszowana raz z Anna@Example.com <\/code>, a raz z anna@example.com<\/code> daje dwa niepowi\u0105zane skr\u00f3ty, z kt\u00f3rych tylko jeden mo\u017ce pasowa\u0107. event_time<\/code> to znacznik czasu uniksowego w sekundach, a \u017c\u0105danie nale\u017cy tu\u017c za potwierdzeniem zam\u00f3wienia, a nie do nocnej paczki. TikTok odrzuca zdarzenia docieraj\u0105ce zbyt p\u00f3\u017ano, a zadanie wsadowe dowiaduje si\u0119 o tym dopiero, gdy okno ju\u017c si\u0119 zamkn\u0119\u0142o.<\/p>\n
Krok 5: Weryfikacja, czy deduplikacja dzia\u0142a<\/h2>\n
Pole test_event_code<\/code>, pobrane z zak\u0142adki zdarze\u0144 testowych w Events Managerze, kieruje \u017c\u0105danie do widoku testowego bez naruszania raportowania \u2014 tyle wystarczy, by potwierdzi\u0107, \u017ce \u0142adunek jest przyjmowany, a pola zahaszowane rozpoznawane.<\/p>\n
Sama deduplikacja ujawnia si\u0119 dopiero na danych produkcyjnych. W Events Managerze zdarzenie zasilane z obu kana\u0142\u00f3w wykazuje liczby przegl\u0105darkowe i serwerowe osobno, a r\u00f3\u017cnica mi\u0119dzy ich sum\u0105 a zdeduplikowan\u0105 warto\u015bci\u0105 ca\u0142kowit\u0105 jest dowodem, \u017ce parowanie dzia\u0142a. Warto\u015b\u0107 ca\u0142kowita r\u00f3wna dok\u0142adnie sumie obu kana\u0142\u00f3w oznacza, \u017ce nic nie jest \u0142\u0105czone \u2014 zwykle wskutek rozbie\u017cnej nazwy zdarzenia albo event_id<\/code> generowanego osobno po ka\u017cdej ze stron. Zestawienie zdeduplikowanej liczby z faktycznymi zam\u00f3wieniami w backendzie sklepu to sprawdzenie, kt\u00f3re ma znaczenie; w\u0142asne liczby TikToka nie poka\u017c\u0105 zakupu, kt\u00f3rego nie zg\u0142osi\u0142 \u017caden kana\u0142.<\/p>\n
Pozostaj\u0105c w granicach<\/h2>\n
Oba kana\u0142y nale\u017c\u0105 za ten sam sygna\u0142 zgody reklamowej. \u017b\u0105danie serwerowe nie jest zwolnione ze zgody dlatego, \u017ce pochodzi z backendu: niesie te same dane klienta, a podstaw\u0105 jego wys\u0142ania jest zgoda zebrana w przegl\u0105darce \u2014 stan zgody trzeba wi\u0119c zapisa\u0107 przy zam\u00f3wieniu i sprawdzi\u0107 przed zbudowaniem \u017c\u0105dania. Surowe adresy e-mail i numery telefon\u00f3w istniej\u0105 tylko do momentu normalizacji i zahaszowania, a token dost\u0119pu nale\u017cy do magazynu sekret\u00f3w, a nie do kodu aplikacji, poniewa\u017c uprawnia do zapisywania konwersji na koncie reklamowym.<\/p>\n
![\"Dwutorowy](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/tiktok-events-api-pl.png\")