Prepare a session

The application SDK starts a browser measurement while a visitor uses your site. Your server stores the verified record so later actions can reuse it. Existing authenticated sessions and new arrivals use the same integration. Start with the Next.js and PostgreSQL example, or connect the server adapter to another Node application.

Initialize once

import { createHeretic } from '@heretic-hq/integration/browser';

const client = createHeretic({
  endpoint: '/api/heretic',
  language: 'auto',
  onState: (state) => updateVerificationStatus(state),
});

Mount the client in your application’s shared layout. Preparation begins automatically and never opens a phone ceremony. It returns an authentic record even when the probe is contradicted; your backend evaluates that record when an action requires it. For a page without a bundler, use the same module:

import { createHeretic } from 'https://heretic.tech/integration/0.1.3/browser.js';
const client = createHeretic({ endpoint: '/api/heretic' });

Reuse and refresh

await client.prepare() joins a running measurement or reuses a valid record held by your server. Page reloads and other tabs can reuse the record. Browser Web Locks coordinate simultaneous preparation where supported; server verification is required in every browser. await client.status() reads readiness without starting a probe. Call it after sign-in, sign-out or an account switch. A ready measurement is separate from the account’s permission to perform an action. A valid record remains usable when a refresh starts. During recent visible activity, the SDK checks whether it is nearing expiry and refreshes as needed. It does not keep measuring an idle page indefinitely. The server refuses expired evidence and records bound to another application session. The measurement nonce is captured when the sensor session opens. Address comparison is an optional customer rule, because the application and sensor may observe different IP families. To start only when explicitly requested, set background: false. To dispose the client and stop local work, call client.destroy().

Existing authenticated sessions

Install preparation in the shared layout before requiring it on an action. Returning users can accumulate measurements during ordinary use. A visitor with a valid login cookie but no Heretic record still needs a measurement; authentication alone does not supply it. A user may reach the protected action before measurement finishes. The SDK displays waiting UI and joins the existing check. If a required measurement cannot complete, the action stays uncompleted. No percentage of ready visitors or fixed residual wait is assumed.

Content security policy

Allow https://heretic.tech in frame-src and style-src. A CDN module also needs that origin in script-src. The phone ceremony loader uses https://heretic.tech/guard.js and /guard.css. The parent page must allow the required frame features: accelerometer, gyroscope, magnetometer and public-key credential creation/get. A parent policy disabling them also disables them inside a nested ceremony. The SDK supplies the iframe allow attributes; it cannot override a restrictive parent header. Keep the measurement frame rendered. The SDK makes it visually unobtrusive at one pixel; display: none can stop animation-frame measurements.

Diagnose preparation

const diagnostic = await client.diagnostics();

This returns server readiness, evidence expiry, whether a measurement is running, and the last local error. It does not expose the signed token or device identifiers. Verify a complete browser run after heretic-check passes on the server; server configuration checks alone cannot establish that the browser’s CSP and cookie transport work.

Get started

Application integration

Collector

Challenge widget

Clearance

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Prepare a session

Initialize once

Reuse and refresh

Existing authenticated sessions

Content security policy

Diagnose preparation

​Initialize once

​Reuse and refresh

​Existing authenticated sessions

​Content security policy

​Diagnose preparation

Initialize once

Reuse and refresh

Existing authenticated sessions

Content security policy

Diagnose preparation