Questa pagina copre i problemi comuni riscontrati durante l'integrazione di TRACIO e le relative soluzioni. TRACIO è un servizio cloud gestito, quindi la maggior parte dei problemi è lato client (script bloccato, cookie, funzioni di privacy del browser) anziché di infrastruttura.
Lo script dell'agente o la richiesta di identificazione non si carica, oppure la console del browser mostra un errore CORS verso edge.tracio.ai.
1. Origin non presente nella allowlist della sua key
Ogni public key può essere vincolata a un insieme di origin consentite. Se l'origin del suo sito non è nella allowlist, l'edge respinge la richiesta (403). Aggiunga il suo origin sotto Request Filtering nella dashboard, oppure confermi che la key che sta usando non sia vincolata per origin a un sito diverso.
2. Ad blocker o CSP che blocca la richiesta
Le estensioni per la privacy (uBlock Origin, AdBlock) o una Content-Security-Policy restrittiva possono bloccare lo script dell'agente o la sua richiesta di rete. L'SDK espone questo come errore blocked (vedi Gestione degli errori). Per rendere più difficile il blocco, serva l'agente da un sottodominio first-party usando le opzioni scriptUrl / endpoint.
3. Endpoint / regione errati
Si assicuri di puntare all'endpoint corretto. Quando imposta region, l'SDK comunica con edge.us.tracio.ai o edge.eu.tracio.ai; se non impostato, usa edge.tracio.ai.
I punteggi di confidenza sono costantemente inferiori a 0.90 per i visitatori di ritorno.
1. Cookie che non persiste
Il cookie _vid_t potrebbe non impostarsi correttamente. Verifichi nel browser:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Se il cookie è assente, veda la sezione Cookie che non persiste qui sotto.
2. Workspace nuovo
Un workspace nuovo di zecca ha un database dei visitatori vuoto, quindi tutti i visitatori appaiono come «nuovi» con una confidenza intorno a 0.90. Dopo 24-48 ore, i visitatori di ritorno vengono riconosciuti con una confidenza più alta.
3. Navigazione in incognito/privata
In modalità incognito, i cookie e il localStorage vengono cancellati al termine della sessione. TRACIO ripiega sul matching basato solo sui segnali, che ha una confidenza più bassa (tipicamente 0.85-0.95).
4. Browser con anti-fingerprinting aggressivo
Brave, Firefox (modalità strict) e Safari (ITP) modificano o bloccano alcuni segnali del browser. Questo riduce l'insieme di segnali disponibili per il matching. TRACIO rileva questi browser e adegua la confidenza di conseguenza.
Ispezioni l'identificazione nella dashboard (Visitors / Events), oppure agisca sul
recapito del webhook, che trasporta identification.confidence,
identification.incognito e il verdetto bot per ciascun evento.
Visitatori umani legittimi vengono segnalati come bot.
1. Estensioni del browser che modificano le proprietà di navigator
Alcune estensioni per la privacy modificano navigator.userAgent, navigator.platform o altre proprietà. Questo può attivare il rilevatore di manomissione ma non dovrebbe attivare da solo il rilevamento dei bot.
Verifichi il campo bot.type per identificare quale rilevatore è scattato:
| bot.type | Causa comune del falso positivo | Soluzione |
|---|---|---|
webdriver | Strumento di testing del browser ha lasciato navigator.webdriver = true | L'utente dovrebbe disattivare la modalità di testing |
headless | VNC/desktop remoto con rendering GPU software | Verifichi se il renderer GPU è SwiftShader/llvmpipe |
unknown | Anomalia della lunghezza di eval da un'estensione del browser | Riesamini l'estensione |
rateBot | Refresh automatico della pagina o polling aggressivo | Riduca la frequenza delle richieste |
2. Ambienti aziendali con rendering software
Gli ambienti Citrix, VDI e terminal server usano spesso il rendering GPU software (SwiftShader, llvmpipe), che è un marcatore headless. Se i suoi utenti operano in questi ambienti, applichi una policy più permissiva quando il webhook mostra un tipo di bot 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. Testing automatizzato in produzione
Se il suo team di QA esegue test Selenium/Playwright contro la produzione, questi verranno correttamente rilevati come bot. Usi una key separata per il traffico di test.
Il cookie _vid_t scompare tra una visita e l'altra, facendo apparire ogni visita come un visitatore «nuovo».
1. Sito non HTTPS
Il cookie _vid_t usa il flag Secure e viene impostato solo su HTTPS. Si assicuri che il suo sito usi HTTPS.
2. Caricamento cross-site
TRACIO imposta SameSite=Lax sul cookie. Se l'agente viene caricato in un contesto strettamente cross-site, il cookie può essere bloccato. Servire l'agente da un sottodominio first-party (tramite scriptUrl / endpoint) lo mantiene same-site.
3. Safari ITP
L'Intelligent Tracking Prevention (ITP) di Safari può limitare la durata dei cookie impostati dal client. TRACIO emette _vid_t anche lato server tramite l'header Set-Cookie e replica l'UID nel localStorage, così l'identità sopravvive anche quando il cookie viene limitato.
4. Browser che cancella i cookie
Alcuni browser (Brave, Firefox Focus) cancellano i cookie al termine della sessione. Gli utenti con impostazioni di privacy aggressive appariranno sempre come visitatori nuovi.
tracio.getResult() impiega più di 500ms per restituire un risultato.
1. Rete lenta verso l'edge
Verifichi la latenza di andata e ritorno verso il suo edge regionale:
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. Raccolta dei segnali che richiede troppo tempo
Alcuni segnali hanno dei timeout. Su dispositivi lenti, la raccolta può richiedere 200ms+. I segnali che con maggiore probabilità aggiungono latenza sono il fingerprint audio (AudioContext sospeso su iOS), la sonda WebRTC/TURN, il rilevamento dei font e il timing DRM. Questi sono delimitati da timeout e non bloccano mai indefinitamente.
Alcuni segnali restituiscono uno stato di non-successo (ad esempio «not available» o «timeout»).
Gli errori dei segnali sono attesi e gestiti con eleganza — il sistema adegua la confidenza in base ai segnali disponibili. Esempi comuni: canvas bloccato dalla CSP, AudioContext in timeout su iOS, WebGPU non supportato sulla maggior parte dei browser, Client Hints non disponibili al di fuori di Chromium. Non è richiesta alcuna azione a meno che segnali critici (canvas, WebGL, audio) non falliscano costantemente su molti visitatori.
Se incontra un problema non trattato qui:
debug: true dell'SDKrequestId di un'identificazione interessata