Per Iniziare

Questa guida ti aiuterà ad aggiungere Noxtica alla tua applicazione web in pochi minuti.

Prerequisiti

• Un account Noxtica (richiedi l’accesso tramite contact)
• La tua Site Key (fornita dopo la configurazione dell’account)

Integrazione Rapida

Una volta configurato l’account e ottenuta la Site Key, aggiungi il nostro collector al tuo HTML — questo è tutto l’installazione.

Raccolta Automatica (Consigliata)

Il modo più semplice per iniziare è lasciare che Noxtica si gestisca da solo, usando la modalità run-once:

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

Questo farà sì che:

• Un visitatore venga valutato alla sua prima visita
• Il risultato venga riutilizzato per le visite successive entro la finestra di cache (default: 7 giorni)
• Le visite di ritorno vengano registrate silenziosamente senza ripetere la valutazione completa
• Le tab aperte vengano coordinate così un visitatore viene valutato una sola volta

I risultati sono disponibili tramite:

// Listen for results
document.addEventListener('noxtica:collected', function (e) {
	console.log('Fingerprint collected:', e.detail);
	console.log('Risk score:', e.detail.score);
	console.log('Risk level:', e.detail.risk_level);
});

// Or access directly after collection
console.log(window.noxticaResult);

Raccolta Manuale

Per maggiore controllo, usa l’API JavaScript:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Create a client with your Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Collect and submit in one call
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

Raccolta Intelligente con checkOnce()

Per il minimo impatto, usa checkOnce() — rispetta l’intervallo di raccolta che configuri sul server, così i visitatori non vengono rivalutati più spesso del necessario:

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

// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);

Prestazioni e Impatto sul Sito

Il collector è progettato per avere un impatto minimo sul caricamento della pagina e sulla latenza percepita dall’utente:

Come lo manteniamo leggero:

• Attributo async — il collector si carica in background e non ritarda mai la visibilità o l’interattività della tua pagina.
• Modalità run-once (data-auto-check-once) — dopo la prima valutazione, le visite successive entro la finestra di cache inviano solo un piccolo ping (~150 byte).
• Coordinamento cross-tab — più tab aperte collassano a una singola valutazione.
• In cache dopo il primo carico — il KHAN VM a prova di manomissione viene messo in cache dal browser, quindi si carica istantaneamente nelle visite successive.
• Elaborazione in background dove supportata, così il lavoro rimane fuori dal main thread e la tua pagina resta reattiva.

Se noti un rallentamento dopo aver aggiunto l’SDK, cattura un profilo con await client.collectAndSubmit({ telemetry: true }) — il result.telemetry restituito include una ripartizione dei tempi.

Sandbox vs. Produzione

Avrai due Site Key: una per sviluppo e staging, una per produzione. Ognuna gira con le proprie policy e mantiene i dati completamente separati.

Usa sempre la Site Key giusta per ambiente. Non usare mai una chiave pk_sand_* nel traffico di produzione — i dati sandbox non appariranno nelle tue dashboard di produzione e il punteggio di rischio sarà troppo permissivo. Al contrario, usare una chiave pk_prod_* in sviluppo consuma il budget del rate limit di produzione.

Un pattern comune:

<script>
	// Pick the key by hostname; fall back to sandbox in dev.
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica.js';
	s.async = true;
	s.dataset.siteKey = KEY;
	s.dataset.autoInit = '';
	s.dataset.autoCheckOnce = '';
	document.head.appendChild(s);
</script>

Compatibilità con i Tag Manager

Il collector funziona con Google Tag Manager, Adobe Launch, Tealium e Segment, MA con alcune avvertenze:

Raccomandato (preferito): aggiungi lo script direttamente al tuo HTML, immediatamente prima di </body> o in <head> con async. Partire il prima possibile dà al collector il miglior vantaggio iniziale, così è pronto nel momento in cui un visitatore interagisce.

Tag manager — funziona, con avvertenze:

• ✅ La maggior parte dei tag manager moderni (GTM Custom HTML, Adobe Launch Custom Code, Segment Custom Source) carica il collector con successo.
• ⚠️ I gate di consenso che bloccano gli script fino a che un visitatore accetta ritarderanno la prima valutazione — di solito nulla gira fino a che il banner di consenso non viene chiuso. Questo è il comportamento corretto; sappi solo che può influire sulle tue metriche “tempo-alla-decisione”.
• ⚠️ Alcuni tag manager meno recenti eliminano gli attributi data-* personalizzati. Se data-site-key non raggiunge il tag script, l’auto-init non partirà. Configuralo tu stesso nel codice invece:

  NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();

• ❌ Alcuni container di tag molto isolati (rari) impediscono l’avvio del runtime a prova di manomissione. L’SDK continua a funzionare con una forma più leggera di raccolta e registra un avviso nella console.

Se devi integrare tramite tag manager, configuralo per far scattare il tag Noxtica su All Pages — Window Loaded (o equivalente) piuttosto che DOM Ready — questo garantisce che lo stato del consenso sia definitivo prima che qualcosa venga eseguito.

Content Security Policy

Se il tuo sito usa una content-security-policy, dovrai consentire a Noxtica di caricarsi, eseguire il suo runtime a prova di manomissione (il KHAN VM) e comunicare con la nostra API. L’esempio qui sotto copre tutti e tre:

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

