Browser Runtime

Use this guide after installing the collector. It explains what your application can observe, how to avoid duplicate work, how optional session replay follows consent, and how to keep collection failures separate from low risk.

How It Works

A normal browser assessment has four customer-visible stages:

Initialize: the collector validates the Site Key against the page origin and loads the policy available to that domain.
Collect: the browser supplies the evidence available under its capabilities, privacy signals, tenant policy, and consent state.
Submit: the collector sends the assessment to the configured collector origin and returns a result.
Cache: checkOnce() can reuse the result inside the configured interval instead of repeating a full assessment.

The collector runs asynchronously. Your page must remain usable while it loads, while evidence is reduced, and when collection cannot run. JavaScript-disabled visitors produce no new browser assessment.

Collection Flow

Automatic (Recommended)

Use the synchronous replay head helper before the asynchronous collector when your eligible integration includes session replay:

<script
	src="https://collect.noxtica.com/collector/noxtica-recorder-head.d9ae068e.js"
	integrity="sha384-0aarRZ9aHZq4csV3R+MzJUTnerNzrddznWNV/KoKPkKp2Qh40kGsrFiPiMAuvmg9"
	crossorigin="anonymous"
></script>
<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>

The first script must be the first executable script in <head> and must not be async or defer. It keeps early activity local until the full replay policy and consent path decides whether replay may start. Denial or an unavailable replay policy does not start replay. Sites without replay may omit it.

See Getting Started for SRI upgrades, nonce-based CSP, package installation, and tag-manager caveats.

First eligible visit: checkOnce() requests an assessment and stores the returned state.

Visit inside the cache window: it returns cached state and can record an eligible visit without repeating the full assessment.

After expiry or an explicit refresh: it requests a fresh assessment.

Manual Control

Use the package API when you want typed result handling:

import { init, isVerdictScored } from '@noxtica/sdk';

const client = await init({ siteKey: 'pk_prod_your_site_key' });
const verdict = await client.getVerdict();

if (isVerdictScored(verdict)) {
	console.log('Scored:', verdict.riskLevel, verdict.score, verdict.confidence);
} else {
	console.log('Completed without a browser-visible score:', verdict.status);
}

getVerdict() respects the cache by default. Pass { force: true } only when your application genuinely needs a fresh assessment.

Caching Behavior

The cache reduces repeated work; it is not an authorization decision. A cached result can be scored or suppressed, and fromCache describes freshness rather than risk.

Cache Key

Do not read, write, or version the collector’s browser-storage key from application code. It is not a public integration contract. Use checkOnce(), getVerdict(), fromCache, and the documented clear or refresh operations instead.

What’s Cached

The SDK may retain enough browser state to identify the prior assessment, report when it was submitted or seen, and return the prior browser-visible result. The exact storage shape can change without changing the public API.

Never copy the cache into a URL, analytics property, or client log. Store the returned fingerprintId on your server only when your workflow needs an authenticated lookup.

TTL (Time-To-Live)

Prefer the domain policy or client default. For the raw collector, you can override a single checkOnce() call:

const result = await client.checkOnce({
	ttlSeconds: 86400,
});

For @noxtica/sdk, use the same per-call unit:

const verdict = await client.getVerdict({ ttlSeconds: 86400 });

Use a shorter interval only after measuring the extra browser work and request volume it creates.

Force Refresh

Raw collector:

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

Package API:

const verdict = await client.getVerdict({ force: true });

A refresh can still return a suppressed result or fail. Fresh does not mean low risk.

Cross-Tab Coordination

The collector coordinates same-site tabs so one tab can perform the assessment while others use its result. Your code should still tolerate a tab closing, storage being unavailable, or a competing tab timing out. Listen for completion and error events instead of assuming a fixed delay.

Events

`noxtica:collected`

Fires after collection or a cache hit:

document.addEventListener('noxtica:collected', (event) => {
	const result = event.detail;
	console.log('Fingerprint ID:', result.fingerprintId);
	console.log('From cache:', Boolean(result.fromCache));

	if (typeof result.score === 'number' && result.risk_level) {
		console.log('Risk:', result.risk_level, result.score);
	} else {
		console.log('Assessment status:', result.status);
	}
});

`noxtica:cache-hit`

Fires when checkOnce() returns cached state:

document.addEventListener('noxtica:cache-hit', (event) => {
	console.log('Cache hit:', event.detail.fromCache);
	console.log('Next collection in:', event.detail.nextSubmitIn, 'days');
});

`noxtica:error`

Fires when auto-init collection fails:

document.addEventListener('noxtica:error', (event) => {
	console.error('Source:', event.detail.source);
	console.error('Message:', event.detail.message);
});

An error event means no fresh assessment is available. It must not be normalized to { score: 0 }, minimal, or low.

Global Variables

The raw auto-init path exposes:

