@fintech-automation/face-liveness

v0.2.2

Published

a month ago

Branded, drop-in face liveness React component with runtime configuration built in.

0High
0Medium
0Low

face-liveness liveness identity verification rekognition react

FTA Face Liveness SDK Overview

@fintech-automation/face-liveness is a branded React SDK around a managed face liveness capture engine. It provides:

FTA backend session creation and result lookup.
Bundled runtime configuration per environment.
Branded wrapper screens before and after the camera capture step.
Grouped brand, theme, localization, captureText, and callbacks options for readable host integration.

The flow is:

intro -> prepare -> capture -> processing -> success | fail | error

Installation

npm install @fintech-automation/face-liveness

Usage

import React from 'react'
import { FaceLiveness } from '@fintech-automation/face-liveness'
import '@fintech-automation/face-liveness/styles.css'

export default function App() {
  return (
    <FaceLiveness
      tenant="YOUR_TENANT"
      launchToken='YOUR_LAUNCH_TOKEN',
      brand={{
        name: 'name',
        logoUrl: 'https://cdn.example.com/logo.svg',
      }}
      callbacks={{
        onSuccess: (result) => console.log('verified', result),
        onFail: (result) => console.log('not passed', result),
        onError: (error) => console.error(error.stage, error.message),
        onCancel: () => console.log('cancelled'),
      }}
    />
  )
}

Browser Bundle Usage

React and ReactDOM are bundled inside the SDK — no extra script tags needed. Use the global FaceLiveness.mount() helper to render into any container.

<html>
  <head>
      <!-- main css file  -->
       <link rel="stylesheet" href="https://cdn.accelerationcloud.com/face-liveness.min.css" />
      <!-- main js file  -->
        <script src="https://cdn.accelerationcloud.com/face-liveness.min.js"></script>
  </head>
  <body>
    <div id="liveness-container"></div>

    <script>
      // Mount the Face Liveness SDK into the container
      FaceLiveness.mount('#liveness-container', {
        tenant:"YOUR_TENANT",
        launchToken: 'YOUR_LAUNCH_TOKEN',
        callbacks: {
          onSuccess: (result) => console.log('verified', result),
          onFail: (result) => console.log('not passed', result),
          onError: (error) => console.error(error.stage, error.message),
          onCancel: () => console.log('cancelled'),
        },
        brand: {
          name: 'Your Business Name',
          logoUrl: 'https://cdn.example.com/logo.svg',
        },
      })
    </script>
  </body>
</html>

Package Files

| Purpose | File | | ------------------ | ---------------------------- | | ESM module | dist/index.mjs | | Browser/UMD bundle | dist/face-liveness.min.js | | CSS | dist/face-liveness.min.css | | TypeScript types | index.d.ts |

Authentication And Sessions

The SDK talks to the Face Liveness backend at:

api/v1/cores/unifi/face-liveness/public-link

Getting the Launch Link

After calling the UniFi Face Liveness API, a link will be returned. This link contains the required information to start the Face Liveness process.

Reference documentation: https://api-docs.accelerationcloud.com/resource/unifi-face-liveness

Parsing Link Parameters

The returned link contains two key parameters:

https://[your-app-domain]?token=YOUR_TOKEN&api_domain=YOUR_API_DOMAIN&tenant=YOUR_TENANT

| Parameter | Description | |-----------|-------------| | token | Required. Bearer token used for API authentication and initializing the Face Liveness process | | tenant | Required. Tenant namespace for the backend service. | | api_domain | API server domain that specifies the backend service address |

Component Props

Top-level props are reserved for session/runtime parameters:

| Prop | Type | Default | Description | | -------------- | --------------------------------------- | ------------------------ | ---------------------------------------------------- | | environment | 'dev' \| 'staging' \| 'uat' \| 'prod' | 'prod' | Selects the backend URL and bundled runtime config. | | launchToken | string | none | Preferred short-lived bearer token for backend APIs. | | backendUrl | string | selected environment URL | Overrides the backend URL. | | origin | string | none | Optional origin/domain sent to the backend. | | tenant | string | 'unifi' | Backend tenant namespace. | | callbacks | LivenessCallbacks | none | Event callbacks. | | flow | LivenessFlow | SDK defaults | Flow behavior. | | brand | LivenessBrand | SDK defaults | Brand shown in the SDK header. | | theme | LivenessTheme | SDK defaults | Visual system tokens. | | localization | LivenessLocalization | SDK defaults | SDK-owned screen copy. | | captureText | Record<string, string> | SDK defaults | Text overrides for the camera/capture step. |

Callbacks

<FaceLiveness
  callbacks={{
    onScreenChange: (screen) => console.log('screen', screen),
    onAnalysisComplete: () => console.log('analysis complete'),
    onSuccess: (result) => console.log('success', result),
    onFail: (result) => console.log('fail', result),
    onError: (error) => console.error(error.stage, error.message),
    onCancel: () => console.log('cancelled'),
    onContinue: () => console.log('continue'),
  }}
/>

