FanIDFace Client SDK

Client-side TypeScript SDK for browser-based apps integrating FanIDFace biometric authentication.

This package exposes the FanIDFaceClientHelper API for:

• requesting BST-backed biometric operations from your server
• launching the FanIDFace mobile flow from phone and desktop browsers
• receiving signed BRT results from the FanIDFace flow

Installation

pnpm add @vizualkei/fanidface-client-sdk

Token Model

FanIDFace web integrations use two tokens:

• BST — Biometric Session Token
  • issued by your server before a biometric operation starts
  • short-lived and bound to a single flow
• BRT — Biometric Result Token
  • returned after the biometric operation completes
  • sent back to your server for validation

Typical flow:

1. your server issues a BST
2. the client launches the FanIDFace biometric flow
3. the biometric flow returns a BRT
4. your server validates the BRT

Quick Start

import { fanidfaceClientHelper } from '@vizualkei/fanidface-client-sdk';

const fanidfaceClient = fanidfaceClientHelper.init({
  biometricSessionUrl: '/api/biometric-session',
  biometricResultUrl: '/api/biometric-results',
  fetcher: (input, init) => fetch(input, init),
});

const brt = await fanidfaceClient.authenticateUser();

FanIDFaceClientHelper

FanIDFaceClientHelper is the main API of this package.

It handles:

• requesting BSTs from your server
• initializing the FanIDFace mobile SDK
• submitting returned BRTs back to your server

FanIDFaceClientHelperConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | biometricSessionUrl | string | Yes | Server endpoint that issues BSTs | | biometricResultUrl | string | Yes | Server endpoint that receives BRTs | | fetcher | (input, init?) => Promise<Response> | Yes | Fetch function used by the helper | | biometricService | string | No | FanIDFace biometric server base URL | | onQrCode | function | No | Desktop QR flow callback | | onAppLaunchFailed | function | No | Callback when app launch likely failed | | sdkOptions | object | No | Additional FanIDFace mobile SDK options | | resultPayloadBuilder | function | No | Custom builder for BRT submit payload |

Helper Methods

ensureInitialized()

Initializes the underlying client early if desired.

enrollUser(user, enrollOptions?)

Starts a FanIDFace enrollment flow and returns a BRT.

restoreUser()

Starts a restore flow and returns a BRT.

authenticateUser()

Starts an authentication flow and returns a BRT.

authenticateUserDirect()

Starts authentication but returns the BRT directly without auto-submitting it to the configured result endpoint.

unenrollUser()

Starts an unenrollment flow and returns a BRT.

retrieveKey()

Runs the offline retrieve-key flow.

clearUser()

Clears the local user on the device.

parseRetrieveKeyResult(jsonString)

Parses the pasted result from the retrieve-key flow.

Additional Exports

• FanIDFaceError
• FanIDFaceMobileFactory
• FanIDFaceMobileInterface
• FanIDFaceMobileOptions
• getFanIDFaceMobileInstallUrl
• FANIDFACE_MOBILE_PLAY_STORE_URL

License

Apache-2.0