Runtime del Browser

Questa guida spiega come l’SDK di Noxtica funziona all’interno del browser dei tuoi visitatori — cosa succede durante una valutazione, come il caching mantiene tutto veloce e come risolvere i problemi più comuni.

Come Funziona

Quando aggiungi l’SDK di Noxtica alla tua pagina, svolge silenziosamente quattro operazioni:

1. Autentica: accede con la tua Site Key usando credenziali che gestisce per te
2. Raccoglie: legge i segnali quotidiani che un browser già espone
3. Invia: li manda a Noxtica per la valutazione del rischio
4. Memorizza in cache: salva il risultato localmente così non ripete il lavoro a ogni visita

Tutto questo gira in background e non blocca mai la tua pagina.

Flusso di Raccolta

Automatico (Consigliato)

Usando data-auto-check-once, l’SDK utilizza la raccolta intelligente:

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key"
	data-auto-init
	data-auto-check-once
	async
></script>

Usi una content-security-policy? Dovrai consentire a Noxtica di caricare ed eseguire il suo runtime a prova di manomissione, il KHAN VM. Se non può avviarsi, Noxtica continua a funzionare con una forma più leggera di raccolta e una protezione anti-manomissione ridotta. Consulta Getting Started → Content Security Policy per lo snippet esatto.

Prima visita: viene eseguita una valutazione completa e il risultato viene messo in cache.

Visite successive (entro la finestra di cache): viene restituito il risultato in cache e registrata una visita leggera. Nessun lavoro pesante viene eseguito.

Dopo la scadenza della cache: viene eseguita una valutazione aggiornata.

Controllo Manuale

Per il controllo programmatico, usa il metodo checkOnce():

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key',
});

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

Comportamento della Cache

L’SDK mette in cache ogni risultato nel browser così non rivaluta lo stesso visitatore a ogni visualizzazione di pagina.

Chiave di Cache

nox_fp_{your_site_key}

Cosa Viene Messo in Cache

• Device ID
• Timestamp dell’ultimo invio
• Timestamp dell’ultima visualizzazione
• Punteggio e livello di rischio precedenti

TTL (Time-To-Live)

Il TTL predefinito della cache è 7 giorni. È configurabile:

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

Forzare l’Aggiornamento

Per bypassare la cache e raccogliere un fingerprint aggiornato:

const result = await client.checkOnce({
	forceRefresh: true,
});

Coordinamento Cross-Tab

Quando un visitatore apre più tab del tuo sito contemporaneamente, l’SDK fa sì che vengano valutati una sola volta:

• Solo una tab svolge il lavoro reale
• Le altre tab aspettano e condividono il risultato

Avviene automaticamente — nessuna configurazione necessaria.

Eventi

L’SDK emette eventi a cui puoi ascoltare:

noxtica:collected

Si attiva dopo una raccolta riuscita o quando viene restituito un risultato dalla cache:

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

Si attiva specificamente quando viene restituito un risultato dalla cache:

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

Si attiva quando la raccolta fallisce:

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

Variabili Globali

Dopo la raccolta, i risultati sono disponibili globalmente:

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

Gestione degli Errori

Errori Comuni

Gestione Manuale degli Errori

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

Modalità di Raccolta

L’SDK supporta tre modalità di raccolta:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // or 'minimal', 'standard'
});

Modalità Protetta (KHAN VM)

La parte più difficile nel contrastare i bot è che qualsiasi cosa giri in un browser è, in linea di principio, visibile e modificabile. Un attaccante determinato può leggere il codice della pagina, capire cosa viene misurato e restituire silenziosamente valori falsi.

Il KHAN VM aumenta il costo di questo. Invece di lasciare la raccolta esposta come codice leggibile sulla pagina, Noxtica fa girare la parte sensibile all’interno di un runtime sigillato e isolato. La logica che decide cosa misurare non è visibile per un attaccante da studiare e riscrivere, e il risultato che produce è sigillato prima di lasciare il browser — rendendolo molto più difficile da manomettere o riprodurre.

Cosa aiuta il KHAN VM:

• Risultati a prova di manomissione — la valutazione è sigillata dentro la sandbox prima di essere inviata, così altri script sulla pagina non possono alterarla o riprodurla silenziosamente.
• Più difficile da fare reverse engineering — la logica di raccolta rimane nascosta all’interno del runtime invece di essere leggibile negli strumenti per sviluppatori del browser.
• Protezione dal replay — ogni risultato è monouso e verificato, così una risposta catturata non può semplicemente essere riutilizzata per fingere un visitatore pulito.

