Tutorial: Wdrożenie TikTok Events API w sklepach internetowych

Piksel przeglądarkowy może pominąć zakup, na przykład po zablokowaniu skryptu lub przedwczesnym zamknięciu strony potwierdzenia. TikTok Events API dodaje drogę raportowania z backendu sklepu. Taka architektura może poprawić kompletność danych, ale nie gwarantuje zebrania wszystkich zdarzeń ani przypisania każdego zakupu do reklamy.

Piksel to kod pomiarowy działający w przeglądarce. Backend oznacza oprogramowanie sklepu na serwerze. API jest interfejsem wymiany danych między programami, a token dostępu to poświadczenie pozwalające na tę wymianę. Deduplikacja rozpoznaje powtórne zgłoszenia tego samego zdarzenia. Atrybucja przypisuje zakup do reklamy według określonych zasad.

Poniższa instrukcja łączy oba kanały wspólnym identyfikatorem zdarzenia. Wymagane są piksel TikTok, token dostępu przechowywany wyłącznie na serwerze, zintegrowany system zgód oraz wiarygodne potwierdzenie zakupu w backendzie. Przykłady obejmują przygotowanie danych; połączenie ze sklepem, kolejka wysyłki i obsługa błędów wymagają osobnej implementacji.

Krok 1: Stały identyfikator potwierdzonego zakupu

Backend tworzy event_id tylko raz. Zgłoszenia przeglądarkowe, serwerowe i ponowienia zachowują tę samą wartość. Przykładowo purchase-10432 oznacza jeden potwierdzony zakup. Identyfikator oparty na zamówieniu musi być unikalny w źródle danych i nie może zawierać danych osobowych. Płatności cykliczne wymagają oddzielnego identyfikatora każdej płatności.

TikTok deduplikuje zdarzenia według kodu piksela, nazwy zdarzenia i event_id w oknie 48 godzin. Odświeżenie strony potwierdzenia po zakończeniu tego okna nie jest chronione bezterminowo. Sklep musi również ograniczać ponowne raportowanie zakupów, na przykład przez status wysyłki każdego zdarzenia. Ponowienia zachowują także pierwotny czas zakupu.

Krok 2: Ten sam obiekt zakupu dla piksela

Backend przekazuje stronie potwierdzenia pola zakupu przekształcone do formatu, który można bezpiecznie umieścić na stronie: event_id, contents, value i currency. Ceny i koszyk pochodzą z potwierdzonego zamówienia, a nie z dowolnie modyfikowanych parametrów URL. Poniższa funkcja wymaga zainicjalizowanego piksela sterowanego systemem zgód:

function sendTikTokPurchase(purchase, advertisingConsent) {
  if (advertisingConsent !== true) return false;
  if (!purchase.event_id || !window.ttq) return false;
  window.ttq.track('Purchase', {
    content_type: 'product',
    contents: purchase.contents,
    value: purchase.value,
    currency: purchase.currency
  }, { event_id: purchase.event_id });
  return true;
}

Wywołanie następuje dopiero po potwierdzeniu zakupu i przy aktualnej zgodzie reklamowej. Wynik true oznacza wywołanie ttq.track, bez potwierdzenia dostarczenia. Inicjalizacja piksela i zdarzenia automatyczne również wymagają kontroli zgody.

Nowe implementacje używają Purchase w obu kanałach. Od maja 2025 r. TikTok automatycznie mapuje wcześniejszą nazwę CompletePayment na Purchase; starsza nazwa nadal jest obsługiwana. Inne rozbieżności bez udokumentowanego mapowania pozostają możliwym źródłem błędów.

Krok 3: Dostępne identyfikatory i kontekst po uzyskaniu zgody

ttclid może występować w adresie strony docelowej reklamy. _ttp jest ciasteczkiem piksela. Wartości nie istnieją wyłącznie w przeglądarce: serwer sklepu może odczytać otrzymane parametry URL i ciasteczka. Podczas pierwszego żądania ciasteczko może jednak jeszcze nie istnieć. Brakujące identyfikatory pozostają pominięte; sztuczne wartości zastępcze pogarszają jakość danych.

Prosta funkcja po stronie przeglądarki zapisuje dostępny identyfikator kliknięcia dopiero po zgodzie. System zgód wywołuje funkcję po pierwszej decyzji oraz po kolejnych zmianach:

function updateTikTokClickCookie(advertisingConsent) {
  const attributes = ';path=/;Secure;SameSite=Lax';
  if (advertisingConsent !== true) {
    document.cookie = 'shop_ttclid=;max-age=0' + attributes;
    return;
  }
  const clickId = new URLSearchParams(location.search).get('ttclid');
  // Local size limit, not a TikTok identifier-format specification.
  if (!clickId || clickId.length > 1024) return;
  document.cookie = 'shop_ttclid=' + encodeURIComponent(clickId) +
    ';max-age=2592000' + attributes;
}

Okres 30 dni jest przykładową decyzją o retencji, a nie wymaganiem TikToka ani gwarancją trwałości ciasteczka. Późniejsze wejście bez ttclid nie przedłuża ważności. Odmowa lub wycofanie zgody usuwa ciasteczko utworzone w tym przykładzie. Identyfikatory zapisane na serwerze i oczekujące zdarzenia wymagają odpowiedniej obsługi wycofania zgody. Usunięcie nie obejmuje ciasteczek o innych ścieżkach lub domenach.

