identro-liveness-react

v1.2.0

Published

23 days ago

React SDK for adding Identro biometric liveness verification and face match workflows to web applications.

0High
0Medium
0Low

syrol

identro liveness face-liveness face-verification biometric kyc identity-verification react nextjs fintech

Identro Liveness React SDK

React SDK for adding Identro biometric liveness verification and optional face match workflows to React, Vite, and Next.js applications.

The React package now matches the Flutter SDK look and behavior:

fullscreen camera experience,
automatic liveness start,
vertical oval face guide,
stepped square corner frame,
dark overlay outside the face area,
clear center capture area,
customizable branding, colors, logo, copy, and powered-by footer,
liveness only, BVN match, NIN match, and reference image match,
direct Identro API mode,
secure backend-proxy mode,
optional AWS active liveness mode,
passive guided camera mode for Flutter-like UI parity.

Installation

npm install identro-liveness-react

Peer dependencies:

npm install react react-dom

Requirements

React 18 or newer.
Browser with camera support.
HTTPS in production for camera access.
Identro merchant API key or a merchant backend proxy.
Identro liveness services enabled on your merchant account.

Default Identro API endpoints:

POST /merchant-api/face/liveness/sessions
POST /merchant-api/face/liveness/sessions/:reference/credentials
POST /merchant-api/face/liveness/sessions/:reference/complete

Quick start

import { IdentroLiveness } from 'identro-liveness-react';

export function LivenessPage() {
  return (
    <IdentroLiveness
      baseUrl="https://api.identro.ng/api/v1"
      apiKey="identro_live_xxxxx"
      captureMode="passive"
      request={{
        serviceType: 'FACE_LIVENESS_ONLY',
        sourceType: 'UPLOADED_REFERENCE',
        consentCaptured: true,
        consentReference: 'CUSTOMER-CONSENT-001',
        idempotencyKey: 'LIVE-001',
      }}
      onCompleted={(result) => {
        console.log('Identro result', result);
      }}
      onCancel={() => {
        console.log('User cancelled');
      }}
      onError={(error) => {
        console.error('Identro liveness failed', error);
      }}
    />
  );
}

Capture modes

| Mode | Meaning | Use case | |---|---|---| | passive | Uses the package fullscreen camera UI, captures a compressed selfie frame, and completes the liveness session with fallback evidence | Best visual parity with Flutter SDK and fastest integration | | aws | Creates Identro session, gets temporary AWS credentials, and renders AWS Face Liveness Detector inside the Identro shell | Active challenge-based web liveness |

Default:

captureMode="passive"

Use AWS active liveness:

<IdentroLiveness
  captureMode="aws"
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={request}
/>

Liveness + BVN

<IdentroLiveness
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={{
    serviceType: 'FACE_LIVENESS_BVN',
    sourceType: 'BVN',
    bvn: '22123456789',
    consentCaptured: true,
    consentReference: 'BVN-CONSENT-001',
    idempotencyKey: 'LIVE-BVN-001',
  }}
/>

Liveness + NIN

<IdentroLiveness
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={{
    serviceType: 'FACE_LIVENESS_NIN',
    sourceType: 'NIN',
    nin: '12345678901',
    consentCaptured: true,
    consentReference: 'NIN-CONSENT-001',
    idempotencyKey: 'LIVE-NIN-001',
  }}
/>

Liveness + reference image

<IdentroLiveness
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={{
    serviceType: 'FACE_LIVENESS_REFERENCE',
    sourceType: 'UPLOADED_REFERENCE',
    referenceFaceBase64: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...',
    consentCaptured: true,
    consentReference: 'REFERENCE-CONSENT-001',
    idempotencyKey: 'LIVE-REF-001',
  }}
/>

Full branding customization

<IdentroLiveness
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={request}
  branding={{
    name: 'MyBank',
    subtitle: 'Secure customer verification',
    logo: <img src="/mybank-logo.svg" alt="MyBank" height={32} />,
    poweredByLogoUrl: '/identro-logo.png',

    primaryColor: '#10B981',
    accentColor: '#34D399',
    background: 'linear-gradient(135deg,#020617,#064E3B)',
    textColor: '#ffffff',
    mutedTextColor: 'rgba(255,255,255,.78)',

    fullscreenCamera: true,
    showTopBar: true,
    showActionButtons: false,

    guideDashed: true,
    guideStrokeWidth: 3.5,
    guideGlowOpacity: 0.18,
    guideWidthFactor: 0.54,
    guideHeightFactor: 0.56,

    showCornerFrame: true,
    cornerFrameColor: '#10B981',
    cornerFrameStrokeWidth: 4,
    cornerFrameLength: 36,
    cornerFrameRadius: 18,
    cornerFramePadding: 28,

    overlayOpacity: 0.80,
    centerHighlightOpacity: 0.08,

    showPoweredBy: true,
  }}
