Runtime de navigateur

Ce guide explique comment le SDK Noxtica fonctionne dans les navigateurs de vos visiteurs — ce qui se passe lors d’une évaluation, comment la mise en cache maintient les performances, et comment résoudre les problèmes courants.

Fonctionnement

Quand vous ajoutez le SDK Noxtica à votre page, il effectue silencieusement quatre opérations :

1. S’authentifie : se connecte avec votre clé de site en utilisant les identifiants qu’il gère pour vous
2. Collecte : lit les signaux courants qu’un navigateur expose déjà
3. Soumet : les envoie à Noxtica pour le scoring
4. Met en cache : stocke le résultat localement pour ne pas répéter le travail à chaque visite

Tout cela se déroule en arrière-plan et ne bloque jamais votre page.

Flux de collecte

Automatique (recommandé)

Avec data-auto-check-once, le SDK utilise une collecte 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>

Vous utilisez une content-security-policy ? Vous devrez autoriser Noxtica à charger et exécuter son environnement d’exécution résistant à l’altération, le KHAN VM. S’il ne peut pas démarrer, Noxtica continue de fonctionner avec une collecte plus légère et une protection contre l’altération plus faible. Voir Démarrage → Content Security Policy pour le snippet exact.

Première visite : une évaluation complète s’exécute et le résultat est mis en cache.

Visites suivantes (dans la fenêtre de cache) : le résultat mis en cache est retourné et une visite légère est enregistrée. Aucun travail lourd ne s’exécute.

Après l’expiration de la fenêtre de cache : une nouvelle évaluation s’exécute.

Contrôle manuel

Pour un contrôle programmatique, utilisez la méthode 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');
}

Comportement de la mise en cache

Le SDK met en cache chaque résultat dans le navigateur pour ne pas réévaluer le même visiteur à chaque vue de page.

Clé de cache

nox_fp_{your_site_key}

Ce qui est mis en cache

• ID de l’appareil
• Horodatage de la dernière soumission
• Horodatage de la dernière vue
• Score et niveau de risque précédents

TTL (durée de vie)

Le TTL de cache par défaut est de 7 jours. Il peut être configuré :

// 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
});

Forcer le rafraîchissement

Pour contourner le cache et collecter une nouvelle empreinte :

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

Coordination entre onglets

Quand un visiteur ouvre plusieurs onglets de votre site en même temps, le SDK s’assure qu’il n’est évalué qu’une seule fois :

• Un seul onglet effectue le vrai travail
• Les autres onglets attendent et partagent ce résultat

Cela se produit automatiquement — aucune configuration n’est nécessaire.

Événements

Le SDK déclenche des événements que vous pouvez écouter :

noxtica:collected

Déclenché après une collecte réussie ou lors du retour d’un résultat mis en 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

Déclenché spécifiquement quand un résultat mis en cache est retourné :

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

noxtica:error

Déclenché quand la collecte échoue :

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

Variables globales

Après la collecte, les résultats sont disponibles globalement :

// 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);

Gestion des erreurs

Erreurs courantes

Gérer les erreurs manuellement

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
	}
}

Modes de collecte

Le SDK prend en charge trois modes de collecte :

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

Mode protégé (KHAN VM)

La partie la plus difficile dans la lutte contre les bots, c’est que tout ce qui tourne dans un navigateur est, en principe, visible et modifiable. Un attaquant déterminé peut lire le code de la page, comprendre ce qui est mesuré, et fournir silencieusement de fausses réponses.

Le KHAN VM augmente le coût de cette attaque. Au lieu d’exposer la collecte en tant que code lisible sur la page, Noxtica exécute la partie sensible à l’intérieur d’un environnement d’exécution cloisonné et scellé. La logique qui décide quoi mesurer n’est pas exposée en clair pour qu’un attaquant l’étudie et la réécrive, et le résultat qu’elle produit est scellé avant de quitter le navigateur — ce qui le rend bien plus difficile à altérer ou à rejouer.

Ce que le KHAN VM apporte :

• Résultats résistants à l’altération — l’évaluation est scellée à l’intérieur du bac à sable avant d’être envoyée, de sorte que d’autres scripts sur la page ne peuvent pas silencieusement l’altérer ou la rejouer.
• Plus difficile à rétroconcevoir — la logique de collecte reste cachée à l’intérieur de l’environnement d’exécution au lieu d’être lisible dans les outils de développement du navigateur.
• Protection contre le rejeu — chaque résultat est à usage unique et vérifié, donc une réponse capturée ne peut pas simplement être réutilisée pour simuler un visiteur légitime.