Se la policy omette il token 'wasm-unsafe-eval', il browser blocca il runtime a prova di manomissione e vedrai un avviso correlato nella console. Noxtica continua a funzionare — ricade su una forma più leggera di raccolta — ma con una protezione anti-manomissione più debole. Aggiungere il token qui sopra ripristina l’esperienza completa.

Site Key

La tua Site Key (pk_...) è un identificatore pubblico che autentica le richieste dal tuo dominio. Ogni dominio che aggiungi nel Backoffice riceve una Site Key univoca.

Note importanti:

• Le Site Key sono pubbliche e possono essere incorporate in modo sicuro nel tuo HTML
• Ogni Site Key è legata a un origin specifico (ad es. https://example.com)
• L’API rifiuterà le richieste il cui origin non corrisponde al dominio registrato della Site Key

Opzioni di Configurazione

const client = NoxticaCollector.createClient({
	// Your Site Key (required)
	siteKey: 'pk_prod_your_site_key_here',

	// API endpoint (defaults to production)
	apiUrl: 'https://collect.noxtica.com',

	// Collection mode: 'max' (default), 'standard', or 'minimal'
	// Omit to use max mode (recommended)
	// mode: 'standard', // Uncomment to opt out of max-only signals
});

Modalità di Raccolta

Formato della Risposta

Dopo la raccolta e l’invio, ricevi:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"flags": [],
	"details": {
		"summary": "Detected 0 risk indicator(s)."
	}
}

Livelli di Rischio

Autenticazione

L’SDK autentica ogni visita con credenziali a breve durata, ruotate automaticamente e legate alla tua Site Key. Le richiede, le aggiorna e le allega a ogni invio per te.

Non hai bisogno di gestire nulla di questo — l’SDK se ne occupa automaticamente.

Processo di Onboarding

1. Richiedi l’accesso: contattaci per richiedere una demo o iniziare
2. Configurazione account: creiamo il tuo account tenant sulla piattaforma
3. Aggiungi domini: accedi al Backoffice, vai su Domains e aggiungi i tuoi origin
4. Copia la Site Key: ogni dominio riceve una Site Key univoca
5. Integra: aggiungi lo script con la tua Site Key alle tue pagine
6. Monitora: visualizza fingerprint e analytics nella dashboard del Backoffice

Gestione di Più Domini

Noxtica supporta più domini per account:

• Produzione: https://www.yoursite.com
• Staging: https://staging.yoursite.com
• Mobile: https://m.yoursite.com

Ogni dominio ha la propria Site Key. Puoi:

• Abilitare/disabilitare i domini senza rigenerare le chiavi
• Ruotare le Site Key in caso di compromissione
• Visualizzare le analytics filtrate per dominio

Versione SDK

Versione attuale dell’SDK: 3.3.0 (Schema: 2026-05-24)

Novità della 3.3.0

• Segnali comportamentali leggeri (sempre attivi) — semplici indicatori di timing come la durata di una sessione e la velocità con cui un visitatore interagisce per la prima volta. Nessun dato biometrico e nessun consenso dell’utente finale richiesto.
• Biometria comportamentale (opt-in) — quando la attivi in Backoffice → Settings → Behavioral Biometrics, Noxtica analizza anche il ritmo del movimento del mouse, i tempi di click e lo scrolling. Questo conta come dato biometrico ai sensi delle normative sulla privacy più severe, quindi è richiesto il consenso esplicito dell’utente finale. Consulta Biometria Comportamentale qui sotto.
• Verifica della coerenza Apple Pay — conferma che un dispositivo che afferma di essere un iPhone si comporti davvero come tale, individuando un comune trucco di spoofing.
• Corrispondenza del fingerprint di rete — riconosce i pattern di connessione caratteristici dei comuni strumenti di automazione, così il traffico da script e bot risalta anche quando il browser sembra convincente.
• Reputazione IP — segnala i visitatori che arrivano da reti con una cattiva reputazione, con la possibilità di collegare il tuo feed di threat intelligence preferito.

Biometria Comportamentale (Opzionale, Opt-In)

Noxtica può anche analizzare il ritmo con cui qualcuno muove il mouse, clicca e scrolla. È una funzionalità opt-in, disattivata per default.

Perché opt-in? Questo tipo di dati comportamentali conta come dato personale sensibile ai sensi delle normative sulla privacy più severe, quindi catturarli richiede il consenso esplicito del tuo utente finale. Lo rendiamo opt-in così sei tu a controllare quando e come viene usato.

Per abilitarlo:

1. Accedi a Backoffice → Settings → Behavioral Biometrics
2. Esamina l’avviso di conformità con il tuo team privacy o legale
3. Aggiorna la tua privacy policy e il banner di consenso per divulgare questa raccolta
4. Attiva la funzionalità

Una volta abilitato, Noxtica include automaticamente questi segnali comportamentali nelle valutazioni future, e la tua dashboard mostra il punteggio comportamentale risultante per dominio.

Prossimi Passi

• Prova la demo live per vedere il fingerprinting in azione
• Leggi la guida Backend Integration per le consultazioni lato server
• Accedi alla dashboard per esplorare i dati raccolti