Podczas finalizacji zamówienia dostępne identyfikatory można powiązać z zakupem. Pole ttp otrzymuje wartość _ttp. Adres IP i user agent (opis oprogramowania przekazywany przez przeglądarkę) muszą pochodzić z pierwotnej wizyty, a nie z późniejszego klienta API. Serwer proxy przekazuje żądania między systemami. Sklep może ufać adresom IP w przekazanych nagłówkach tylko wtedy, gdy przyjmuje je od prawidłowo skonfigurowanych, zaufanych serwerów pośrednich.

Krok 4: Budowa danych dla serwera

Adres docelowy to POST https://business-api.tiktok.com/open_api/v1.3/event/track/, z nagłówkami Access-Token i Content-Type: application/json. Pole event_source_id zawiera ten sam kod piksela co integracja przeglądarkowa. Poniższa funkcja w Pythonie przygotowuje dane bez wykonywania żądania sieciowego:

import hashlib
import re

def sha256(value):
    return hashlib.sha256(value.encode('utf-8')).hexdigest()

def build_payload(pixel_code, order, advertising_consent,
                  email, phone_e164=None):
    if advertising_consent is not True:
        return None
    email = email.strip().lower()
    if not email:
        raise ValueError('Missing email for this example')
    user = {'email': sha256(email)}
    if phone_e164 is not None:
        # Input already parsed and validated for its country.
        if not re.fullmatch(r'\+[1-9][0-9]{1,14}', phone_e164):
            raise ValueError('Expected international phone number with +')
        user['phone'] = sha256(phone_e164)
    return {
        'event_source': 'web',
        'event_source_id': pixel_code,
        'data': [{
            'event': 'Purchase',
            'event_time': order['confirmed_at_unix'],
            'event_id': order['event_id'],
            'user': user,
            'properties': {
                'content_type': 'product',
                'contents': order['contents'],
                'currency': order['currency'],
                'value': order['value']
            },
            'page': {'url': order['confirmation_url']}
        }]
    }

order oznacza już zweryfikowany rekord backendu: potwierdzony zakup, zapisany stały identyfikator, czas zakupu w całych sekundach od 1 stycznia 1970 UTC (czas uniksowy), właściwy kod waluty, np. EUR, liczbową wartość i listę produktów. Adres potwierdzenia musi należeć do domeny sklepu i nie może zawierać adresu e-mail, tokenów dostępu ani innych poufnych parametrów. Zezwolenie pochodzi z zaufanego rejestru zgód, uwzględniającego znane wycofania; niesprawdzone pole z przeglądarki nie wystarcza.

Przykład usuwa odstępy na początku i końcu adresu e-mail oraz zamienia litery na małe. Następnie SHA-256 oblicza z tego tekstu skrót o stałej długości. Opcjonalny numer telefonu musi już mieć prawidłową postać, na przykład +12133734253; znak plus pozostaje częścią haszowanej wartości. Wyrażenie regularne sprawdza jedynie podstawowy format, bez potwierdzania poprawności numeru. Odczyt i sprawdzenie numeru według zasad właściwego kraju następują przed wywołaniem funkcji. Brakujący numer jest pomijany. E-mail jest wymagany w tym uproszczonym przykładzie, ale nie stanowi jedynej metody dopasowania obsługiwanej przez TikTok.

Haszowanie nie anonimizuje danych. Dodatkowe pola mają osobne zasady: external_id wymaga haszowania, natomiast ttclid, ttp, adres IP i user agent są przesyłane bez haszowania. Surowe identyfikatory i skróty nie powinny trafiać do ogólnych logów diagnostycznych. Dane kontaktowe potrzebne do realizacji zamówienia podlegają odrębnym zasadom retencji sklepu.

Wysyłka powinna następować możliwie szybko po potwierdzeniu zakupu. Kolejka zachowuje pierwotną identyfikację i czas, ponownie sprawdza zgodę przed wysyłką oraz ogranicza ponowienia. Ocena obejmuje status HTTP, czyli status odpowiedzi na żądanie sieciowe, oraz odpowiedź JSON zawierającą uporządkowane dane wyniku: code: 0 oznacza powodzenie wywołania API, bez dowodu dopasowania osoby lub atrybucji reklamowej. Timeout oznacza brak odpowiedzi w wyznaczonym czasie. Może wystąpić także po przyjęciu danych, dlatego potrzebny jest status „wynik nieznany”, bez tworzenia nowego identyfikatora zdarzenia.

Krok 5: Osobna kontrola dostarczenia, powtórzeń i przypisania do reklam

Test Events i udostępniony test_event_code służą do sprawdzenia wybranej integracji. Dane testowe są oddzielone od produkcji; konfiguracja testowa musi zostać usunięta przed rzeczywistym raportowaniem. Widoczne zahaszowane pola nie potwierdzają skutecznego dopasowania osoby. Kontrolowany zakup testowy sprawdza oba kanały, wspólny kod piksela, identyczne identyfikatory zdarzenia i zgodne wartości zakupu.

Bieżąca kontrola opiera się na szczegółach deduplikacji i diagnostyce w Events Managerze. Sumowanie metryk przeglądarkowych, serwerowych i wspólnych wymaga wcześniejszego sprawdzenia definicji. Same równe sumy nie dowodzą błędu: bez nakładania kanałów nie występują duplikaty. Porównanie zmieniają również opóźnienia raportowania, strefy czasowe i filtry.

Uzgodnienie z danymi sklepu wymaga jednakowej definicji zakupu, okresu i zbioru zakupów dopuszczonych do przekazania. „Total Events” obejmuje zdarzenia przypisane i nieprzypisane do reklam; zakupy przypisane do reklam w Ads Managerze zależą dodatkowo od dopasowania osoby i okien atrybucji, czyli dopuszczalnych okresów między kontaktem z reklamą a zakupem. Przyjęte zdarzenie nie jest zatem gwarantowaną konwersją reklamową.