Browser-Laufzeit

Diese Anleitung erklärt, wie das Noxtica-SDK in den Browsern Ihrer Besucher arbeitet – was während einer Bewertung passiert, wie Caching die Dinge schnell hält und wie Sie häufige Probleme beheben können.

So funktioniert es

Wenn Sie das Noxtica-SDK zu Ihrer Seite hinzufügen, erledigt es leise vier Dinge:

1. Authentifizieren: Meldet sich mit Ihrem Site Key an und verwaltet die Zugangsdaten für Sie
2. Erfassen: Liest die alltäglichen Signale, die ein Browser ohnehin preisgibt
3. Übermitteln: Sendet sie an Noxtica zur Bewertung
4. Cachen: Speichert das Ergebnis lokal, damit die Arbeit nicht bei jedem Besuch wiederholt wird

All das läuft im Hintergrund und blockiert Ihre Seite niemals.

Erfassungsablauf

Automatisch (empfohlen)

Bei Verwendung von data-auto-check-once setzt das SDK die intelligente Erfassung ein:

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

Nutzen Sie eine Content Security Policy? Sie müssen Noxtica erlauben, seine manipulationssichere Laufzeitumgebung, die KHAN VM, zu laden und auszuführen. Wenn das nicht möglich ist, arbeitet Noxtica mit einer leichteren Erfassungsvariante und schwächerem Manipulationsschutz weiter. Siehe Erste Schritte → Content Security Policy für das genaue Snippet.

Erster Besuch: Eine vollständige Bewertung wird durchgeführt und das Ergebnis zwischengespeichert.

Nachfolgende Besuche (innerhalb des Cache-Fensters): Das zwischengespeicherte Ergebnis wird zurückgegeben und ein leichtgewichtiger Besuch aufgezeichnet. Keine aufwendige Arbeit läuft erneut.

Nach Ablauf des Cache-Fensters: Eine neue Bewertung wird durchgeführt.

Manuelle Steuerung

Für programmatische Steuerung verwenden Sie die checkOnce()-Methode:

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

Caching-Verhalten

Das SDK speichert jedes Ergebnis im Browser, damit derselbe Besucher nicht bei jedem Seitenaufruf neu bewertet wird.

Cache-Schlüssel

nox_fp_{your_site_key}

Was zwischengespeichert wird

• Device-ID
• Zeitstempel der letzten Übermittlung
• Zeitstempel der letzten Sichtung
• Vorheriger Risikowert und Risikostufe

TTL (Time-To-Live)

Die Standard-Cache-TTL beträgt 7 Tage. Sie ist konfigurierbar:

// Zur Erfassungszeit überschreiben
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 Tage statt 7
});

// Oder in Sekunden
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 Tag
});

Aktualisierung erzwingen

Um den Cache zu umgehen und einen neuen Fingerprint zu erfassen:

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

Tab-übergreifende Koordination

Wenn ein Besucher mehrere Tabs Ihrer Website gleichzeitig öffnet, sorgt das SDK dafür, dass die Bewertung nur einmal durchgeführt wird:

• Nur ein Tab erledigt die eigentliche Arbeit
• Die anderen Tabs warten und teilen sich das Ergebnis

Das geschieht automatisch – keine Konfiguration nötig.

Events

Das SDK löst Events aus, auf die Sie hören können:

noxtica:collected

Wird nach erfolgreicher Erfassung oder beim Zurückgeben eines zwischengespeicherten Ergebnisses ausgelöst:

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

Wird speziell dann ausgelöst, wenn ein zwischengespeichertes Ergebnis zurückgegeben wird:

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

noxtica:error

Wird ausgelöst, wenn die Erfassung fehlschlägt:

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

Globale Variablen

Nach der Erfassung sind die Ergebnisse global verfügbar:

// Nach Abschluss der Erfassung
console.log(window.noxticaResult);

// Client-Instanz (bei Verwendung von Auto-Init)
console.log(window.noxticaClient);

// Letzter Fehler (falls vorhanden)
console.log(window.noxticaLastError);

Fehlerbehandlung

Häufige Fehler

Fehler manuell behandeln

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Konfigurationsproblem mit dem Site Key
	} else if (error.message.includes('rate')) {
		// Zurückhalten und später erneut versuchen
	}
}

Erfassungsmodi

Das SDK unterstützt drei Erfassungsmodi:

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

Geschützter Modus (KHAN VM)

Das Schwierigste bei der Bot-Abwehr ist, dass alles, was im Browser läuft, grundsätzlich sichtbar und veränderbar ist. Ein entschlossener Angreifer kann den Code der Seite lesen, herausfinden, was gemessen wird, und still gefälschte Antworten zurückliefern.

Die KHAN VM erhöht den Aufwand dafür. Anstatt die Erfassung offen als lesbaren Code auf der Seite laufen zu lassen, führt Noxtica den sensiblen Teil in einer versiegelten, sandbox-basierten Laufzeitumgebung aus. Die Logik, die entscheidet, was gemessen wird, liegt nicht offen für einen Angreifer, und das produzierte Ergebnis wird versiegelt, bevor es den Browser verlässt – es ist damit deutlich schwerer zu manipulieren oder wiederzuverwenden.

Was die KHAN VM bringt:

• Manipulationssichere Ergebnisse – die Bewertung wird innerhalb der Sandbox versiegelt, bevor sie gesendet wird; andere Skripte auf der Seite können sie nicht still verändern oder wiederverwenden.
• Schwerer zu reverse-engineeren – die Erfassungslogik bleibt innerhalb der Laufzeitumgebung verborgen, anstatt in den Entwicklerwerkzeugen des Browsers lesbar zu sein.
• Replay-Schutz – jedes Ergebnis ist einmalig und verifiziert, sodass eine abgefangene Antwort nicht einfach wiederverwendet werden kann, um einen sauberen Besucher vorzutäuschen.

