Adhere Web SDK

The Adhere Web SDK enables you to rapidly and securely verify user identities and perform facial liveness checks directly in your web applications. The SDK mounts a drop-in widget over your application, handling document capture, identity verification, and liveness detection — all in one seamless flow.

Features

Drop-in UI Modal — Responsive, animated widget that overlays your app via SmartComplyFlow.open().
CDN & npm Support — Install via npm/yarn or load directly from a CDN with zero build steps.
Dynamic Routing — Automatically adapts document and verification requirements from your dashboard configuration.
One-Time Use Policy — Each clientId is single-use to prevent duplicate verifications.
Nigeria & Global Identity — Supports BVN, NIN, and International Passport verification.
Hardware Agnostic Liveness — Uses native webcam and MediaRecorder API for cross-platform compatibility.

Installation

Option 1 — CDN (No build step required)

Add the script tag to your HTML:

<!-- Always latest version -->
<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@latest/dist/smartcomply.browser.js"></script>

<!-- Or pin to a specific version (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@1.0.19/dist/smartcomply.browser.js"></script>

The SDK is available globally as window.SmartComplySDK:

const { SmartComplyFlow, SmartComply } = window.SmartComplySDK;

Pin to a specific version in production (e.g. @1.0.19) to avoid unexpected breaking changes.

Option 2 — npm / yarn

npm install smartcomply-web-sdk
# or
yarn add smartcomply-web-sdk

import { SmartComplyFlow } from 'smartcomply-web-sdk';

The easiest way to integrate is the drop-in widget. It handles the complete verification flow automatically.

SmartComplyFlow.open({
  apiKey: "your_api_key_here",
  clientId: "your_client_id_here",
  environment: "production", // "production" or "sandbox"

  onComplete: (result) => {
    console.log("Verification complete:", result);
    // result = { entryId, sessionId, status, submittedAt }
  },
  onError: (error) => {
    console.error("Verification failed:", error);
  },
  onClose: () => {
    console.log("Widget closed.");
  }
});

Get your API Key and generate a Client ID from your Adhere Dashboard. Each clientId is single-use and tied to one verification session.

Configuration Parameters

Parameter	Type	Required	Description
`apiKey`	string	✅ Yes	Your API key from the Adhere Dashboard
`clientId`	string	✅ Yes	Single-use client ID generated per user
`environment`	string	No	`"production"` or `"sandbox"` (default: `"sandbox"`)
`onComplete`	function	No	Callback fired when verification completes successfully
`onError`	function	No	Callback fired on error
`onClose`	function	No	Callback fired when the widget is closed

Environment URLs

Environment	Base URL
`production`	`https://adhere-api.smartcomply.com`
`sandbox`	`https://dev-adhere.smartcomply.com`

Framework Examples

React

import { SmartComplyFlow } from 'smartcomply-web-sdk';

export default function VerifyButton() {
  const handleVerify = () => {
    SmartComplyFlow.open({
      apiKey: process.env.REACT_APP_API_KEY,
      clientId: process.env.REACT_APP_CLIENT_ID,
      environment: "production",
      onComplete: (result) => console.log("Done:", result),
      onError: (err) => console.error("Error:", err),
    });
  };

  return <button onClick={handleVerify}>Verify Identity</button>;
}

Vue

<template>
  <button @click="handleVerify">Verify Identity</button>
</template>

<script setup>
import { SmartComplyFlow } from 'smartcomply-web-sdk';

const handleVerify = () => {
  SmartComplyFlow.open({
    apiKey: import.meta.env.VITE_API_KEY,
    clientId: import.meta.env.VITE_CLIENT_ID,
    environment: "production",
    onComplete: (result) => console.log("Done:", result),
    onError: (err) => console.error("Error:", err),
  });
};
</script>

Plain HTML (CDN)

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/smartcomply-web-sdk@1.0.19/dist/smartcomply.browser.js"></script>
</head>
<body>
  <button onclick="startVerification()">Verify Identity</button>

  <script>
    const { SmartComplyFlow } = window.SmartComplySDK;

    function startVerification() {
      SmartComplyFlow.open({
        apiKey: "your_api_key_here",
        clientId: "your_client_id_here",
        environment: "production",
        onComplete: (result) => console.log("Done:", result),
        onError: (err) => console.error("Error:", err),
      });
    }
  </script>
</body>
</html>

Headless API (Advanced)

For full control over the UI, use the SmartComply class directly without the modal.

import { SmartComply } from 'smartcomply-web-sdk';

const sdk = new SmartComply({
  apiKey: "your_api_key_here",
  clientId: "your_client_id_here",
  environment: "production",
});

const run = async () => {
  // 1. Create a session
  await sdk.createSession();

  // 2. Fetch SDK configuration
  const config = await sdk.initializeConfig();
  console.log("Verification type:", config.verification_type);

  // 3. Verify identity (BVN/NIN/Passport)
  await sdk.onboarding.verify({
    identity_type_id: 1,  // from config.channels
    fields: { bank_verification_number: "12345678901" }
  });

  // 4. Run liveness check — requires an HTMLElement container for the camera
  const container = document.getElementById("camera-container") as HTMLElement;
  const liveness = await sdk.liveness.startCheck(container, {
    identifier: "user-unique-id",
    identifier_type: "bvn",
    country: "NG",
  });
  console.log("Liveness status:", liveness.status);
};

run();

onComplete Payload

{
  "entryId": 365,
  "sessionId": "da7623bd-9158-4b56-a9e4-4bccf3c0133f",
  "status": "passed",
  "submittedAt": "2026-06-05T23:11:22.873161+00:00"
}

Security Notes

Single-use Client IDs — Each clientId expires immediately after a completed verification. Generate a fresh one per user session from your backend.
API Key — Never expose your API key in client-side code in production. Use environment variables.
Session Tokens — Session tokens are automatically managed by the SDK and expire after 30 minutes.

Troubleshooting

Error	Cause	Fix
`CLIENT_ID_ALREADY_USED`	`clientId` was already used	Generate a new `clientId` from your backend
`SESSION_EXPIRED`	Session exceeded 30 min timeout	Call `createSession()` again
`401 Unauthorized`	Invalid or missing API key	Check your `apiKey` value
`Camera not available`	Browser blocked camera access	Ensure HTTPS and camera permissions granted

API Reference

Web SDK

Adhere Web SDK

Features

Installation

Option 1 — CDN (No build step required)

Option 2 — npm / yarn

Quick Start — Drop-in Widget (Recommended)

Configuration Parameters

Environment URLs

Framework Examples

React

Vue

Plain HTML (CDN)

Headless API (Advanced)

onComplete Payload

Security Notes

Troubleshooting

​Adhere Web SDK

​Features

​Installation

​Option 1 — CDN (No build step required)

​Option 2 — npm / yarn

​Quick Start — Drop-in Widget (Recommended)

​Configuration Parameters

​Environment URLs

​Framework Examples

​React

​Vue

​Plain HTML (CDN)

​Headless API (Advanced)

​onComplete Payload

​Security Notes

​Troubleshooting

Adhere Web SDK

Features

Installation

Option 1 — CDN (No build step required)

Option 2 — npm / yarn

Quick Start — Drop-in Widget (Recommended)

Configuration Parameters

Environment URLs

Framework Examples

React

Vue

Plain HTML (CDN)

Headless API (Advanced)

onComplete Payload

Security Notes

Troubleshooting