Ta strona omawia typowe problemy napotykane podczas integracji TRACIO oraz ich rozwiązania. TRACIO to zarządzana usługa chmurowa, więc większość problemów występuje po stronie klienta (zablokowany skrypt, pliki cookie, funkcje prywatności przeglądarki), a nie po stronie infrastruktury.
Skrypt agenta lub żądanie identyfikacji nie ładuje się, albo konsola przeglądarki pokazuje błąd CORS wobec edge.tracio.ai.
1. Origin nie znajduje się na liście dozwolonych dla Twojego klucza
Każdy klucz publiczny można ograniczyć do zestawu dozwolonych origins. Jeśli origin Twojej witryny nie jest na liście dozwolonych, edge odrzuca żądanie (403). Dodaj swój origin w sekcji Request Filtering w panelu lub upewnij się, że używany klucz nie jest przypisany do origin innej witryny.
2. Blokada reklam lub CSP blokujące żądanie
Rozszerzenia prywatności (uBlock Origin, AdBlock) lub restrykcyjna Content-Security-Policy mogą blokować skrypt agenta lub jego żądanie sieciowe. SDK zgłasza to jako błąd blocked (zobacz Obsługa błędów). Aby utrudnić blokowanie, serwuj agenta z subdomeny first-party, korzystając z opcji scriptUrl / endpoint.
3. Nieprawidłowy endpoint / region
Upewnij się, że kierujesz żądania do właściwego endpointu. Gdy ustawisz region, SDK komunikuje się z edge.us.tracio.ai lub edge.eu.tracio.ai; bez ustawienia używa edge.tracio.ai.
Wskaźniki pewności dla powracających odwiedzających konsekwentnie utrzymują się poniżej 0.90.
1. Plik cookie nie jest utrwalany
Plik cookie _vid_t może nie być ustawiany poprawnie. Sprawdź w przeglądarce:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Jeśli plik cookie brakuje, zobacz sekcję Plik cookie nie jest utrwalany poniżej.
2. Nowy workspace
Zupełnie nowy workspace ma pustą bazę danych odwiedzających, więc wszyscy odwiedzający pojawiają się jako „nowi” z pewnością około 0.90. Po 24–48 godzinach powracający odwiedzający są rozpoznawani z wyższą pewnością.
3. Tryb incognito / przeglądanie prywatne
W trybie incognito pliki cookie i localStorage są czyszczone po zakończeniu sesji. TRACIO przełącza się wtedy na dopasowywanie wyłącznie na podstawie sygnałów, które ma niższą pewność (zazwyczaj 0.85–0.95).
4. Przeglądarki z agresywnym anty-fingerprintingiem
Brave, Firefox (tryb strict) oraz Safari (ITP) modyfikują lub blokują niektóre sygnały przeglądarki. Zmniejsza to zestaw sygnałów dostępnych do dopasowania. TRACIO wykrywa te przeglądarki i odpowiednio dostosowuje pewność.
Przeanalizuj identyfikację w panelu (Visitors / Events) lub zareaguj na dostarczenie
webhooka, który przenosi identification.confidence,
identification.incognito oraz werdykt bot dla każdego zdarzenia.
Prawdziwi odwiedzający (ludzie) są oznaczani jako boty.
1. Rozszerzenia przeglądarki modyfikujące właściwości navigatora
Niektóre rozszerzenia prywatności modyfikują navigator.userAgent, navigator.platform lub inne właściwości. Może to uruchomić detektor manipulacji, ale samo w sobie nie powinno uruchamiać wykrywania botów.
Sprawdź pole bot.type, aby ustalić, który detektor się uruchomił:
| bot.type | Częsta przyczyna fałszywego wykrycia | Rozwiązanie |
|---|---|---|
webdriver | Narzędzie do testów pozostawiło navigator.webdriver = true | Użytkownik powinien wyłączyć tryb testowy |
headless | VNC/zdalny pulpit z programowym renderowaniem GPU | Sprawdź, czy renderer GPU to SwiftShader/llvmpipe |
unknown | Anomalia długości eval spowodowana rozszerzeniem przeglądarki | Sprawdź rozszerzenie |
rateBot | Automatyczne odświeżanie strony lub agresywny polling | Zmniejsz częstotliwość żądań |
2. Środowiska korporacyjne z renderowaniem programowym
Środowiska Citrix, VDI i serwerów terminalowych często korzystają z programowego renderowania GPU (SwiftShader, llvmpipe), co jest markerem headless. Jeśli Twoi użytkownicy pracują w takich środowiskach, zastosuj łagodniejszą politykę, gdy webhook pokazuje typ bota headless:
// `event` is the webhook delivery body (/docs/webhooks)if (event.bot.result === "bot" && event.bot.type === "headless") { // Software-GPU (SwiftShader/llvmpipe) VDI users can trip the headless // detector — consider applying a softer policy for these.}3. Automatyczne testy w środowisku produkcyjnym
Jeśli Twój zespół QA uruchamia testy Selenium/Playwright na produkcji, zostaną one prawidłowo wykryte jako boty. Użyj osobnego klucza dla ruchu testowego.
Plik cookie _vid_t znika między wizytami, przez co każda wizyta jawi się jako „nowy” odwiedzający.
1. Witryna bez HTTPS
Plik cookie _vid_t używa flagi Secure i jest ustawiany wyłącznie przez HTTPS. Upewnij się, że Twoja witryna korzysta z HTTPS.
2. Ładowanie cross-site
TRACIO ustawia na pliku cookie SameSite=Lax. Jeśli agent jest ładowany w ściśle cross-site kontekście, plik cookie może zostać zablokowany. Serwowanie agenta z subdomeny first-party (przez scriptUrl / endpoint) utrzymuje go jako same-site.
3. Safari ITP
Intelligent Tracking Prevention (ITP) w Safari może ograniczać czas życia plików cookie ustawianych po stronie klienta. TRACIO dodatkowo wystawia _vid_t po stronie serwera za pomocą nagłówka Set-Cookie i odzwierciedla UID w localStorage, dzięki czemu tożsamość przetrwa nawet wtedy, gdy czas życia pliku cookie zostanie ograniczony.
4. Przeglądarka czyszcząca pliki cookie
Niektóre przeglądarki (Brave, Firefox Focus) czyszczą pliki cookie po zakończeniu sesji. Użytkownicy z agresywnymi ustawieniami prywatności zawsze będą się pojawiać jako nowi odwiedzający.
tracio.getResult() zwraca wynik po ponad 500 ms.
1. Wolne połączenie sieciowe z edge
Sprawdź opóźnienie round-trip do Twojego regionalnego edge:
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health2. Zbieranie sygnałów trwa zbyt długo
Niektóre sygnały mają limity czasu. Na wolnych urządzeniach zbieranie może trwać 200 ms+. Sygnały, które najczęściej zwiększają opóźnienie, to audio fingerprint (AudioContext zawieszony na iOS), sonda WebRTC/TURN, wykrywanie czcionek oraz pomiar czasu DRM. Są one ograniczone limitami czasu i nigdy nie blokują w nieskończoność.
Niektóre sygnały zwracają status inny niż sukces (na przykład „not available” lub „timeout”).
Błędy sygnałów są oczekiwane i obsługiwane w sposób łagodny — system dostosowuje pewność na podstawie dostępnych sygnałów. Typowe przykłady: canvas zablokowany przez CSP, timeout AudioContext na iOS, WebGPU nieobsługiwane w większości przeglądarek, Client Hints niedostępne poza Chromium. Nie jest wymagane żadne działanie, chyba że krytyczne sygnały (canvas, WebGL, audio) konsekwentnie zawodzą u wielu odwiedzających.
Jeśli napotkasz problem, który nie został tu omówiony:
debug: truerequestId dotkniętej identyfikacji