Getting Started

This guide takes you from a Site Key to an observable browser assessment and a server-side decision path. Start in observation mode: confirm collection, review scored and non-scored outcomes, and compare them with your own outcomes before adding friction.

Prerequisites

Before you change your application, have:

a provisioned Noxtica account (request access);
a Site Key for the exact origin you are integrating;
access to the Backoffice to confirm the domain and review results;
a backend API key with the required read scope if your server will make decisions; and
a documented consent or lawful-basis decision for any optional session-replay or behavioral capture you enable.

The browser collector requires JavaScript. If JavaScript is unavailable or blocked, it produces no new assessment; keep your normal application path available and apply the fallback your team chose for that surface.

Quick Integration

Choose one browser setup. The script-tag path is the smallest change; the package API is useful when your application needs typed result handling or framework lifecycle integration.

Automatic Collection (Recommended)

Place the session-replay head helper first in <head>, followed by the asynchronous collector:

<head>
	<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_here"
		data-auto-init
		data-auto-check-once
		async
	></script>
</head>

The first script keeps the earliest page activity available for session replay. It does not transmit that activity by itself. Replay starts only when your tenant policy, browser privacy signals, sampling, and consent or other approved basis allow it; a denied or unavailable replay state is discarded. If you do not use session replay, you may omit the first script. Existing async-only collector installations remain supported, but replay cannot recover activity from before the collector attached.

The integrity value belongs to the exact immutable d9ae068e asset in the snippet. When you upgrade the asset URL, copy its matching SHA-384 value from https://collect.noxtica.com/collector/asset-manifest.json; never combine a new URL with an old integrity value.

The collector then:

assesses on the first eligible visit;
returns a cached result within the configured assessment interval;
records eligible return visits without repeating a full assessment; and
coordinates open tabs so they can share one assessment.

Listen before the asynchronous script finishes so you do not miss the event:

document.addEventListener('noxtica:collected', function (event) {
	const result = event.detail;

	if (typeof result.score === 'number' && result.risk_level) {
		console.log('Scored result:', result.risk_level, result.score);
	} else {
		// Numeric fields can be intentionally suppressed in the browser response.
		console.log('Assessment completed without a browser-visible score:', result.status);
	}

	console.log('Fingerprint ID:', result.fingerprintId);
	console.log('From cache:', Boolean(result.fromCache));
});

document.addEventListener('noxtica:error', function (event) {
	console.error('Collection failed:', event.detail);
});

After collection, the same raw result is available as window.noxticaResult. Prefer events over polling the global.

Strict CSP: nonce variant

If your content-security policy authorizes scripts with a response-specific nonce, apply the same nonce to both public assets. Generate a new unpredictable nonce for every HTTP response and include its value in script-src.

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

Do not load the head helper from another asynchronous script. It must execute before the activity you want replay to include.

Manual Collection

Use the raw browser API when your page already loads the collector and you want to choose the collection moment:

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

	try {
		const result = await client.collectAndSubmit();
		console.log('Fingerprint ID:', result.fingerprintId);

		if (typeof result.score === 'number' && result.risk_level) {
			console.log('Risk:', result.risk_level, result.score);
		} else {
			console.log('Assessment status:', result.status);
		}
	} catch (error) {
		console.error('No fresh assessment is available:', error);
	}
</script>

For a typed package integration:

pnpm add @noxtica/sdk
# or: npm install @noxtica/sdk

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

const noxtica = await init({ siteKey: 'pk_prod_your_site_key_here' });
const verdict = await noxtica.getVerdict();

if (isVerdictScored(verdict)) {
	console.log('Risk:', verdict.riskLevel, verdict.score, verdict.confidence);
} else {
	// Suppressed is unknown risk, not score 0 and not "low".
	console.log('Assessment status:', verdict.status);
}

Smart Collection with `checkOnce()`

checkOnce() respects the configured cache interval. Use it for page-load and route-change checks unless you have a specific reason to request a fresh assessment.

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

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

if (typeof result.score === 'number') {
	console.log('Risk level:', result.risk_level);
} else {
	console.log('No browser-visible numeric score:', result.status);
}

