Ця сторінка охоплює поширені проблеми, що виникають під час інтеграції TRACIO, та способи їх розв'язання. TRACIO — це керований хмарний сервіс, тому більшість проблем виникають на боці клієнта (заблокований скрипт, cookie, функції приватності браузера), а не через інфраструктуру.
Скрипт агента або запит на ідентифікацію не завантажується, або консоль браузера показує помилку CORS щодо edge.tracio.ai.
1. Origin не додано до списку дозволених для вашого ключа
Кожен публічний ключ можна обмежити набором дозволених origin. Якщо origin вашого сайту немає у списку дозволених, edge відхиляє запит (403). Додайте свій origin у розділі Request Filtering у дашборді або переконайтеся, що ключ, який ви використовуєте, не прив'язаний за origin до іншого сайту.
2. Блокувальник реклами або CSP блокує запит
Розширення для приватності (uBlock Origin, AdBlock) або сувора Content-Security-Policy можуть блокувати скрипт агента або його мережевий запит. SDK подає це як помилку blocked (див. Обробка помилок). Щоб ускладнити блокування, віддавайте агента з first-party субдомену за допомогою опцій scriptUrl / endpoint.
3. Неправильний endpoint / регіон
Переконайтеся, що ви вказуєте правильний endpoint. Коли ви задаєте region, SDK звертається до edge.us.tracio.ai або edge.eu.tracio.ai; без нього використовується edge.tracio.ai.
Показники упевненості для відвідувачів, що повертаються, стабільно нижчі за 0.90.
1. Cookie не зберігається
Cookie _vid_t, можливо, встановлюється некоректно. Перевірте у браузері:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Якщо cookie відсутнє, див. розділ Cookie не зберігається нижче.
2. Новий workspace
Новісінький workspace має порожню базу відвідувачів, тому всі відвідувачі виглядають як «нові» з упевненістю близько 0.90. Через 24–48 годин відвідувачі, що повертаються, розпізнаються з вищою упевненістю.
3. Режим інкогніто / приватний перегляд
У режимі інкогніто cookie та localStorage очищуються після завершення сесії. TRACIO переходить до зіставлення лише за сигналами, яке має нижчу упевненість (зазвичай 0.85–0.95).
4. Браузери з агресивним анти-fingerprinting
Brave, Firefox (суворий режим) і Safari (ITP) модифікують або блокують деякі сигнали браузера. Це зменшує набір сигналів, доступний для зіставлення. TRACIO виявляє ці браузери та відповідно коригує упевненість.
Перегляньте ідентифікацію в дашборді (Visitors / Events) або реагуйте на
доставку webhook, яка містить identification.confidence,
identification.incognito та вердикт bot для кожної події.
Легітимні відвідувачі-люди позначаються як боти.
1. Розширення браузера модифікують властивості navigator
Деякі розширення для приватності модифікують navigator.userAgent, navigator.platform або інші властивості. Це може спрацювати на детекторі підробки, але саме по собі не має призводити до бот-детекції.
Перевірте поле bot.type, щоб визначити, який детектор спрацював:
| bot.type | Поширена причина хибного спрацювання | Розв'язання |
|---|---|---|
webdriver | Інструмент тестування залишив navigator.webdriver = true | Користувачу слід вимкнути режим тестування |
headless | VNC/віддалений робочий стіл із програмним GPU-рендерингом | Перевірте, чи є SwiftShader/llvmpipe рендерером GPU |
unknown | Аномалія довжини eval через розширення браузера | Перевірте розширення |
rateBot | Автоматичне оновлення сторінки або агресивний polling | Зменшіть частоту запитів |
2. Корпоративні середовища з програмним рендерингом
Середовища Citrix, VDI та термінальних серверів часто використовують програмний GPU-рендеринг (SwiftShader, llvmpipe), що є маркером headless. Якщо ваші користувачі працюють у таких середовищах, застосовуйте м'якшу політику, коли webhook показує тип бота 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. Автоматизоване тестування у продакшені
Якщо ваша QA-команда виконує тести Selenium/Playwright проти продакшену, вони коректно розпізнаватимуться як боти. Використовуйте окремий ключ для тестового трафіку.
Cookie _vid_t зникає між візитами, через що кожен візит виглядає як «новий» відвідувач.
1. Сайт без HTTPS
Cookie _vid_t використовує прапорець Secure і встановлюється лише через HTTPS. Переконайтеся, що ваш сайт використовує HTTPS.
2. Cross-site завантаження
TRACIO встановлює SameSite=Lax на cookie. Якщо агент завантажується у строго cross-site контексті, cookie може бути заблоковане. Віддача агента з first-party субдомену (через scriptUrl / endpoint) зберігає його same-site.
3. Safari ITP
Intelligent Tracking Prevention (ITP) у Safari може обмежувати час життя cookie, встановлених на боці клієнта. TRACIO також видає _vid_t на боці сервера через заголовок Set-Cookie і дублює UID у localStorage, тож ідентичність зберігається навіть тоді, коли cookie обмежене.
4. Браузер очищає cookie
Деякі браузери (Brave, Firefox Focus) очищають cookie після завершення сесії. Користувачі з агресивними налаштуваннями приватності завжди виглядатимуть як нові відвідувачі.
tracio.getResult() повертає результат довше ніж за 500 мс.
1. Повільна мережа до edge
Перевірте затримку туди-назад до вашого регіонального 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. Збирання сигналів триває надто довго
Деякі сигнали мають тайм-аути. На повільних пристроях збирання може тривати 200 мс+. Найімовірніше додають затримку такі сигнали: аудіо-fingerprint (AudioContext призупинено на iOS), проба WebRTC/TURN, виявлення шрифтів і тайминг DRM. Вони обмежені тайм-аутами й ніколи не блокують нескінченно.
Деякі сигнали повертають неуспішний статус (наприклад «not available» або «timeout»).
Помилки сигналів очікувані й обробляються коректно — система коригує упевненість на основі доступних сигналів. Поширені приклади: canvas заблоковано через CSP, тайм-аут AudioContext на iOS, WebGPU не підтримується у більшості браузерів, Client Hints недоступні поза Chromium. Дії не потрібні, якщо тільки критичні сигнали (canvas, WebGL, audio) не збоять стабільно у багатьох відвідувачів.
Якщо ви натрапили на проблему, яку тут не описано:
debug: truerequestId ідентифікації, якої стосується проблема