Preverus SDK

Typed browser SDK for basic device fingerprinting, visitor resolution, event tracking, and risk evaluation.

Preverus supports two browser integration styles:

• NPM SDK for JavaScript applications.
• Hosted universal script for Laravel, PHP, Rails, Django, WordPress, static HTML, and other sites without a frontend build step.

Install

npm install @preverus/sdk

Free Basic Fingerprint

No account, API key, or agent URL is required for basic local fingerprinting.

import { createPreverus } from "@preverus/sdk";

const preverus = createPreverus();
const fingerprint = await preverus.fingerprint.get();

This mode runs locally in the browser and does not send network requests to Preverus.

Hosted script equivalent:

<script src="https://cdn.preverus.com/v1/preverus.js"></script>
<script>
  window.Preverus.getContext().then((context) => {
    console.log(context.fingerprint);
  });
</script>

Free mode does not resolve visitors, send events, evaluate risk, or use global intelligence. Create browser and server keys when you need hosted platform features.

Hosted Universal Script

Use the hosted script when the site is not built with npm or when you want a drop-in integration for server-rendered pages.

<script
  src="https://cdn.preverus.com/v1/preverus.js"
  data-preverus-key="pk_live_xxx"
  data-preverus-auto="true"
></script>

The hosted script is served by Preverus as preverus.js. Internally, the SDK source calls this entrypoint snippet because it is the script-tag wrapper build. Customers should think of it as the hosted Preverus browser script, not a separate SDK.

The hosted script is a thin public bootstrap around the SDK. It does not bundle the protected collector agent. With a browser key, the SDK still loads the latest Preverus-hosted obfuscated agent through the manifest and uses the same visitor resolution, event, storage, consent, route alias, and transport behavior as the npm SDK.

When platform mode is enabled, getContext() creates a browser_session event by sending the full collected feature vector to Preverus. That event populates visitors/devices in the console and returns a short-lived riskSessionToken for backend decisions.

Available global API:

<script>
  (async () => {
    await window.Preverus.ready();

    const context = await window.Preverus.getContext();
    console.log(context.riskSessionToken);

    await window.Preverus.track("signup", {
      userId: "acct_42",
      email: "[email protected]",
    });
  })();
</script>

getContext() returns:

{
  "fingerprint": "fp_hash",
  "visitorId": "v_abc123",
  "riskSessionToken": "signed_token",
  "riskSessionExpiresAt": "2026-07-10T12:05:00Z",
  "browserSessionEventId": "evt_123",
  "hasPlatformAccess": true,
  "consentGranted": true
}

Form Integration

For server-rendered forms, enable auto instrumentation and optionally mark the fraud-relevant action.

<script
  src="https://cdn.preverus.com/v1/preverus.js"
  data-preverus-key="pk_live_xxx"
  data-preverus-auto="true"
></script>

<form method="POST" action="/register" data-preverus-action="signup">
  <input name="email" type="email" />
  <button type="submit">Create account</button>
</form>

Before submit, the script attaches:

<input type="hidden" name="preverus_fingerprint" />
<input type="hidden" name="preverus_visitor_id" />
<input type="hidden" name="preverus_risk_session_token" />
<input type="hidden" name="preverus_browser_session_event_id" />

Form context collection has an 8-second timeout and fails open by default so an unavailable fraud service does not strand the underlying form. Set data-preverus-form-context-timeout-ms to tune the timeout, or data-preverus-form-failure-mode="block" when a sensitive form must fail closed.

Your backend should pass those values to Preverus with a private server key before approving sensitive actions.

Event Use Cases

Call window.Preverus.track() for fraud-relevant browser events when you know the user or action.

Signup:

<script>
  window.Preverus.track("signup", {
    userId: "acct_42",
    email: "[email protected]",
  });
</script>

Login:

<script>
  window.Preverus.track("login", {
    userId: "acct_42",
    email: "[email protected]",
  });
</script>

Checkout or payment:

<script>
  window.Preverus.track("checkout", {
    userId: "acct_42",
    email: "[email protected]",
    metadata: {
      order_id: "ord_123",
      amount: "129.99",
    },
  });
</script>

Sensitive actions should still be enforced by your backend using a server key. Browser tracking adds intelligence; backend decisions enforce policy.

Platform Mode

Pass a browser API key to use the hosted Preverus platform for visitor resolution, event tracking, and risk workflows.

import { createPreverus } from "@preverus/sdk";

const preverus = createPreverus({
  apiKey: "pk_live_xxx",
});

const visitor = await preverus.init();