console.log(window.noxticaResult); // Last browser-visible result, after completion
console.log(window.noxticaClient); // Auto-initialized raw client
console.log(window.noxticaLastError); // Last reported collection error, if present

Globals are useful for interactive diagnostics. Application code should prefer events or the typed package API so loading, scored, suppressed, and error states stay explicit.

Error Handling

Common Errors

Observed state	Likely cause	What to do
`origin_mismatch`	The page origin is not registered for the Site Key.	Compare scheme, host, and port with the Backoffice domain.
`invalid_site_key`	The key is wrong, disabled, or not available to this origin.	Copy the issued key again and confirm the domain is enabled.
HTTP `429`	Collection frequency exceeded the applicable limit.	Stop forcing refreshes and honor any retry guidance.
Script or API network error	CSP, DNS, network policy, or collector availability.	Inspect Network and CSP reports; follow your unavailable-result policy.
Completed without `score`	Browser verdict suppression, not transport failure.	Use `status` and the authenticated server lookup; do not treat as low.

Handling Errors Manually

try {
	const result = await client.collectAndSubmit();
	if (typeof result.score !== 'number') {
		return { state: 'suppressed', fingerprintId: result.fingerprintId, status: result.status };
	}
	return { state: 'scored', result };
} catch (error) {
	return { state: 'unavailable', error };
}

Keep suppressed and unavailable separate. Suppressed means the assessment completed but the browser was not given numeric verdict fields. Unavailable means your code did not obtain a fresh result.

Collection Modes

The supported @noxtica/sdk collection modes are:

Mode	Observable effect	When to use
`max`	Requests the full supported evidence set for the tenant and browser.	Default for an evaluated integration.
`lite`	Requests a reduced evidence set.	When your reviewed risk and performance policy calls for it.

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

Availability still depends on browser capabilities, CSP, privacy signals, consent, and tenant eligibility. Mode selection does not turn unavailable evidence into a clean signal.

Protected Mode (Sealed Runtime)

Some eligible tenant policies request a stronger, tamper-resistant assessment path. The collector negotiates and runs the supported path without requiring your application to select an implementation or inspect internal runtime state.

Customer-visible behavior is what your integration should depend on:

a scored result includes risk level, score, and confidence;
a suppressed browser result omits those numeric fields and includes a coarse status;
a reduced path can continue with less evidence when browser policy prevents the stronger path; and
a startup or transport failure is reported as an error.

Keep your CSP aligned with Getting Started. Do not branch business logic on undocumented runtime names, files, or console messages.

Browser Support

The collector targets current, supported releases of major Chromium, Firefox, and Safari-based browsers. Browser capability and policy vary even within the same family, especially in private mode, embedded frames, hardened profiles, and enterprise-managed devices.

Build for capability outcomes rather than user-agent versions:

Full evidence: all eligible checks used by the current policy were available.
Reduced evidence: collection completed with some browser capabilities unavailable.
Suppressed result: assessment completed but browser-visible numeric fields were withheld.
Error: no fresh browser result was obtained.

Test the actual browser versions in your customer support matrix. Do not auto-block an older or privacy-focused browser solely because evidence is reduced.

Debug Mode

Enable diagnostics only while investigating:

// Before the raw collector loads
self.NOXTICA_DEBUG = true;

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

Prefer a bounded log level for normal environments.

Log Levels (`logLevel` / `data-log-level`)

The levels are silent, error, warn, info, and debug.

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

client.setLogLevel('debug');
console.log(client.getLogLevel());

For auto-init, data-log-level on the script has the highest precedence. Programmatic logLevel comes next, then the Domain setting, then the SDK default. An invalid value falls through instead of stopping collection.

SDK diagnostics and optional session-replay capture of your host page’s console are separate controls. Turning SDK logs to silent does not itself authorize or disable replay capture.

Session Replay and Diagnostics

Session replay is optional and eligibility-dependent. It must remain separate from the base risk-result state and from your site’s consent decision.

With @noxtica/sdk, connect your consent platform only after it has resolved the visitor’s choice:

const client = await init({ siteKey: 'pk_prod_your_site_key' });

// Call from your consent platform's resolved callback, not speculatively.
client.setReplayConsent(userAcceptedReplay);

console.log('Replay consent:', client.getReplayConsentState());
console.log('Replay recorder:', client.getReplayRecorderState());

Useful customer-visible states include:

AWAITING_CONSENT: replay is eligible but waiting for your explicit decision;
POLICY_READY: the policy and consent decision admit replay;
DISABLED or DENIED: replay will not start for this client state; and
recorder error: replay did not start successfully, which does not turn the risk verdict into low risk.

Use replay to investigate the customer journey around a flagged or failed operation, then compare it with the server lookup and operator-console record. Do not place secrets, payment data, authentication tokens, or sensitive form values in replay-visible surfaces.