Ehrliche Grenzen – was sie nicht tut:

• Sie ist ein Manipulationsschutz-Feature, keine Ende-zu-Ende-Verschlüsselung.
• Wenn Ihre eigene Seite kompromittiert ist (z. B. durch eine Cross-Site-Scripting-Schwachstelle), kann ein Angreifer auf dieser Seite dieselben rohen Browser-Signale sehen, die Noxtica sieht. Die KHAN VM schützt die Verarbeitung und das Ergebnis, nicht die Seite um sie herum.

Die KHAN VM wird serverseitig aktiviert und erfordert keine Änderungen an Ihrer Integration. Wenn sie nicht starten kann – etwa weil eine Content Security Policy sie blockiert – fällt Noxtica auf eine leichtere Erfassungsvariante zurück, damit die Erkennung weiterhin funktioniert, wenn auch mit schwächerem Manipulationsschutz.

Browser-Unterstützung

Das SDK unterstützt moderne Browser:

In älteren Browsern kann die Signalgenauigkeit reduziert sein, sie funktionieren jedoch weiterhin.

Debug-Modus

Aktivieren Sie das Debug-Logging, um Probleme zu beheben:

// Vor dem Laden des SDK
globalThis.NOXTICA_DEBUG = true;

// Oder pro Client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Oder per Skript-Attribut
<script src="..." data-debug></script>;

Der Debug-Modus protokolliert:

• Erfassungsfortschritt
• Token-Lebenszyklus
• Cache-Treffer und -Fehltreffer
• Aufgetretene Fehler

Hinweis: Der Debug-Modus ist in der Produktion standardmäßig stumm. Es erscheinen keine Konsolenausgaben, sofern er nicht explizit aktiviert wurde.

Speicher-Überlegungen

Browser-Speicher

Das SDK nutzt den lokalen Speicher des Browsers zum Cachen von Ergebnissen. Falls nicht verfügbar (z. B. im privaten Browsermodus oder bei deaktiviertem Speicher):

• Die Erkennung funktioniert weiterhin
• Jeder Seitenaufruf führt eine neue Bewertung durch
• Die tab-übergreifende Koordination kann eingeschränkt sein

Keine Cookies

Das SDK verwendet keine Cookies. Alles, was es benötigt, wird im lokalen Speicher des Browsers gehalten.

Performance-Auswirkung

Erster Besuch

Die Erfassung läuft asynchron und blockiert das Seiten-Rendering nicht.

Nachfolgende Besuche (Cache-Treffer)

Fehlerbehebung

Fingerprint wird nicht erfasst

1. Prüfen Sie die Browser-Konsole auf Fehler
2. Verifizieren Sie, dass der Site Key exakt mit Ihrer Domain übereinstimmt (einschließlich https://)
3. Stellen Sie sicher, dass die Domain im Backoffice aktiviert ist
4. Aktivieren Sie den Debug-Modus, um detaillierte Logs zu sehen

„WebAssembly blocked by Content Security Policy”

Wenn Sie diese Warnung in der Browser-Konsole sehen, blockiert die Content Security Policy Ihrer Seite die manipulationssichere Laufzeitumgebung (die KHAN VM). Die Erkennung funktioniert weiterhin in einem leichteren Modus, aber Sie erhalten den stärksten Schutz, wenn Sie sie zulassen.

Verwenden Sie das folgende Snippet, um Noxtica das Laden und Ausführen zu erlauben:

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

Siehe Erste Schritte → Content Security Policy für die vollständige Referenz.

Unterschiedliche Device-IDs auf demselben Gerät

Das kann vorkommen, wenn:

• Der Browser-Speicher geleert wird
• Das Browser-Profil sich ändert
• Der Besucher den privaten/Inkognito-Modus nutzt
• Der Browser ein größeres Update durchläuft

Das ist erwartetes Verhalten – die Erkennung passt sich an, wenn ein Gerät sich über die Zeit verändert.

Erfassung dauert zu lange

1. Prüfen Sie den Netzwerk-Tab auf langsame API-Antworten
2. Erwägen Sie mode: 'minimal' für schnellere Erfassung
3. Stellen Sie sicher, dass das SDK mit dem Attribut async geladen wird

Events werden nicht ausgelöst

1. Stellen Sie sicher, dass Sie Listener registrieren, bevor das SDK läuft
2. Prüfen Sie, ob die Auto-Init-Attribute korrekt sind
3. Verifizieren Sie, dass keine JavaScript-Fehler die Ausführung blockieren

Best Practices

1. Verwenden Sie data-auto-check-once statt data-auto-collect, um redundante Erfassungen zu minimieren

2. Laden Sie das SDK asynchron mit dem Attribut async, um das Laden der Seite nicht zu blockieren

3. Hören Sie auf Events, anstatt window.noxticaResult per Polling abzufragen

4. Überschreiben Sie die TTL nicht unnötig – das Standardintervall von 7 Tagen ist für die meisten Anwendungsfälle optimiert

5. Behandeln Sie Fehler reibungslos – ein Erfassungsfehler sollte Ihre Seite nicht zum Absturz bringen

Nächste Schritte

• Erste Schritte – Erste Einrichtungsanleitung
• Backend-Integration – Serverseitige Geräteabfragen