Performance & Site Impact

The full collector is asynchronous, and checkOnce() avoids repeating a full assessment inside its cache window. The optional replay head helper is synchronous because its purpose is to cover the earliest part of the page; omit it when replay is not part of your integration.

Measure the customer-visible impact on your own pages:

Compare page loading with and without the collector in your normal performance tooling.
Confirm the collector script loads asynchronously.
Confirm a repeat visit returns fromCache: true when expected.
Inspect the browser Network panel for blocked, slow, or repeated requests.
Keep production logging quiet and enable targeted diagnostics only while investigating.

A slow or failed collection is not a low-risk result. Keep collection off the critical rendering path, and let your application continue with its documented unavailable-result policy.

Sandbox vs Production

Use the Site Key provisioned for each environment. Do not assume that a development key and a production key share domains, policy, retention, or data views.

Check	Development or staging	Production
Registered origin	Your exact test origin	Your exact public origin
Site Key	Key issued for that environment	Key issued for that environment
Data review	Confirm test traffic is isolated as expected	Confirm production traffic appears in the intended domain view
Policy	Observe and exercise error paths	Promote only the policy your team reviewed

A common pattern chooses the Site Key by hostname while keeping the replay helper static:

<script
	src="https://collect.noxtica.com/collector/noxtica-recorder-head.d9ae068e.js"
	integrity="sha384-0aarRZ9aHZq4csV3R+MzJUTnerNzrddznWNV/KoKPkKp2Qh40kGsrFiPiMAuvmg9"
	crossorigin="anonymous"
></script>
<script>
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const script = document.createElement('script');
	script.src = 'https://collect.noxtica.com/collector/noxtica.js';
	script.async = true;
	script.dataset.siteKey = KEY;
	script.dataset.autoInit = '';
	script.dataset.autoCheckOnce = '';
	document.head.appendChild(script);
</script>

Replace both example keys with keys actually issued to you. If you have only one environment key, request the environment setup you need rather than inventing a prefix.

Tag Manager Compatibility

Google Tag Manager, Adobe Launch, Tealium, Segment, and similar tools can load the asynchronous collector. Use these checks:

Put the replay head helper directly in <head> if you need early replay coverage; a tag manager that starts later cannot recreate earlier activity.
Trigger the collector according to your consent platform. Delayed consent means delayed collection.
Confirm your tag manager preserves data-site-key, data-auto-init, and data-auto-check-once.

If it strips custom attributes, initialize after the collector loads:

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

A constrained container may block part or all of collection. Treat a reduced or failed result as degraded evidence, not as low risk.

Content Security Policy

Allow the collector origin for scripts and API connections. The stronger supported collection profile also requires WebAssembly compilation:

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

If your policy cannot allow 'wasm-unsafe-eval', the collector can continue with a reduced evidence set and reports a warning. Validate that posture with your security team. A fallback assessment has less evidence; it must not be interpreted as a clean result merely because the stronger path was unavailable.

For nonce-based policies, use the nonce example. For pinned assets, keep each URL and integrity value as a published pair.

Site Keys

A Site Key is a public browser identifier tied to a registered origin. It belongs in client HTML; a Server API key does not.

Register the exact scheme, host, and port used by the page.
Use a separate issued key where your environment or data-separation policy requires it.
Never send an sk_... Server API key to the browser.
An origin mismatch or disabled key prevents a valid assessment; it does not mean low risk.

Configuration Options

The package API exposes supported configuration through init():

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

const noxtica = await init({
	siteKey: 'pk_prod_your_site_key_here',
	apiUrl: 'https://collect.noxtica.com',
	mode: 'max', // or 'lite'
	logLevel: 'silent',
});

Use the default apiUrl unless your provisioned deployment specifies another supported HTTPS collector origin.

Initializing the Script with Parameters

Use only the documented script attributes or package options below. Script attributes configure the raw auto-init path; package options are passed through init().

Script attributes (`<script data-*>`)

