Zasada działania Tik Tok Events API jest dokładnie taka sama jak zasada działania Meta Conversion API. Po więcej info na ten temat zapraszam do innych naszych artykułów:
Adam Brzostek
01.04.2026Czas czytania: 15:00
Tik Tok Events API - kompletny przewodnik jak wdrożyć je samodzielnie 2026
Po raz kolejny wykorzystujemy technologie server-side i znowu dane będziemy wysyłać dwutorowo:
- za pomocą pixela, czyli bezpośrednio ze strony do systemu reklamowego Tik Tok
- za pomocą API, czyli z wykorzystaniem serwera, do którego również musimy przesłać dane ze strony klienta a dopiero w następnej kolejności wysłać je do systemu reklamowego Tik Tok
Tak samo jak w przypadku CAPI, przesłane dane powinny się zdeduplikować.
Korzyści również się nie różnią:
- Trwalsze ciasteczka bez skróconego okresu przydatności
- Omijanie adblocków i innych ograniczeń śledzenia = więcej danych
- Bezpieczniejszy sposób przesyłania danych
Mimo że Tik Tok oferuje autmatyczną integracje Events API to w mojej ocenie nie działa ona najlepiej, a sama dokumentacja jest bardzo uboga, dlatego przygotowałem ten poradnik.
Ten artykuł przeczytasz tylko po zapisaniu się do newslettera
Dołącz do newslettera Bettersteps żeby zobaczyć pełną treść artykułu kompletnie za darmo
Zapisując się z tego formularza otrzymasz dostęp do całego materiału oraz na maila link do pobrania gotowych plików jSON dla GTM WEB oraz GTM SERVER
Wymagania wstępne
- Dostęp na poziomie publikacji do kontenera GTM po stronie klienta
- Dostęp na poziomie publikacji do kontenera GTM po stronie serwera
- Jeżeli nie mamy skonfigurowanego serwera tagowania zapraszam do zapoznania się najpierw z tym tym artykułem: https://bettersteps.pl/blog/praktyczny-poradnik-gtm-server-side-tagging-google-analytics-4 natomiast w przeciwieństwie do tego co opisywałem wcześniej w artykule, na podstawie zebranego doświadczenia rekomenduje skorzystanie z ręcznej konfiguracji, dla której Google dostarczył bardzo dobrą instrukcję: https://developers.google.com/tag-platform/tag-manager/server-side/cloud-run-setup-guide?provisioning=manual&hl=pl
- Przed konfiguracją koniecznie zapoznaj się z pułapkami jakie mogą na Ciebie czychać: https://bettersteps.pl/blog/pulapki-konfiguracji-gtm-server-side-w-technologii-google-cloud-run
- Idealnie jeżeli nasz serwer tagowania będzie miał zintegrowaną własną subdomenę, poradnik jak to zrobić dostępny jest tutaj: https://bettersteps.pl/blog/integracja-wlasnej-subdomeny-do-serwera-tagowania-w-google-cloud-platform-cloud-run
- Pełny dostęp do Tik Tok Business Center
- Jeżeli jest to możliwe przyda nam się dostęp administracyjny do całego konta, bo wtedy będziemy wtedy w pełni niezależni, natomiast jeżeli nie jest to możliwe to potrzebny będzie nam dostęp do Ads Managera z funkcją obsługi zdarzeń.
- Dostęp do Google Analytics (administracyjny na zakresie konta lub do edycji na zakresie nowej dedykowanej usługi)
- Dane do serwera tagowania będziemy wysyłać za pomocą tagów GA4, dlatego warto utworzyć dedykowaną usługę, gdyż dzięki temu za jednym zamachem wdrożymy CAPI oraz śledzenie server-side GA4
Konfiguracja po stronie klienta
Jak już wiem wdrażając Tik Tok Events API musimy w pierwszej kolejności przesłać dane ze strony klienta.
Jest to najbardziej skomplikowana część całego wdrożenia, natomiast jeżeli to skonfigurujemy prawidłowo to konfiguracja po stronie serwera pójdzie nam bardzo gładko.
Do wysyłania danych za pomocą pixela użyjemy autoryzowanego szablonu od Tik Tok’a.
Natomiast do wysłania danych do serwera tagowania wykorzystamy tagi Google Analytics 4.
Zmienne
Zacznijmy od konfiguracji zmiennych, które będą nam potrzebne. Wszystkie znajdują się w jSONie udostępnionym tutaj:
Oprócz standardowych parametrów opisujących zdarzenia potrzebne nam będą:
cookie - Tik Tok ID - czyli ciasteczko 1st party tworzone przez kod pixela facebooka identyfikujące konkretnego użytkownika - przesłanie tej informacji jest konieczne do deduplikacji i dopasowania danych w systemie Meta.
cjs - Tik Tok unique event ID - unikalny identyfikator zdarzenia, który wykorzystamy do deduplikacji zdarzeń.
Zmienna ta to moja autorska twórczość. Składa się ona z połączenia nazwy eventu, identyfikatora ciasteczka Tik Tok’a oraz timestamp’u zdarzenia pomniejszonego o ostatnie cztery cyfry - jest to bardzo kluczowy zabieg, gdyż aby deduplikacja działała prawidłowo wartość tej zmiennej musi być identyczna gdy jest przekazywana pixelem oraz tagiem GA4. Mimo, że teoretycznie obydwa tagi uruchamiają się w tym samym momencie to w rzeczywistości działają asynchronicznie i czas uruchomienia różni się o ułamki sekund stąd takie działanie. Kod do skopiowania dostępny jest tutaj:
function() {
var event_timestamp = Date.now();
var event_id = {{Event}} + '_' + {{cookie - Tik Tok ID}} + '_' + event_timestamp;
var len = event_id.length;
return event_id.substring(0,len - 4);
}const - Tik Tok Pixel ID - stała przechowująca id naszego pixela.
const - server container url - stała przechowująca adres naszego serwera tagowania.
const - server GA4 id - id pomiaru usługi GA4 dla danych przesyłanych przez serwer.
Zmienne konfiguracji
Oprócz tego dla ułatwienia będziemy korzystać ze zmiennych konfiguracji. Pomogą nam one w przyszłości zarządzać zmianami, ale ułatwią nam również sam proces tagowania.
Konfiguracja GA4 server - zmienna konfiguracji GA4 dla łatwego zarządzania zmianami tagowania w przyszłości.
Konfiguracja zdarzeń GA4 server - zmienna konfiguracji zdarzeń GA4 dla łatwego zarządzania zmianami tagowania w przyszłości.
W obydwu zmiennych deklarujemy parametry wspólne dla wszystkich zdarzeń wysyłanych do Mety przez serwer za pomocą CAPI:
- server_container_url - url naszego serwera tagowania
- t_event_id - identyfikator zdarzenia do deduplikacji (oznaczam go przedrostkiem t_ aby wyróżnić go od identyfikatora zdarzenia mety, który już możemy mieć w naszej zmiennej). Możemy użyć innej nazwy gdyż i tak wartość tą będziemy deklarować w tagach API
W moim pliku jSON wszystkie powyższe zmienne są już skonfigurowane, ale należy pamiętać o zmianie wartości parametrów konfiguracyjnych:
- const - Tik Tok Pixel ID
- const - server container url
- const - server GA4 id
Oprócz tego w pliku znajdują się też standardowe zmienne ecommerce oraz zmienne javascript w formacie wymaganym przez Tik Tok’a do obsługi zdarzeń.
Implementacja pixela Tik Tok’a
W tym przewodniku posłużymy się przykładem zdarzenia add_to_cart, ale w analogiczny sposób możemy otagować każde zdarzenie.
Podstawowy tag Tik Tok
Zaczynamy od wdrożenia podstawowego tagu odsłony.
Niestety w dokumentacji nie ma powiedziane jak prawidłowo skonfigurować go z wykorzystaniem szablonu, dlatego używam tutaj tagu niestandardowego kodu HTML.
Id naszego pixela przechowywane jest we wcześniej utworzonej zmiennej.
Kod ten jest standardowy i znajduje się w udostępnionym przeze mnie pliku jSON.
Możemy też pobrać go bezpośrednio z Tik Tok’a przechodząc z Ad Managera do Events Managera (Tools → Events → Data Sources), a następnie wybierając interesujący nas pixel.
W panelu pixela otwieramy zakładkę Settings i odnajdujemy tą sekcję:
Po kliknięciu View base code będziemy mogli skopiować nasz kod pixela
Musimy pamiętać o ustawieniu uruchamiania tagu raz na stronę oraz o ustawieniu wymaganych zgód, ale o tą kwestię rozwiniemy w dedykowanej sekcji.
Kod ten odpowiada za zdarzenie page view i będzie to jedyne zdarzenie, które będziemy obsługiwać tylko client side, ponieważ nie dokopałem się do dokumentacji jak w przypadku kofu HTML zadeklarować event_id
Wysłanie zdarzenia
Do wysłania zdarzenia możemy skorzystać już z szablonu tagu. Rekomenduje się korzystanie ze standardowych zdarzeń, ponieważ tylko pod takie można optymalizować kampanie na Tik Toku. Listę wspieranych zdarzeń znajdziemy tutaj: https://ads.tiktok.com/help/article/supported-standard-events?aadvid=7353949490531041296
Ale oczywiście szablon daje nam możliwość wysłania również zdarzenia niestandardowego.
W naszym przypadku będzie to jednak zdarzenie standardowe o nazwie AddToCart.
Musimy dodać wymagane parametry w sekcji Object Properties oraz dodanie zabezpieczenia, które uruchomi tag podstawowy przed tagiem zdarzenia, gdyby tamten nie wczytał się wcześniej. Ponieważ ustawiliśmy jego uruchamianie raz na stronę nie ma ryzyka, że dojdzie do zduplikowanego uruchomienia i zliczenia odsłony.
Konfigurując Object properties możemy wybrać wykorzystanie warstwy danych, jeżeli odpowiada ona w 100% strukturze enhanced ecommerce.
Jeżeli nie mamy takiej warstwy to musimy skonfigurować te parametry ręcznie.
W zależności od zdarzenia wybieramy
- Single Content (add to cart, view item), gdy mamy do czynienia ze zdarzeniem na pojedynczym produkcie
- Multiple Contents (view_cart, purchase, etc), gdy mamy do czynienia ze zdarzeniem na grupie produktów.
W sekcji deduplikacji musimy jeszcze zadeklarować identyfikator zdarzenia w postaci stworzonej przez nas wcześniej zmiennej.
W analogiczny sposób możemy wdrożyć śledzenie każdego zdarzenia, a przykłady dla kluczowych zdarzeń znajdują się w udostępnionym pliku.
Przy zdarzeniu purchase jak event id najlepiej będzie wykorzystać identyfikator transakcji
Wysłanie danych do serwera tagowania
Skoro nasz pixel Meta odbiera już prawidłowo dane ze strony ze wszystkimi parametrami potrzebnymi do deduplikacji danych odebranych przez CAPI możemy przystąpić do właściwej części konfiguracji.
Do naszego serwera tagowania za pomocą tagów GA4 musimy wysłać wszystkie zdarzenia z wymaganymi parametrami, które wcześniej wdrożyliśmy za pomocą pixela.
Podstawowy Tag Google
Zaczniemy od wdrożenie podstawowego tagu Google, który obsłuży zdarzenie odsłony.
Konfiguracja jest bardzo prosta.
Jako identyfikator pomiaru deklarujemy wcześniej utworzoną zmienną.
W sekcji Zmienna ustawień konfiguracji wybieramy skonfigurowaną przez nas zmienną.
W Opcjach uruchamiania tagu wybieramy Raz na stronę.
Wysłanie zdarzenia
Do wysłania zdarzenia do serwera korzystamy z tagu zdarzenia Google Analytics 4.
Konfiguracja również jest bardzo prosta.
Ponownie jako identyfikator pomiaru deklarujemy wcześniej utworzoną zmienną.
W sekcji Zmienna ustawień zdarzeń wybieramy skonfigurowaną przez nas zmienną.
W parametrach zdarzenia oprócz standardowych parametrów ecommerce przekazujemy zmienne, analogiczne do tych przekazanych w tagu pixela.
W przypadku zdarzeń wywoływanych jednocześnie z odsłoną warto dodatkowo zabezpieczyć się poprzez uruchomienie tagu konfiguracji GA4 przed tagiem zdarzenia - dzięki temu że, był on ustawiony aby uruchamiać się raz na stronę nie grozi nam sytuacja, że uruchomi się zbyt wiele razy.
W analogiczny sposób wdrażamy każde zdarzenie.
W przypadku zdarzenia purchase powinniśmy nadpisać parametr t_event_id ze zmiennej konfiguracji zdarzeń dodają ten parametr w konfiguracji tagu z wartością identyfikatora zamówienia.
Przesłanie danych z serwera do Tik Tok’a
Aby wysłać odebrane przez serwer tagowania dane do naszego konta reklamowego w Tik Toku skorzystamy z szablonu tagu Tik Tok Events API (Official) od tik toka
Zmienne
Potrzebujemy utworzyć dwie stałe:
const - Tik Tok Pixel ID - stała przechowująca id naszego pixela - identycznie jak w kontenerze po stronie klienta.
const - Tik Tok Access Token - stała przechowująca id Tokena dostępu do API.
lTable - Tik Tok events map - tabela przeglądowa mapująca zdarzenia GA4 na nazwy zdarzeń wymagane przez Tik Tok’a - niestety nie ma potwierdzenia, żeby Tik Tok sam zmapował zdarzenia
event_date - t_event_id - zmienna przechwytująca z danych zdarzenia jego identyfikator dla Tik Tok’a
Jak wygenerować token dostępu Tik Tok Events API
Token generuje się z poziomu menadżera zdarzeń Tik Tok.
Musimy skorzystać z analogicznej ścieżki jak przy pobieraniu kodu pixela, czyli przejść z Ad Managera do Events Managera (Tools → Events → Data Sources), a następnie wybierając interesujący nas pixel.
Należy wejść w źródła danych - > odpowiedni pixel - > ustawienia, a nastepnie odszukać sekcję Events API i kliknąć przycisk Wygeneruj token dostępu.
Konfiguracja Tagu
Przy poprawnej konfiguracji po stronie klienta w większości przypadków nie musimy za wiele zmieniać w konfiguracji.
Debugowanie
Aby przetestować poprawność działania Events API do naszego tagu musimy dodać kod testowy zdarzenia.
Po raz kolejny jest tu analogia do tego jak działa CAPI.
Kod testowy znajdziemy w źródła danych - > odpowiedni pixel - > testowanie zdarzeń.
Kopiujemy go i wklejamy w odpowiednie miejsce.
Pamiętajmy, że przed publikacją obszaru roboczego musimy usunąć ten parametr.
W tym momencie możemy włączyć tryb podglądu zarówno w kontenerze po stronie klienta jak i w kontenerze po stronie serwera.
Oczekujemy, że w tym samym momencie uruchomi się zarówno tag pixela jak i tag zdarzenia GA4, który wysyła dane do serwera.
W podglądzie kontenera po stronie serwera w zakładce Tags powinniśmy zobaczyć uruchomiony tag Events API.
Natomiast ważniejsza jest zakładka Requests. Oczekujemy tam wychodzącego żądania do Tik Tok’a z kodem 200 - wtedy oznacza to, że żądanie wysłało się prawidłowo.
Na sam koniec powinnismy sprawdzić zdarzenie w menadżerze zdarzeń Tik Tok’a. Dzięki temu możemy potwierdzić, czy odbieranie działa prawidłowo.
Niestety panel Tik Tok nie daje nam możliwości w podglądzie live sprawdzenia czy działa deduplikacja.
Jeżeli dane odbierają się prawidłowo to w tym momencie powinnismy opublikować nasze obszary robocze zarówno w GTM client side jak i GTM serwer side,
Po kilku dniach od publikacji implementacji, w menadżerze zdarzeń będziemy mogli sprawdzić jakość naszej deduplikacji. Żeby to zrobić należy ponownie wejść do panelu konkretnego pixela, a tam w zakładce overview wybrać interesujące nas zdarzenie i sprawdzić jego deduplikację.
System powinien wykryć i wskazać nam czy potrzebna jest poprawka.
Zarządzanie zgodami consent mode
Ostatnią kwestią do omówienia jest zarządzanie zgodami uruchamiania tagów.
Tagi Tik Tok’a niezależnie czy są to tagi pixela czy Events API wymagają zgody ad_storage.
W przypadku pixela jest to naturalnie proste do ustawienia.
W przypadku tagów Events API nie jest to tak oczywiste.
Najprościej jest ustawić wymóg zgody do tagów GA4 po stronie klienta.
Natomiast rozwiązanie to nie sprawdzi się, gdy tych samych tagów używamy do śledzenia GA4 serwer-side i to w trybie advanced consent mode.
W takiej sytuacji tworzę zmienną w GTM client side przechwytującą status zgody ad_storage i dodaje dodatkowy parametr do obydwu zmiennych konfiguracji.
W GTM serwer side tworzę zmienną odczytującą tą wartość.
I używam jej, żeby uwarunkować uruchamianie tagów API.
Jak korzystać z plików jSON
Pliki zostały stworzone dla następujących zdarzeń:
- page_view
- view_item
- add_to_cart
- begin_checkout
- purchase
Oprócz tego dla śledzenia GA4 znajdują się tam tagi dla:
- view_cart
- add_payment_info
- add_shipping info
Pliki są stworzone dla standardowej struktury Data Layer enhanced ecommerce
GTM client side
- Zaimportuj kontener
- Zaktualizuj zmienne
- const - GA4 id - server
- const - server-side url
- const - Tik Tok Pixel ID
- Zaktualizuj zmienną cjs - localStorage.ad_storage tak aby przechwytywała wartość zgody ad_storage dla CMP, którego używasz - może być konieczne stworzenie kodu, który pobiera tą zmienną
GTM server side
- Zaimportuj kontener
- Zaktualizuj zmienne
- const - Tik Tok access token
- const - Tik Tok Pixel ID
Po pozytywnem debugu opublikuj obydwa kontenery
Wdrożenie Events API nie jest dobrze udokumentowane i mimo kilka wdrożeń za sobą nadal istnieje tu dla mnie mnóstwo niejasności. Na pewno będę na bieżąco aktualizował ten przewodnik.
Nie dostałeś plików jSON? Spróbuj jeszcze raz tutaj: https://bettersteps.pl/twoj-przewodnik-tik-tok-events-api
Zaobserwuj nasze profile, żeby nie przegapić innych ciekawych materiałów:
