Browser-runtime

Deze gids legt uit hoe de Noxtica SDK werkt in de browsers van je bezoekers — wat er gebeurt tijdens een beoordeling, hoe caching alles snel houdt, en hoe je veelvoorkomende problemen oplost.

Hoe het werkt

Wanneer je de Noxtica SDK aan je pagina toevoegt, doet het stil vier dingen:

1. Authenticeren: meldt zich aan met je Site Key via credentials die het voor jou beheert
2. Verzamelen: leest de alledaagse signalen die een browser al blootlegt
3. Indienen: stuurt ze naar Noxtica voor scoring
4. Cachen: slaat het resultaat lokaal op zodat het werk niet bij elk bezoek opnieuw hoeft te worden gedaan

Dit alles draait op de achtergrond en blokkeert je pagina nooit.

Collectieflow

Automatisch (aanbevolen)

Bij gebruik van data-auto-check-once gebruikt de SDK slimme collectie:

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

Gebruik je een content-security-policy? Dan moet je Noxtica toestemming geven om zijn manipulatiebestendige runtime, de KHAN VM, te laden en uit te voeren. Als dat niet lukt, blijft Noxtica werken met een lichtere vorm van collectie en zwakkere manipulatiebeveiliging. Zie Aan de slag → Content Security Policy voor het exacte snippet.

Eerste bezoek: er wordt een volledige beoordeling uitgevoerd en het resultaat wordt gecached.

Volgende bezoeken (binnen het cachevenster): het gecachte resultaat wordt geretourneerd en een lichtgewicht bezoek wordt geregistreerd. Er wordt geen zwaar werk uitgevoerd.

Na het verlopen van het cachevenster: er wordt een nieuwe beoordeling uitgevoerd.

Handmatige controle

Voor programmatische controle gebruik je de methode 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');
}

Cachinggedrag

De SDK cachet elk resultaat in de browser zodat dezelfde bezoeker niet bij elke paginaweergave opnieuw wordt beoordeeld.

Cachesleutel

nox_fp_{your_site_key}

Wat er wordt gecached

• Device ID
• Tijdstempel van laatste indiening
• Tijdstempel van laatste activiteit
• Vorige risicoscore en -niveau

TTL (Time-To-Live)

De standaard cache-TTL is 7 dagen. Dit kan worden geconfigureerd:

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

Cache vernieuwen

Om de cache te omzeilen en een verse fingerprint te verzamelen:

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

Cross-tab-coördinatie

Wanneer een bezoeker meerdere tabbladen van je site tegelijk opent, zorgt de SDK ervoor dat ze slechts één keer worden beoordeeld:

• Slechts één tabblad doet het echte werk
• De andere tabbladen wachten en delen dat resultaat

Dit gebeurt automatisch — geen configuratie nodig.

Events

De SDK verstuurt events waarnaar je kunt luisteren:

noxtica:collected

Wordt geactiveerd na een geslaagde collectie of bij het teruggeven van een gecached resultaat:

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

Wordt specifiek geactiveerd wanneer een gecached resultaat wordt teruggegeven:

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

noxtica:error

Wordt geactiveerd wanneer de collectie mislukt:

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

Globale variabelen

Na de collectie zijn resultaten wereldwijd beschikbaar:

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

Foutafhandeling

Veelvoorkomende fouten

Fouten handmatig afhandelen

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

Collectiemodi

De SDK ondersteunt drie collectiemodi:

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

Beschermde modus (KHAN VM)

Het moeilijkste aan het bestrijden van bots is dat alles wat in een browser draait in principe zichtbaar en bewerkbaar is. Een vastberaden aanvaller kan de code van de pagina lezen, uitzoeken wat er gemeten wordt en stilletjes valse antwoorden terugsturen.

De KHAN VM verhoogt de kosten daarvan. In plaats van de collectie als leesbare code op de pagina open te laten staan, draait Noxtica het gevoelige gedeelte binnen een afgesloten, gesandboxte runtime. De logica die beslist wat er gemeten wordt ligt niet voor iedereen zichtbaar om te bestuderen en te herschrijven, en het resultaat dat het produceert is afgesloten voordat het de browser verlaat — zodat het veel moeilijker te manipuleren of te herspelen is.

Wat de KHAN VM doet:

• Manipulatiebestendige resultaten — de beoordeling is afgesloten binnen de sandbox voordat die wordt verstuurd, zodat andere scripts op de pagina hem niet stilletjes kunnen aanpassen of herspelen.
• Moeilijker te reverse-engineeren — de collectielogica blijft verborgen in de runtime in plaats van leesbaar te zijn in de ontwikkeltools van de browser.
• Hergebruikbeveiliging — elk resultaat is eenmalig en geverifieerd, zodat een vastgelegd antwoord niet simpelweg opnieuw kan worden gebruikt om een schone bezoeker voor te spiegelen.

Eerlijke grenzen — wat het niet doet:

• Het is een manipulatiebestendigheidsfunctie, geen end-to-end-encryptie.
• Als je eigen pagina is gecompromitteerd (bijvoorbeeld door een cross-site scripting-fout), kan een aanvaller op die pagina dezelfde ruwe browsersignalen zien die Noxtica ziet. De KHAN VM beschermt de verwerking en het resultaat, niet de pagina eromheen.

De KHAN VM wordt aan de serverkant ingeschakeld en vereist geen wijzigingen aan je integratie. Als hij niet kan starten — bijvoorbeeld omdat een content-security-policy hem blokkeert — valt Noxtica terug op een lichtere vorm van collectie zodat detectie blijft werken, alleen met zwakkere manipulatiebeveiliging.

Browserondersteuning

De SDK ondersteunt moderne browsers:

Oudere browsers kunnen een verminderde signaalnauwkeurigheid hebben maar blijven functioneren.

Debugmodus

Schakel debug-logging in om problemen op te lossen:

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

Debugmodus logt:

• voortgang van de collectie
• token-levenscyclus
• cache-hits en -misses
• eventuele fouten

Let op: debugmodus is standaard stil in productie. Er verschijnt geen console-uitvoer tenzij deze expliciet is ingeschakeld.

Opslagoverwegingen

Browseropslag

De SDK gebruikt de lokale opslag van de browser om resultaten te cachen. Als die niet beschikbaar is (bijvoorbeeld bij privébrowsen of wanneer opslag is uitgeschakeld):

• Detectie werkt nog steeds
• Elke paginaweergave voert een nieuwe beoordeling uit
• Cross-tab-coördinatie kan verminderd zijn

Geen cookies

De SDK gebruikt geen cookies. Alles wat het nodig heeft wordt bewaard in de lokale opslag van de browser.

Prestatie-impact

Eerste bezoek

De collectie draait asynchroon en blokkeert het renderen van de pagina niet.

Volgende bezoeken (cache hit)

Probleemoplossing

Fingerprint wordt niet verzameld

1. Controleer de browserconsole op fouten
2. Controleer of de Site Key exact overeenkomt met je domein (inclusief https://)
3. Zorg dat het domein is ingeschakeld in de Backoffice
4. Schakel debugmodus in om gedetailleerde logs te zien

”WebAssembly blocked by Content Security Policy”

Als je deze waarschuwing in de browserconsole ziet, blokkeert de content-security-policy van je pagina de manipulatiebestendige runtime (de KHAN VM). Detectie blijft werken in een lichtere modus, maar je krijgt de sterkste beveiliging door het toe te staan.

Gebruik het onderstaande snippet om Noxtica te mogen laden en uitvoeren:

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

Zie Aan de slag → Content Security Policy voor de volledige referentie.

Verschillende device-ID’s op hetzelfde apparaat

Dit kan gebeuren wanneer:

• De opgeslagen browserdata is gewist
• Het browserprofiel is veranderd
• De bezoeker gebruikt privé/incognitomodus
• De browser een ingrijpende update heeft gehad

Dit is verwacht gedrag — de herkenning past zich aan naarmate een apparaat in de loop van de tijd verandert.

Collectie duurt te lang

1. Controleer het netwerktabblad op trage API-responses
2. Overweeg mode: 'minimal' te gebruiken voor snellere collectie
3. Zorg dat de SDK wordt geladen met het attribuut async

Events worden niet geactiveerd

1. Zorg dat je luistert voordat de SDK wordt uitgevoerd
2. Controleer of de auto-init-attributen correct zijn
3. Controleer of er geen JavaScript-fouten zijn die de uitvoering blokkeren

Best practices

1. Gebruik data-auto-check-once in plaats van data-auto-collect om overbodige collecties te minimaliseren

2. Laad de SDK asynchroon met het attribuut async om het laden van pagina’s niet te blokkeren

3. Luister naar events in plaats van window.noxticaResult te pollen

4. Overschrijf de TTL niet onnodig — het standaardinterval van 7 dagen is geoptimaliseerd voor de meeste use-cases

5. Ga netjes om met fouten — een mislukte collectie mag je pagina niet breken

Volgende stappen

• Aan de slag — initiële installatiegids
• Backend-integratie — server-side apparaatopzoekingen