Attribute	Values	Notes
`data-site-key`	Issued `pk_...` string	Required for auto-init.
`data-auto-init`	Presence-only	Enables auto-init for this tag.
`data-auto-check-once`	Presence-only	Recommended cache-respecting collection.
`data-auto-collect`	Presence-only	Collect on each load; ignored when `data-auto-check-once` is present.
`data-log-level`	`silent`, `error`, `warn`, `info`, `debug`	Highest-precedence SDK diagnostic level.
`data-debug`	Presence-only	Legacy debug toggle; use `data-log-level` for explicit control.
`data-api-url`	HTTPS URL, or localhost for local development	Raw embed only; invalid values fall back to the default collector origin.
`data-check-interval-days`	Positive number	Client cache-interval override.
`data-ttl-seconds`	Positive integer	Per-call override used with `data-auto-check-once`.

Programmatic options (`createClient()` / `@noxtica/sdk`)

Option	Supported use
`siteKey`	Issued browser Site Key.
`apiUrl`	Supported HTTPS collector origin.
`mode`	Package contract: `'max'` (default) or `'lite'`.
`checkIntervalDays`	Client cache-interval override.
`signatureMode`	`'require'` (default), `'warn'`, or `'disabled'`; change only after a security review.
`accountId`	Optional account association; do not put sensitive data in this field.
`debug` / `logLevel`	SDK diagnostics.
`onChallenge` / `onBlock`	Host callbacks for supported policy directives.
`scriptUrl` / `pinnedLoader`	Package-only asset pinning for deployments given a supported URL and integrity value.

Precedence for `data-log-level` / `logLevel`

Highest wins: data-log-level on the script, then the programmatic logLevel, then the Domain setting in Backoffice, then the SDK default. An absent or invalid value falls through. The legacy debug or data-debug toggle applies only when no explicit level overrides it.

Recipe: silent in production, verbose in staging

<script
	src="https://collect.noxtica.com/collector/noxtica-recorder-head.d9ae068e.js"
	integrity="sha384-0aarRZ9aHZq4csV3R+MzJUTnerNzrddznWNV/KoKPkKp2Qh40kGsrFiPiMAuvmg9"
	crossorigin="anonymous"
></script>
<script>
	const isProd = location.hostname === 'www.example.com';
	const script = document.createElement('script');
	script.src = 'https://collect.noxtica.com/collector/noxtica.js';
	script.async = true;
	script.dataset.siteKey = isProd ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	script.dataset.autoInit = '';
	script.dataset.autoCheckOnce = '';
	script.dataset.logLevel = isProd ? 'silent' : 'debug';
	document.head.appendChild(script);
</script>

CSP and SRI

Use the policy under Content Security Policy. If you pin an asset, update its URL and SRI hash together and verify the pair from the published manifest supplied for your deployment.

Framework examples

Install @noxtica/sdk before using a framework wrapper.

Plain HTML:

<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
	data-log-level="silent"
	async
></script>

React (@noxtica/sdk/react):

import { NoxticaProvider } from '@noxtica/sdk/react';

<NoxticaProvider siteKey="pk_prod_your_site_key_here" logLevel="silent">
	<App />
</NoxticaProvider>;

Next.js (@noxtica/sdk/next):

import { NoxticaScript } from '@noxtica/sdk/next';

<NoxticaScript siteKey="pk_prod_your_site_key_here" logLevel="silent" />;

Vue (@noxtica/sdk/vue):

import { createNoxtica } from '@noxtica/sdk/vue';

app.use(createNoxtica({ siteKey: 'pk_prod_your_site_key_here', logLevel: 'silent' }));

Collection Modes

Mode	Customer-visible behavior	Use when
`max`	Requests the full supported evidence set for the current tenant and browser.	Default; use for evaluated production integrations.
`lite`	Requests a reduced evidence set.	Use only when the lower collection cost matches your risk policy.

Browser support, tenant policy, consent, and feature eligibility still determine what can run. A reduced or unavailable signal is not evidence that the session is safe.

Response Format

A scored raw collector response includes fields such as:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"fromCache": false
}

A browser response may intentionally suppress numeric verdict fields:

{
	"success": true,
	"fingerprintId": "abc123...",
	"status": "evaluated"
}