await preverus.events.track({
  eventType: "signup",
  userId: "user_123",
  email: "[email protected]",
});

In platform mode, the SDK automatically loads the Preverus browser agent from the configured API manifest. Most integrations only need apiKey.

Risk Sessions

Create a verified browser session when you want a backend decision to reference the full device/browser signals collected by the SDK.

const session = await preverus.session.create();

await fetch("/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    preverus_risk_session_token: session.token,
  }),
});

session.create() collects the full feature vector, sends it to https://api.preverus.com/v1/risk/session, creates a browser_session event, and returns a signed token. The token is only a reference to the stored Preverus session data; it does not contain the raw collected signals.

Browser Key Vs Server Key

Use two keys in production:

• Browser key: publishable, origin-restricted, used by frontend SDK collection, visitor resolution, and event tracking.
• Server key: private, used only on your backend for trusted account binding, risk decisions, metadata search, related visitor lookup, overrides, and investigation APIs.

Never put a server key in frontend code.

Backend enforcement example:

POST https://api.preverus.com/v1/decision/evaluate
X-API-Key: sk_live_xxx
X-Visitor-ID: v_abc123
Content-Type: application/json

{
  "user_id": "acct_42",
  "ip": "203.0.113.10",
  "risk_session_token": "signed_token_from_browser",
  "event_type": "signup",
  "metadata": {
    "email": "[email protected]"
  }
}

Visitor Resolution

Resolve the current browser/device into a stable, canonical Preverus visitor identity. The SDK privately persists an opaque continuity token; site owners store the returned visitorId, not the token.

const visitor = await preverus.visitor.resolve({
  userId: "user_123",
  email: "[email protected]",
});

console.log(visitor.visitorId);

Use visitorId as the Preverus platform identity. Use your own account ID as userId. Send the authenticated account ID together with the visitor ID from your backend to bind additional devices safely; browser metadata alone does not create a deterministic account binding.

Event Tracking

Track security and fraud-relevant events continuously.

await preverus.events.track({
  eventType: "login",
  userId: "user_123",
  email: "[email protected]",
});

Risk Evaluation

Use risk evaluation before sensitive actions such as signup, login, checkout, payout, withdrawal, password reset, or bonus redemption.

Best practice: run risk evaluation from your backend with a server key after the browser SDK has collected a fingerprint and resolved a visitorId.

const risk = await preverus.risk.evaluate({
  eventType: "signup",
  userId: "user_123",
  email: "[email protected]",
});

Public API

• createPreverus(config?): creates a client instance.
• preverus.configure(config?): configures the singleton client.
• preverus.init(): initializes the client and resolves a visitor when an API key is configured.
• preverus.fingerprint.get(): returns a local fingerprint hash.
• preverus.fingerprint.collect(): returns the collected feature vector and fingerprint.
• preverus.visitor.resolve(input?): resolves and stores the Preverus visitorId.
• preverus.visitor.lookup(input?): looks up visitor risk/profile context.
• preverus.visitor.related(input): returns visitors connected through shared metadata signals.
• preverus.events.track(input?): collects signals and sends an event.
• preverus.risk.evaluate(input?): evaluates risk for a sensitive action.
• preverus.metadata.lookup(input): looks up reputation/linkage context.
• preverus.metadata.search(input): alias for metadata.lookup().
• preverus.consent.set(granted): updates collection consent.
• preverus.consent.get(): returns current consent state.
• preverus.storage.clear(): clears stored fingerprint and visitor identity.

Configuration

Most platform integrations only need apiKey.

const preverus = createPreverus({
  apiKey: "pk_live_xxx",
  debug: false,
  sampleRate: 1,
});

Advanced deployments can override the API endpoint or agent manifest URL.

const preverus = createPreverus({
  apiKey: "pk_live_xxx",
  endpoint: "https://api.example.com",
  agentManifestUrl: "https://api.example.com/v1/agent/manifest",
});

Consent And Storage

• Consent defaults to granted for invisible security use cases.
• consent.granted=false disables collection side effects, network sends, periodic telemetry, and identity storage until consent is granted.
• consent.respectDoNotTrack=true starts denied when the browser has Do Not Track enabled.
• preverus.storage.clear() removes stored fingerprint and visitor identity values.

Browser Support

Recommended target browsers:

• Chrome/Edge 100+
• Firefox 100+
• Safari 15.4+
• Mobile Safari 15.4+
• Chromium-based Android browsers 100+

Documentation

Full documentation: https://preverus.com/docs

License

MIT