Integration Flow

A production integration is not just “script in, block out.” It is an evidence path with explicit states: collect in the browser, keep the authoritative read on the server, review the score with confidence and context, then apply a policy your team has evaluated.

The four nodes are Browser, Result, Score, and Decision. Each node has an observable output and a failure state that must not be confused with low risk.

01. Browser

Add one supported browser integration, keep it asynchronous, and preserve the customer journey when JavaScript or collection is unavailable.

The browser collector requests the evidence available under the current browser, domain policy, privacy signals, and consent state. It submits to the configured collector origin and returns either a scored browser result, a deliberately suppressed browser result, or an error.

What the script does

• Starts collection through data-auto-check-once, the raw client API, or @noxtica/sdk.
• Returns a fingerprintId that your application can send to its own backend.
• Reuses cached assessment state within the configured interval.
• Emits completion, cache-hit, and error events for the raw auto-init path.
• Starts optional session replay only when that capability is eligible and your policy and consent path admit it.

What the script does NOT do

• It does not make your final signup, payment, or access decision.
• It does not turn a missing signal, suppressed score, or network failure into low risk.
• It does not make fingerprintId an identity credential.
• It does not make session-replay consent implicit in collection.
• It cannot produce a new assessment when JavaScript is disabled or the collector is blocked.

Output to verify: a completion or error state, a fingerprintId when collection succeeds, and fromCache when the returned state was reused.

02. Result

Treat the browser result as an integration handoff, not as the only source of truth for a high-impact action.

A raw collector result can have one of these shapes:

function classifyBrowserResult(result) {
	if (typeof result?.score === 'number' && result.risk_level && typeof result.confidence === 'number') {
		return { state: 'scored', result };
	}

	if (result?.success && result?.status) {
		return {
			state: 'suppressed',
			fingerprintId: result.fingerprintId,
			status: result.status,
		};
	}

	return { state: 'unavailable' };
}

What it is

• Scored: numeric score, risk level, and confidence are present.
• Suppressed: the assessment completed but browser-visible numeric verdict fields are absent. The coarse status is not a low-risk score.
• Cached: fromCache describes freshness and can apply to the browser-visible state returned by checkOnce().
• Error or unavailable: collection rejected, timed out, was blocked, or returned no usable state. No fresh result exists.

For a trusted application decision, send fingerprintId to your backend and read the device record with GET /v1/device/:deviceId and a server-held API key. Keep the business request and the lookup in the same tenant and environment boundary.

Why a sealed result instead of a session lookup

The browser and server surfaces protect the handoff so application code can detect invalid or unavailable outcomes instead of trusting arbitrary client values. As an integrator, depend on the documented result fields and authenticated lookup—not internal payload layout, signing keys, runtime files, or implementation-specific console messages.

The operational benefit is separation of duties: the browser collects, your backend reads the tenant-scoped record, and your policy owns the customer action.

03. Score

Read score, tier, confidence, and available reasons together. A score summarizes evidence; it does not replace business context.

The authenticated device lookup can return:

• score from 0 to 100;
• riskLevel: minimal, low, medium, high, or critical;
• confidence for that assessment;
• server-visible flags and published reason codes when available;
• optional category detail when available; and
• first-seen, last-submitted, and last-seen timestamps.

The browser response may expose less detail by design. Use the authenticated server record and operator console for investigation rather than adding detector-specific feedback to client code.

Categories that feed the score

Customer-visible evidence can cover automation, browser consistency, infrastructure context, privacy-browser handling, device capability, and behavioral anomalies. Availability varies by browser, tenant capability, consent, and current policy.

Use Detection Signals to understand the public categories and Features Reference to understand the operator-facing output. Do not build application policy on undocumented detector names or internal weights.

Speed

Keep Noxtica outside your page-rendering and primary-action critical path. Use cache-respecting collection in the browser, set an application deadline for the server lookup, and measure the actual latency of the deployment you use.

If the lookup misses its deadline or returns an error, the state is unavailable. Apply the fallback chosen for that business operation; do not substitute minimal, low, or score 0.

04. Decision

Your server turns a risk read into a business action. Your operators review what happened and adjust the policy deliberately.

A decision should combine:

• the scored device record, when present;
• confidence and available reasons;
• the protected operation;
• account, authentication, transaction, and abuse context your application already owns; and
• explicit handling for suppressed, missing, malformed, and unavailable results.