Treat these as different states:

Scored: score, risk level, and confidence are present.
Suppressed: collection completed, but browser-visible numeric fields are absent. Risk is unknown in browser code; use the authenticated backend lookup.
Error or unavailable: the promise rejects or noxtica:error fires. No fresh result exists; apply your documented fallback.
Cached: fromCache is true. This describes freshness, not risk.

Never coerce an absent score to 0 or map suppressed, unavailable, or error states to low.

Risk Levels

Score	Level	Operational interpretation
0–19	`minimal`	Little risk evidence in this assessment.
20–39	`low`	Limited risk evidence.
40–59	`medium`	Review or observe according to the surface.
60–79	`high`	Consider step-up verification when confidence and context support it.
80–100	`critical`	Reserve stronger action for policy-reviewed, high-confidence cases.

A tier is evidence for your policy, not a complete business decision. Combine it with confidence, the protected action, and your own account or transaction context.

Authentication

The browser uses the public Site Key. Your backend uses a separately issued secret API key and keeps it server-side. The browser SDK manages its own collection requests; do not copy browser credentials, signed results, or secret keys into logs.

Onboarding Process

Request access and agree the deployment and eligible capabilities.
Register each exact origin in Backoffice.
Copy the issued Site Key into one supported browser installation.
Confirm a scored, suppressed, and error path in your test environment.
Create a scoped Server API key and implement the backend lookup.
Review browser, server, and operator-console outputs together.
Run your policy in observation mode before enabling challenge or block behavior.

Managing Multiple Domains

Each registered domain has its own Site Key and domain-level view. Use the domain controls available to your account to separate environments and policies. When a hostname changes, register it before traffic moves; an unregistered origin yields an integration error, not a low-risk result.

SDK Version

For a script-tag deployment, use the current public loader URL or an immutable URL-and-integrity pair supplied for your deployment. For a package deployment, use the version installed from @noxtica/sdk and its exported types as the contract. Do not mix examples from different loader and package releases without checking compatibility.

Release compatibility

Older examples may use different key placeholders, collection-mode names, or browser result casing. For a new integration, follow this page: raw collector responses use risk_level, while @noxtica/sdk normalizes it to riskLevel. Build policy only on documented fields and tolerate additive response fields.

Behavioral Biometrics (Optional, Opt-In)

Behavioral biometrics is separate from the base device assessment and session replay. Enable it only if the capability is included in your account and your privacy or legal review approves the purpose, disclosure, retention, and consent flow.

Before enabling it:

confirm capability eligibility and settings in Backoffice;
document the customer journey in which it will run;
collect an explicit consent decision where required by your policy;
verify denial leaves the base experience usable; and
review the resulting output in observation mode before using it in a decision.

Do not infer consent from a Site Key, page load, or low-risk result.

Next Steps

Follow Backend Integration to keep secret credentials and policy decisions on your server.
Use Browser Runtime for lifecycle, replay-consent, and troubleshooting details.
Review the Integration Flow from collection through evaluation-before-enforcement.
Browse the Features Reference for customer-visible capabilities and operator outputs.
Open the Backoffice to confirm your own domain’s data and policy state.

Getting Started

Prerequisites

Quick Integration

Automatic Collection (Recommended)

Strict CSP: nonce variant

Manual Collection

Smart Collection with checkOnce()

Performance & Site Impact

Sandbox vs Production

Tag Manager Compatibility

Content Security Policy

Site Keys

Configuration Options

Initializing the Script with Parameters

Script attributes (<script data-*>)

Programmatic options (createClient() / @noxtica/sdk)

Precedence for data-log-level / logLevel

Recipe: silent in production, verbose in staging

CSP and SRI

Framework examples

Collection Modes

Response Format

Risk Levels

Authentication

Onboarding Process

Managing Multiple Domains

SDK Version

Release compatibility

Behavioral Biometrics (Optional, Opt-In)

Next Steps

Smart Collection with `checkOnce()`

Script attributes (`<script data-*>`)

Programmatic options (`createClient()` / `@noxtica/sdk`)

Precedence for `data-log-level` / `logLevel`