Predefined capture UI

launch() opens the native Mobai capture screen on top of your app. It provides the camera preview, face overlay, countdown, progress, live feedback, camera permission handling, and capture lifecycle. Use it unless your application needs complete control over the screen layout.

Integration	Choose it when
Predefined UI	You want the shortest integration and Mobai-managed capture controls.
Custom UI	Your application must own the screen layout and visual design.

Configure a production session

import {
  launch,
  MBCaptureConstraints,
  MBImageQualityLevel,
  type MobaiBiometricOptions,
} from "@mobaibio/mobai-biometric";

const options: MobaiBiometricOptions = {
  numberOfFrameToCollect: 3,
  videoCaptureDuration: 2000,
  timeBeforeAutomaticCapture: 1,
  captureConstrains: MBCaptureConstraints.V3,
  imageQualityLevel: MBImageQualityLevel.LEVEL_2,
  sessionId: sessionId,

  showProgressBar: true,
  showFaceStatusLabel: true,
  showCountdownLabel: true,

  cameraPermissionAlert: {
    title: "Camera access required",
    message: "Enable camera access in Settings to continue.",
    settingText: "Open Settings",
    cancelText: "Cancel",
  },
};

launch(options);

sessionId is optional. Supply it when your backend flow needs authenticated frame and video session metadata. See Capture results.

Common capture options

Option	Default	Purpose
numberOfFrameToCollect	3	Number of frames sampled from the video interval.
videoCaptureDuration	1000	Video duration in milliseconds, clamped to 1000–3000.
timeBeforeAutomaticCapture	1	Countdown duration in seconds.
captureConstrains	MBCaptureConstraints.V1	Selects the V1, V2, or V3 validation pipeline.
imageQualityLevel	MBImageQualityLevel.LEVEL_3	Selects V3 lighting strictness. It has no effect on V1 or V2.
sessionId	—	Key for the authenticated sessionMetadata and sessionVideoMetadata.
targetResolution	TargetResolution.HD_720	Capture resolution: HD_720, HD_1080, or HD_4K. QHD is deprecated and falls back to HD_720.
previewScaleType	PreviewScaleType.fill	fill covers the screen and crops the preview; fit shows the full camera frame. Captured images are not affected.
isDebugging	false	Enables SDK diagnostics.
payloadOptimization	false	Enables biometric payload-size optimization.

For a new integration, start with V3 and LEVEL_2, then adjust the quality level after testing on your supported devices and environments.

Configure visible UI components

The optional components default to hidden. Configure them independently of debug mode:

Option	Default	Purpose
showProgressBar	false	Displays capture progress.
showFaceStatusLabel	false	Displays geometry and V3 lighting guidance.
showCountdownLabel	false	Displays the automatic-capture countdown.
countdownLabelText	—	Text shown with the countdown.
cameraPermissionAlert	required	Alert shown when camera access has been denied.

To change the guidance texts, see Feedback and localization.

Debug mode

Do not enable isDebugging just to show progress or user guidance. Enable the corresponding show… options so those components remain available in production builds.

Receive capture events

The capture screen reports its result through the native event emitter. Subscribe before calling launch(), and remove the listeners when the screen that launched the capture unmounts:

import { useEffect } from "react";
import { NativeEventEmitter } from "react-native";
import {
  MobaiBiometric,
  EVENT_SUCCESS,
  EVENT_FAILURE,
  type MBCaptureSessionResult,
  type ErrorResult,
} from "@mobaibio/mobai-biometric";

useEffect(() => {
  const emitter = new NativeEventEmitter(MobaiBiometric);
  const success = emitter.addListener(EVENT_SUCCESS, (result: MBCaptureSessionResult) => {
    upload(result);
  });
  const failure = emitter.addListener(EVENT_FAILURE, (error: ErrorResult) => {
    showRetry(error.errorDescription);
  });
  return () => {
    success.remove();
    failure.remove();
  };
}, []);

Event	Payload	Sent when
EVENT_SUCCESS	MBCaptureSessionResult	The capture finished. The capture screen closes.
EVENT_FAILURE	ErrorResult (errorDescription)	The capture could not be completed.

The predefined UI handles frame-by-frame feedback itself; it does not send validation events to JavaScript.

Platform notes

• iOS: launch() presents the capture screen from AppDelegate.window. An app whose AppDelegate does not set window crashes when launch() is called. Apps built for iOS 27 must assign the window from their SceneDelegate to AppDelegate.window; see iOS 27: adopt the UIScene lifecycle.
• Android: with MBCaptureConstraints.V1, launch() returns empty sessionMetadata and sessionVideoMetadata even when sessionId is set. Use V2 or V3, or the custom UI, when you need session metadata.

Continue the integration

• Capture constraints and image quality
• Feedback and localization
• Capture results
• Troubleshooting