Limites honnêtes — ce qu’il ne fait pas :

• C’est une fonctionnalité de résistance à l’altération, pas du chiffrement de bout en bout.
• Si votre propre page est compromise (par exemple, par une faille de cross-site scripting), un attaquant sur cette page peut voir les mêmes signaux bruts du navigateur que Noxtica. Le KHAN VM protège le traitement et le résultat, pas la page qui l’entoure.

Le KHAN VM est activé côté serveur et ne nécessite aucune modification de votre intégration. S’il ne peut pas démarrer — par exemple parce qu’une content-security-policy le bloque — Noxtica revient à une collecte plus légère pour que la détection continue de fonctionner, simplement avec une protection contre l’altération plus faible.

Compatibilité navigateur

Le SDK prend en charge les navigateurs modernes :

Les navigateurs plus anciens peuvent avoir une précision de signal réduite mais continueront de fonctionner.

Mode debug

Activez la journalisation de debug pour résoudre les problèmes :

// 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>;

Le mode debug journalise :

• La progression de la collecte
• Le cycle de vie du token
• Les succès et échecs de cache
• Toute erreur rencontrée

Remarque : le mode debug est silencieux par défaut en production. Aucune sortie dans la console n’apparaît sans activation explicite.

Considérations de stockage

Stockage du navigateur

Le SDK utilise le stockage local du navigateur pour mettre en cache les résultats. Si celui-ci est indisponible (par exemple en navigation privée ou avec le stockage désactivé) :

• La détection continue de fonctionner
• Chaque chargement de page effectue une nouvelle évaluation
• La coordination entre onglets peut être réduite

Pas de cookies

Le SDK n’utilise pas de cookies. Tout ce dont il a besoin est conservé dans le stockage local du navigateur.

Impact sur les performances

Première visite

La collecte s’exécute de manière asynchrone et ne bloque pas le rendu de la page.

Visites suivantes (avec cache)

Dépannage

Empreinte non collectée

1. Vérifiez la console du navigateur pour des erreurs
2. Vérifiez que la clé de site correspond exactement à votre domaine (y compris https://)
3. Assurez-vous que le domaine est activé dans le Backoffice
4. Activez le mode debug pour voir les logs détaillés

« WebAssembly blocked by Content Security Policy »

Si vous voyez cet avertissement dans la console du navigateur, la content-security-policy de votre page bloque l’environnement d’exécution résistant à l’altération (le KHAN VM). La détection continue de fonctionner en mode allégé, mais vous obtiendrez la protection la plus robuste en l’autorisant.

Utilisez le snippet ci-dessous pour permettre à Noxtica de se charger et de s’exécuter :

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

Voir Démarrage → Content Security Policy pour la référence complète.

IDs d’appareils différents sur le même appareil

Cela peut se produire quand :

• Les données stockées du navigateur sont effacées
• Le profil du navigateur change
• Le visiteur utilise le mode privé/incognito
• Le navigateur subit une mise à jour majeure

C’est attendu — la reconnaissance s’adapte à mesure qu’un appareil évolue dans le temps.

Collecte trop lente

1. Vérifiez l’onglet réseau pour des réponses API lentes
2. Envisagez d’utiliser mode: 'minimal' pour une collecte plus rapide
3. Assurez-vous que le SDK est chargé avec l’attribut async

Événements qui ne se déclenchent pas

1. Assurez-vous que vous écoutez avant que le SDK ne s’exécute
2. Vérifiez que les attributs auto-init sont corrects
3. Vérifiez qu’il n’y a pas d’erreurs JavaScript bloquant l’exécution

Bonnes pratiques

1. Utilisez data-auto-check-once plutôt que data-auto-collect pour minimiser les collectes redondantes

2. Chargez le SDK de manière asynchrone avec l’attribut async pour éviter de bloquer le chargement de la page

3. Écoutez les événements plutôt que de sonder window.noxticaResult

4. Ne modifiez pas inutilement le TTL — l’intervalle de 7 jours par défaut est optimisé pour la plupart des cas d’usage

5. Gérez les erreurs gracieusement — un échec de collecte ne devrait pas briser votre page

Prochaines étapes

• Démarrage — guide de configuration initiale
• Intégration backend — lookups d’appareils côté serveur