/>

Branding options

| Option | Type | Description | |---|---|---| | name | string | Merchant/brand name | | subtitle | string | Brand subtitle | | logoUrl | string | URL logo | | logo | ReactNode | Custom logo node | | poweredByLogoUrl | string | Powered-by logo URL | | poweredByLogo | ReactNode | Custom powered-by logo node | | primaryColor | string | Main brand color | | accentColor | string | Accent color | | background | string | Color or CSS gradient | | fullscreenCamera | boolean | Fullscreen liveness camera | | showTopBar | boolean | Show app-bar/back arrow | | showActionButtons | boolean | Show manual buttons. Default is false because liveness auto-starts | | showPoweredBy | boolean | Show/hide powered-by footer | | guideDashed | boolean | Dashed or solid oval guide | | showCornerFrame | boolean | Show stepped square corner frame | | cornerFrameColor | string | Corner frame color | | overlayOpacity | number | Darkness outside face area | | centerHighlightOpacity | number | Light highlight inside face area |

Text customization

<IdentroLiveness
  baseUrl="https://api.identro.ng/api/v1"
  apiKey="identro_live_xxxxx"
  request={request}
  text={{
    appBarTitle: 'Face verification',
    subtitle: 'Center your face and follow the guide.',
    creatingSession: 'Preparing secure verification...',
    capturing: 'Hold still and keep your face inside the guide',
    processing: 'Finalizing your verification...',
    passed: 'Verification successful',
    review: 'Verification needs review',
    failed: 'Verification failed',
    retry: 'Try again',
    cancel: 'Cancel',
    poweredBy: 'Powered by',
    poweredByBrand: 'Identro',
  }}
/>

Secure backend-proxy mode

For production public apps, do not expose a permanent Identro merchant API key in the browser. Use your backend to call Identro.

<IdentroLiveness
  baseUrl="https://merchant.example.com"
  request={request}
  handlers={{
    async createSession(request) {
      const response = await fetch('/api/identro/liveness/session', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(request),
      });
      if (!response.ok) throw new Error('Unable to create liveness session');
      return response.json();
    },
    async getCredentials(reference, session) {
      const response = await fetch(`/api/identro/liveness/${reference}/credentials`, {
        method: 'POST',
      });
      if (!response.ok) throw new Error('Unable to prepare liveness capture');
      return response.json();
    },
    async completeSession(reference, session, payload) {
      const response = await fetch(`/api/identro/liveness/${reference}/complete`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(payload),
      });
      if (!response.ok) throw new Error('Unable to complete liveness session');
      return response.json();
    },
  }}
/>

Your backend should call Identro with:

x-api-key: YOUR_PRIVATE_IDENTRO_MERCHANT_API_KEY

Running the example app

cd example
npm install
npm run dev -- --port 8080

Environment variables:

VITE_IDENTRO_BASE_URL=https://api.identro.ng/api/v1
VITE_IDENTRO_API_KEY=your_merchant_api_key
VITE_IDENTRO_MERCHANT_ID=your_merchant_id

Run with env values:

VITE_IDENTRO_BASE_URL=https://api.identro.ng/api/v1 \
VITE_IDENTRO_API_KEY=your_merchant_api_key \
VITE_IDENTRO_MERCHANT_ID=your_merchant_id \
npm run dev -- --port 8080

The example includes:

setup screen,
merchant ID/API key fields,
liveness only/BVN/NIN/reference image choices,
passive and AWS capture mode options,
branding color controls,
fullscreen SDK screen,
result screen with scores and raw JSON.

Flutter Web / React Web CORS note

When testing from React on localhost:8080, the backend must allow:

Origin: http://localhost:8080
Headers: Content-Type, Accept, Authorization, x-api-key
Methods: GET, POST, OPTIONS

Troubleshooting

Camera does not open

Use HTTPS in production. Localhost is usually allowed by browsers.

CORS error

Allow your local origin and x-api-key header on the backend.

Request entity too large

Increase backend and Nginx body limits because passive mode submits a compressed camera frame.

Nginx:

client_max_body_size 50M;

NestJS/Express:

app.use(json({ limit: '50mb' }));
app.use(urlencoded({ extended: true, limit: '50mb' }));

Insufficient balance

The merchant wallet balance is lower than the price of the selected liveness service.

Publishing

npm run clean
npm install
npm run typecheck
npm run build
npm pack --dry-run
npm publish --access public

License

MIT. See LICENSE.