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 vedere quale classe di rilevamento è scattata (veda Tipi di bot per il vocabolario completo):
| bot.type | Causa comune del falso positivo | Soluzione |
|---|---|---|
automation | Uno strumento di testing ha lasciato il browser in modalità di automazione | Disattivare la modalità di automazione al di fuori dei test |
headless | VDI / desktop remoto che renderizza senza una GPU reale | Veda «Ambienti aziendali» più sotto |
extension | È attiva un'estensione di automazione, proxy o VPN | Riesamini l'estensione |
other | È scattato un indicatore di automazione non specifico | Consulti reasons (Business+) per la classe |
Nei piani Business ed Enterprise, l'array reasons del webhook nomina la classe di
osservazione alla base del verdetto: è il modo più rapido per capire un falso positivo.
Veda Codici motivo.
2. Ambienti aziendali con rendering software
Gli ambienti Citrix, VDI e terminal server renderizzano senza una GPU reale, il che
assomiglia a un runtime 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") { // VDI and remote-desktop users render without a real GPU and can trip the // headless classification — 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 sensibilmente più tempo a rispondere rispetto agli altri
suoi dispositivi e alle altre sue reti di test.
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. La raccolta richiede troppo tempo
Su dispositivi poco potenti la raccolta richiede più tempo. Ogni controllo che può essere lento è delimitato dal proprio timeout, quindi la raccolta non blocca mai indefinitamente: un controllo che esaurisce il tempo viene semplicemente riportato come non disponibile e l'identificazione prosegue senza di esso.
L'identificazione va a buon fine, ma la confidenza è più bassa del previsto su uno specifico browser o classe di dispositivi.
Non tutti i controlli possono essere eseguiti in ogni ambiente: una CSP restrittiva, le limitazioni della piattaforma e le funzioni di privacy del browser ne rendono alcuni non disponibili. Questo è previsto e gestito con eleganza: la confidenza viene calcolata da ciò che è stato effettivamente raccolto, ed è per questo che i browser irrigiditi si identificano legittimamente con una confidenza inferiore rispetto a uno standard.
Non è richiesta alcuna azione da parte sua. Se la confidenza è costantemente bassa su
una quota rilevante del suo traffico, contatti il supporto con un requestId: la
diagnosi si fa dal record lato server, non dal browser.
Se incontra un problema non trattato qui:
debug: true dell'SDKrequestId di un'identificazione interessata