Storage Considerations

Browser Storage

The collector uses browser storage for cache and coordination when available. If storage is unavailable or cleared:

collection can still run;
more visits may require fresh assessment;
cross-tab coordination can be reduced; and
a device identifier may change.

Your application must not depend on browser storage persistence for authentication or account identity.

No Cookies

The collector does not require your application to set a Noxtica cookie for the cache described here. Your own session and consent cookies remain governed by your application and policy.

Performance Impact

First Visit

A first eligible visit can include loader, policy, collection, and submission work. The mix depends on browser capability and tenant policy, so measure the stages on your traffic rather than relying on a fixed universal duration.

Keep the collector asynchronous and keep your page’s primary action functional while the assessment is loading.

Subsequent Visits (Cache Hit)

A cache hit avoids a full assessment and exposes fromCache: true. Confirm this in the event payload or typed verdict and in the browser Network panel. Repeated full submissions usually indicate an expired override, forced refresh, unavailable storage, or a key/origin mismatch.

Bundle and runtime specifics

Treat the public asset URL, SRI value, package exports, and result fields as contract. Asset byte size and the mix of browser work can change between releases. Measure the exact asset you deploy and pin URL plus integrity together if your deployment requires immutability.

Automation detection

Automation evidence contributes to the authenticated risk assessment. Your browser code receives a coarse scored or suppressed result; detailed review belongs in server-side and operator views. This separation lets your application act without exposing detector-specific feedback to the browser.

Troubleshooting

Fingerprint Not Collected

Confirm JavaScript is running and the collector request appears in Network.
Confirm the exact origin is registered for the Site Key.
Confirm data-auto-init and either data-auto-check-once or data-auto-collect are present.
Register listeners before the async script executes.
Check CSP reports for blocked script, connection, or WebAssembly execution.
Enable warn or debug temporarily and capture the request ID or error message.

Tamper-resistant runtime blocked by Content Security Policy

If CSP prevents the stronger assessment path, the collector can continue with reduced evidence and logs a warning. Allow the documented origins and WebAssembly policy when your security review permits it:

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

See Getting Started → Content Security Policy. Reduced evidence is not a low-risk verdict; review confidence and use your fallback policy.

Different Device IDs on Same Device

Browser storage clearing, private mode, profile changes, or browser updates can produce a different identifier. Treat fingerprintId as an assessment lookup key, not a permanent person identifier or authentication factor.

Collection Taking Too Long

Compare loader, policy, collection, and submission timing in Network and your own performance trace.
Remove unnecessary forced refreshes and confirm cache hits.
Keep the loader asynchronous.
Test whether CSP or enterprise browser controls are repeatedly forcing a reduced path.
If the request exceeds your application deadline, classify it as unavailable and continue with the fallback chosen for that operation.

Events Not Firing

Register listeners before the SDK runs.
Confirm the auto-init attributes are present and correctly spelled.
Check for earlier JavaScript errors.
Inspect window.noxticaResult and window.noxticaLastError interactively.
For a package integration, await init() and getVerdict() rather than waiting for raw document events.

Best Practices

Use data-auto-check-once or cache-respecting getVerdict() for normal traffic.
Keep the collector off your page’s critical rendering and primary-action path.
Model loading, scored, suppressed, cached, reduced, and unavailable states explicitly.
Never coerce an absent score to zero or label an error as low risk.
Keep Server API keys and detailed decisions on your backend.
Connect replay to an explicit consent or approved-basis decision and verify denial.
Evaluate policies in observation mode before enabling customer-facing enforcement.

Next Steps

Getting Started — installation and supported parameters.
Backend Integration — authenticated device lookups and server policy.
Integration Flow — observe, compare, then enforce.
Features Reference — customer-visible capabilities and operator outputs.

Browser Runtime

How It Works

Collection Flow

Automatic (Recommended)

Manual Control

Caching Behavior

Cache Key

What’s Cached

TTL (Time-To-Live)

Force Refresh

Cross-Tab Coordination

Events

noxtica:collected

noxtica:cache-hit

noxtica:error

Global Variables

Error Handling

Common Errors

Handling Errors Manually

Collection Modes

Protected Mode (Sealed Runtime)

Browser Support

Debug Mode

Log Levels (logLevel / data-log-level)

Session Replay and Diagnostics

Storage Considerations

Browser Storage

No Cookies

Performance Impact

First Visit

Subsequent Visits (Cache Hit)

Bundle and runtime specifics

Automation detection

Troubleshooting

Fingerprint Not Collected

Tamper-resistant runtime blocked by Content Security Policy

Different Device IDs on Same Device

Collection Taking Too Long

Events Not Firing

Best Practices

Next Steps

`noxtica:collected`

`noxtica:cache-hit`

`noxtica:error`

Log Levels (`logLevel` / `data-log-level`)