Limiti onesti — cosa non fa:

• È una funzionalità di resistenza alla manomissione, non crittografia end-to-end.
• Se la tua stessa pagina è compromessa (ad esempio, da una falla di cross-site scripting), un attaccante su quella pagina può vedere gli stessi segnali del browser grezzi che vede Noxtica. Il KHAN VM protegge l’elaborazione e il risultato, non la pagina intorno ad esso.

Il KHAN VM viene attivato dal lato server e non richiede modifiche alla tua integrazione. Se non riesce ad avviarsi — ad esempio perché una content-security-policy lo blocca — Noxtica ricade su una forma più leggera di raccolta così il rilevamento continua a funzionare, ma con una protezione anti-manomissione più debole.

Supporto Browser

L’SDK supporta i browser moderni:

I browser più datati potrebbero avere un’accuratezza ridotta dei segnali, ma continueranno a funzionare.

Modalità Debug

Attiva il logging di debug per risolvere i problemi:

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

La modalità debug registra:

• L’avanzamento della raccolta
• Il ciclo di vita dei token
• Cache hit e miss
• Eventuali errori incontrati

Nota: la modalità debug è silenziosa per impostazione predefinita in produzione. Nessun output sulla console appare a meno che non sia esplicitamente abilitata.

Considerazioni sullo Storage

Storage del Browser

L’SDK usa il local storage del browser per mettere in cache i risultati. Se non disponibile (ad esempio, in navigazione privata o con lo storage disabilitato):

• Il rilevamento funziona comunque
• Ogni caricamento di pagina esegue una valutazione aggiornata
• Il coordinamento cross-tab potrebbe essere ridotto

Nessun Cookie

L’SDK non usa cookie. Tutto ciò di cui ha bisogno è conservato nel local storage del browser.

Impatto sulle Prestazioni

Prima Visita

La raccolta gira in modo asincrono e non blocca il rendering della pagina.

Visite Successive (Cache Hit)

Risoluzione dei Problemi

Il Fingerprint Non Viene Raccolto

1. Controlla la console del browser per errori
2. Verifica che la Site Key corrisponda esattamente al tuo dominio (incluso https://)
3. Assicurati che il dominio sia abilitato nel Backoffice
4. Attiva la modalità debug per vedere log dettagliati

”WebAssembly blocked by Content Security Policy”

Se vedi questo avviso nella console del browser, la content-security-policy della tua pagina sta bloccando il runtime a prova di manomissione (il KHAN VM). Il rilevamento continua a funzionare in modalità più leggera, ma otterrai la protezione più completa consentendolo.

Usa lo snippet qui sotto per consentire a Noxtica di caricarsi ed eseguirsi:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com; connect-src 'self' https://collect.noxtica.com

Consulta Getting Started → Content Security Policy per il riferimento completo.

Device ID Diversi sullo Stesso Dispositivo

Può succedere quando:

• I dati salvati nel browser vengono cancellati
• Il profilo del browser cambia
• Il visitatore usa la modalità privata/incognito
• Il browser riceve un aggiornamento importante

È un comportamento atteso — il riconoscimento si adatta man mano che un dispositivo cambia nel tempo.

La Raccolta Richiede Troppo Tempo

1. Controlla la scheda di rete per risposte API lente
2. Valuta di usare mode: 'minimal' per una raccolta più veloce
3. Assicurati che l’SDK sia caricato con l’attributo async

Gli Eventi Non Si Attivano

1. Assicurati di ascoltare prima che l’SDK venga eseguito
2. Verifica che gli attributi di auto-init siano corretti
3. Controlla che non ci siano errori JavaScript che bloccano l’esecuzione

Buone Pratiche

1. Usa data-auto-check-once invece di data-auto-collect per ridurre al minimo le raccolte ridondanti

2. Carica l’SDK in modo asincrono con l’attributo async per evitare di bloccare il caricamento della pagina

3. Ascolta gli eventi invece di interrogare window.noxticaResult

4. Non sovrascrivere il TTL inutilmente — l’intervallo predefinito di 7 giorni è ottimizzato per la maggior parte dei casi

5. Gestisci gli errori con grazia — un errore di raccolta non deve interrompere la tua pagina

Prossimi Passi

• Getting Started — guida di configurazione iniziale
• Backend Integration — consultazioni dei dispositivi lato server