A canonical four-action policy

A useful starting vocabulary is:

• Allow: continue when the scored evidence and your other controls support it.
• Observe: continue while recording the proposed policy outcome for later comparison.
• Step up: request additional verification when evidence is elevated, unknown, or unavailable for a sensitive action.
• Block: reserve for the clearest, policy-reviewed cases where your evidence and business rules support denial.

Do not map tiers mechanically to actions across every route. A read-only page, signup, password reset, and high-value transaction have different costs of false acceptance and false rejection.

Where the decision lives

• The browser reports collection state and a lookup identifier.
• Your backend performs the authenticated read and computes the business action.
• Backoffice provides the device, event, visit, and policy views available to your account.
• Session replay, when eligible and admitted, helps investigate the customer journey around an operation; it is not itself a risk tier.
• Your application audit trail should record the input state, proposed action, final action, and outcome without logging secrets or sensitive replay data.

Evaluate Before You Enforce

Use this rollout sequence for every customer-facing policy:

1. Instrument: confirm scored, suppressed, missing, rate-limited, and unavailable paths in a non-production environment.
2. Observe: calculate the action you would take, but do not change the customer experience.
3. Label outcomes: join the proposed action with your own confirmed success, abuse, chargeback, account-recovery, or review outcome.
4. Segment: compare results by protected route, browser family, geography relevant to your business, and customer cohort. Look for concentrated false positives.
5. Tune: choose thresholds and confidence requirements per surface. Define the fallback for unknown and unavailable states separately.
6. Step up first: introduce reversible additional verification before hard denial where the customer cost warrants it.
7. Enforce gradually: promote only the policy you reviewed, keep an owner and rollback path, and continue monitoring outcomes.

The Browser Security concept describes observation mode and operator-controlled enforcement. The Backend Integration example shows how to keep transport and risk states separate in code.

End-to-end timing

There are two paths to measure:

1. Browser path: loader, policy, collection, submission, and cache behavior.
2. Server path: your request handling, authenticated device lookup, and policy evaluation.

Measure both on your traffic. Do not promise that collection or lookup will always finish before a customer action. Set deadlines and test the fallback for JavaScript disabled, blocked collection, no identifier, 404, 429, and 5xx outcomes.

Technical reference

This reference lists the public contract an integrator can safely depend on. Implementation details can change without changing these behaviors.

01. Browser — what’s collected

The collector uses the supported evidence available in the current browser and policy. It loads asynchronously, can reuse cache state, and reports collection errors. Optional behavioral or replay capture has separate eligibility and consent requirements.

Observable fields for the raw auto-init path include fingerprintId, optional score, optional risk_level, optional confidence, optional status, and fromCache. The typed package normalizes risk_level to riskLevel.

02. Token — the sealed result

The public SDK protects result integrity and manages the browser-side exchange. Integrators should:

• keep the default required verification posture unless a security review approves otherwise;
• treat verification or transport failure as unavailable;
• send fingerprintId, not a secret API key, from browser to backend; and
• keep sk_... API keys on the server.

Do not pin undocumented key identifiers or parse an internal token layout. Use the SDK result and authenticated Server API.

03. Score — verification latency

GET /v1/device/:deviceId returns the current tenant-scoped device record when found. The response includes a risk tier, numeric score, and confidence for a scored record, with optional explanation fields. 404 means unknown in the current tenant and retention window; 401, 403, 429, and 5xx are configuration, capacity, or availability states—not low risk.

04. Decision — what your code reads

Your policy should accept a discriminated input such as:

{ state: 'scored', score, riskLevel, confidence }
{ state: 'suppressed', fingerprintId, status }
{ state: 'unknown', reason: 'device_not_found' }
{ state: 'unavailable', reason: 'timeout_or_error' }

Only the first shape belongs in a numeric threshold comparison. The other shapes need explicit policies and must never be coerced to score 0.

Related reading

• Getting Started — supported script and package installation.
• Browser Runtime — cache, events, replay consent, result states, and troubleshooting.
• Backend Integration — the authenticated lookup and safe policy example.
• Detection Signals — public evidence categories.
• Features Reference — customer operations and capability outputs.
• Browser Security — observe-first, operator-controlled enforcement.