@vizualkei/fanidface-client-sdk

FanIDFace-branded variant of @vizualkei/sophid-client-sdk. The implementation is a thin wrapper over the SophID client SDK: FanIDFaceClientHelper extends NeumaClientHelper unchanged, and most types are simply re-exported.

The only behavioral differences are:

• The helper's singleton is independent (fanidfaceClientHelper, distinct from neumaClientHelper).
• When onAppLaunchFailed fires, the wrapper rewrites the AppLaunchFailureContext so appName is FanIDFace Mobile, installUrl points to the FanIDFace Mobile Play Store listing, and the message references the FanIDFace app.
• The install URL constant points at io.vizualkei.fanidface_mobile.

For full API details (config shape, methods, QR flow, error model, types), see the SophID client SDK README. This document only documents the FanIDFace-specific surface.

Installation

pnpm add @vizualkei/fanidface-client-sdk

This package depends on @vizualkei/sophid-client-sdk and declares react@^18.3.1 as a peer dependency.

Public exports

From @vizualkei/fanidface-client-sdk:

| Name | Kind | Source | | ------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- | | FanIDFaceClientHelper | class | Local — extends NeumaClientHelper with no overrides | | fanidfaceClientHelper | object | Local — singleton wrapper around FanIDFaceClientHelper | | FanIDFaceClientHelperConfig | type | Local — alias of NeumaClientHelperConfig | | FanIDFaceError | class | Local — SophIDError subclass with name = 'FanIDFaceError' | | FanIDFaceMobileFactory | object (create()) | Local — delegates to SophIDMobileFactory.create() | | FanIDFaceMobileInterface | type | Re-export of SophIDMobileInterface | | FanIDFaceMobileOptions | type | Re-export of SophIDMobileOptions | | FanIDFaceEnrollmentResult | type | Re-export of EnrollmentResult | | FanIDFaceAuthenticationResult | type | Re-export of AuthenticationResult | | EnrollUserOptions, UserDescriptor, KeyRetrievalResult, PackageVersion | types | Re-exports from @vizualkei/sophid-client-sdk | | PendingOperationInfo | type | Re-export from @vizualkei/sophid-client-sdk | | HandlePendingOperationOptions, PendingOperationResult | types | Re-exports from @vizualkei/sophid-client-sdk | | AppLaunchPlatform, AppLaunchFailureContext, QrCodeData, QrCodeCleanupFn | types | Re-exports | | FANIDFACE_MOBILE_PLAY_STORE_URL | constant | https://play.google.com/store/apps/details?id=io.vizualkei.fanidface_mobile | | getFanIDFaceMobileInstallUrl(platform) | function | Returns the FanIDFace Mobile install URL for Android, undefined otherwise |

There is also an installLinks subpath export that exposes only the install-URL helpers.

Quick start

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

fanidfaceClientHelper.init({
    biometricSessionUrl: '/api/biometric-session',
    biometricResultUrl: '/api/biometric-results',
    fetcher: (input, init) => fetch(input, init),
    onQrCode: ({ deepLinkUrl, onCancel }) => showMyQrModal(deepLinkUrl, onCancel),
    onAppLaunchFailed: ({ appName, installUrl, message }) => {
        // appName === 'FanIDFace Mobile'
        // installUrl === FANIDFACE_MOBILE_PLAY_STORE_URL on Android
        showInstallModal({ appName, installUrl, message });
    },
});

const brt = await fanidfaceClientHelper.authenticateUser();

fanidfaceClientHelper singleton API

All methods proxy to the underlying FanIDFaceClientHelper and match the SophID client SDK signatures exactly:

| Method | Signature | | ------------------------------------ | ----------------------------------------------------------------------------- | | init(config) | (FanIDFaceClientHelperConfig) => FanIDFaceClientHelper | | get() | () => FanIDFaceClientHelper (throws if not initialized) | | ensureInitialized() | () => void | | enrollUser(user, enrollOptions?) | (UserDescriptor, EnrollUserOptions?) => Promise<string> | | restoreUser() | () => Promise<string> | | authenticateUser() | () => Promise<string> | | authenticateUserDirect() | () => Promise<string> | | unenrollUser() | () => Promise<string> | | retrieveKey() | () => Promise<null> | | clearUser() | () => Promise<void> | | parseRetrieveKeyResult(jsonString) | (string) => KeyRetrievalResult | | handlePendingOperation(options?) | (HandlePendingOperationOptions?) => Promise<PendingOperationResult \| null> | | getPendingOperation() | () => PendingOperationInfo \| null | | resumePendingResult() | () => Promise<unknown \| null> | | clearPendingResult() | () => void |

Use handlePendingOperation() from page-load code for iOS Safari return-flow recovery. It is UI-agnostic: the SDK resumes or retrieves the pending result, maps failed BRT claims to an error, submits recovered successful BRTs by default, then calls your app's callbacks so you can show a modal, navigate, write state, or render any other result UI.

fanidfaceClientHelper.init also calls neumaClientHelper.init internally with a FanIDFace installUrlResolver and wrapped onAppLaunchFailed, so both singletons share the same underlying SophIDMobile configuration without inheriting Neuma install URLs.

App-launch failure rebranding

The wrapper configures SophIDMobileOptions.installUrlResolver with getFanIDFaceMobileInstallUrl and intercepts onAppLaunchFailed to replace the AppLaunchFailureContext fields:

| Field | Value | | --------------------------- | ------------------------------------------------------------- | | appName | 'FanIDFace Mobile' | | installUrl | getFanIDFaceMobileInstallUrl(platform) (Android only) | | message (iOS) | 'You need to install the fanidface mobile app.' | | message (other platforms) | 'Install FanIDFace Mobile to continue this biometric step.' |

operation and platform are forwarded unchanged.

Notes

• Deep-link scheme, QR-code app-link, and polling endpoints are inherited from @vizualkei/sophid-client-sdk (the QR app-link still rides on ${origin}/f/{opCode}/{callbackId} and the deep-link scheme is still sophdplk://operation). Branding is enforced only in the launch-failure UX.
• FanIDFaceError only differs from SophIDError in name. The error code enumeration is unchanged.
• The default biometric service URL inherited from the SophID SDK is https://api.sophid.xyz:443. Override it with config.biometricService when integrating with a different deployment.

License

Apache-2.0