| Prop | Type | Description | | --- | --- | --- | | onScreenChange | (screen: 'intro' \| 'prepare' \| 'capture' \| 'processing' \| 'success' \| 'fail' \| 'error') => void | Called when the flow changes screens. | | onAnalysisComplete | () => void | Called when the capture detector finishes analysis and the SDK begins fetching backend results. | | onSuccess | (result: LivenessResult) => void | Called after the backend returns a successful liveness result. | | onFail | (result: LivenessResult) => void | Called after the backend returns a non-passing or failed result. | | onError | (error: { stage: string; message: string; cause?: unknown }) => void | Called when a session, camera, capture, or result-fetch error occurs. | | onCancel | () => void | Called when the user cancels the live capture flow. | | onContinue | () => void | Called when the user taps Continue on the success screen. |

Result Object

interface LivenessResult {
  id?: string;
  session_id?: string;
  status?: 'PASSED' | 'FAILED';
  fail_reason?: string | null;
  created_time?: string;
  completed_time?: string;
  response_json?: string;
  audit_img_file_ids?: string;
  reference_img_file_ids?: string;
  callback_url?: string;
  ...
}

Brand

<FaceLiveness
  brand={{
    name: 'AccCloud',
    logoUrl: 'https://cdn.example.com/logo.svg',
    secureLabel: 'Encrypted session',
  }}
/>

| Field | Default | Description | | ------------- | --------------------- | --------------------------------------------------------------------- | | name | '' | Your business name. | | logo | none | Optional React node brand mark for React consumers. | | logoUrl | none | Optional image URL brand mark; preferred for hosted/runtime wrappers. | | secureLabel | 'Encrypted session' | Top-right security label; pass '' to hide. |

Friendly Note 📝

Note: The brand mark is rendered with the following priority:
logo – If you pass a custom React node, it takes full precedence.
logoUrl – If no logo is provided, we'll display your image.
name – As a last resort, we'll generate a clean initials-based mark (e.g., "Face Liveness" → "FL") to keep the UI tidy.
This ensures your brand identity always appears — whether as a rich component, an image, or a simple text abbreviation. ✨

Flow

<FaceLiveness
  flow={{
    skipIntro: false,
    skipPrepare: false,
  }}
/>

| Field | Default | Description | | ------------- | ------- | ----------------------------------------------------------------------------------- | | skipIntro | false | Starts at Prepare instead of Intro. | | skipPrepare | false | Goes straight to capture after Intro, or immediately when skipIntro is also true. |

Theme

<FaceLiveness
  theme={{
    colors: {
      primary: '#1634A4',
      secondary: '#1A3DBF',
      heading: '#111827',
    },
    shape: {
      radius: 22,
    },
    typography: {
      fontFamily: "'Inter', system-ui, sans-serif",
    },
    layout: {
      width: 400,
      fullscreen: true,
    },
  }}
/>

| Field | Default | Description | | ----------------------- | ------------------ | ------------------------------------------------------ | | colors.primary | '#1634A4' | Main brand color. | | colors.secondary | '#1A3DBF' | Secondary brand accent color. | | colors.heading | '#111827' | Main heading and strong text color. | | shape.radius | 22 | Root/card corner radius in pixels. | | typography.fontFamily | Inter/system stack | Font family used by wrapper screens and capture theme. | | layout.width | 400 | Root card width. Number values are treated as pixels. | | layout.fullscreen | true | Uses a full-height mobile/portrait tablet layout. |

Localization

localization customizes SDK-owned screens and is grouped by screen.

<FaceLiveness
  localization={{
    intro: {
      eyebrow: 'Identity check',
      title: "Let's confirm it's really you",
      body: 'A quick face scan helps protect your account.',
      cta: 'Start face scan',
      trustLabel: 'Bank-grade liveness detection',
    },
    prepare: {
      eyebrow: 'Before we start',
      title: 'Three things for a clean scan',
      tips: [
        { title: 'Find good light', body: 'Avoid strong backlight.' },
        { title: 'Clear your face', body: 'Remove sunglasses or masks.' },
        { title: 'Hold steady', body: 'Keep the device at eye level.' },
      ],
      cta: "I'm ready",
      backLabel: 'Back',
    },
    starting: {
      title: 'Starting camera',
      body: 'Creating a secure liveness session.',
    },
    processing: {
      title: 'Verifying your scan',
      body: 'This usually takes just a moment.',
    },
    success: {
      title: "You're verified",
      body: 'Thanks. The liveness check was completed.',
      cta: 'Continue',
    },
    fail: {
      title: "We couldn't complete the scan",
      body: 'Move somewhere brighter and try again.',
      cta: 'Try again',
    },
    cameraPermission: {
      title: 'Camera access is required',
      body: 'Allow camera access, then try again.',
    },
  }}
/>

Capture Text

captureText customizes the text shown during the camera/capture step.

<FaceLiveness
  captureText={{
    hintCenterFaceText: 'Center your face',
    hintTooCloseText: 'Move back',
    hintTooFarText: 'Move closer',
    hintHoldFaceForFreshnessText: 'Hold still',
  }}
/>

Notes

The camera capture step owns the camera oval geometry and liveness model flow. This SDK themes the surrounding UI and supported capture theme tokens.
The underlying capture runtime uses process-global client configuration. If a host app also configures the same provider runtime, mount this SDK with that shared global behavior in mind.
Camera capture requires browser camera permission, HTTPS in production, WebGL, and network access to liveness assets.
Bundled runtime ids are public client identifiers. Privileged operations stay on the FTA backend.

License

This repository includes the FinTech Face Liveness SDK, which is licensed under a Commercial License Agreement. See COMMERCIAL-LICENSE.md for full terms.

Use of this SDK requires explicit permission from FinTech Automation.