Feedback and localization

The predefined UI can show geometry, pose, and V3 lighting guidance without enabling debug mode. In the custom UI, your application renders all texts itself.

Show feedback in production

launch({
  isDebugging: false,
  captureConstrains: MBCaptureConstraints.V3,
  showProgressBar: true,
  showFaceStatusLabel: true,
  showCountdownLabel: true,
  cameraPermissionAlert,
});

isDebugging controls diagnostics. The show… options control the user-facing interface.

Customize V3 messages

Pass faceStatusTexts and countdownLabelText to launch():

import { type FaceStatusTexts } from "@mobaibio/mobai-biometric";

const faceStatusTexts: FaceStatusTexts = {
  faceTooFarAway: "Move closer",
  faceTooClose: "Move farther away",
  faceTooFarUp: "Move the phone up",
  faceTooFarDown: "Move the phone down",
  faceTooFarLeft: "Move to the right",
  faceTooFarRight: "Move to the left",
  faceNotFound: "Face not found",
  tooManyFaces: "Only one face, please",
  validFace: "Hold still",
  facePoseInvalid: "Look straight at the camera",
  checkingLighting: "Checking the light",
  unevenLighting: "Use more even lighting",
  insufficientLight: "Move to a brighter area",
};

launch({
  captureConstrains: MBCaptureConstraints.V3,
  showFaceStatusLabel: true,
  showCountdownLabel: true,
  countdownLabelText: "Hold still",
  faceStatusTexts,
  cameraPermissionAlert,
});

Available face messages

Property	Used for
faceTooFarAway	Distance
faceTooClose	Distance
faceTooFarUp	Position
faceTooFarDown	Position
faceTooFarLeft	Position
faceTooFarRight	Position
faceNotFound	Detection
tooManyFaces	Detection
validFace	Valid state
facePoseInvalid	V3 pose (optional)
checkingLighting	V3 lighting pending (optional)
unevenLighting	V3 uneven lighting (optional)
insufficientLight	V3 insufficient light (optional)

The first nine members are required by the FaceStatusTexts type. The V3 members are optional; when they are omitted, the SDK shows its default text.

Android geometry messages for V2 and V3

On Android, V2 and V3 read the position and distance texts from separate options instead of faceStatusTexts. iOS ignores these options and uses faceStatusTexts for all versions. To localize every message on both platforms, set faceStatusTexts and these options:

launch({
  captureConstrains: MBCaptureConstraints.V3,
  showFaceStatusLabel: true,
  faceStatusTexts,
  facePositionStatusText: {
    faceTooFarUp: "Move the phone up",
    faceTooFarDown: "Move the phone down",
    faceTooFarLeft: "Move to the right",
    faceTooFarRight: "Move to the left",
    faceValidPosition: "Hold still",
    faceNotFound: "Face not found",
  },
  faceDistanceStatusText: {
    faceTooFarAway: "Move closer",
    faceTooClose: "Move farther away",
    faceValidDistance: "Hold still",
    faceNotFound: "Face not found",
  },
  cameraPermissionAlert,
});

Option	Members	Android use
facePositionStatusText	faceTooFarUp, faceTooFarDown, faceTooFarLeft, faceTooFarRight, faceValidPosition, faceNotFound	V2 and V3 position
faceDistanceStatusText	faceTooFarAway, faceTooClose, faceValidDistance, faceNotFound	V2 and V3 distance
facePoseStatusText	faceExcessiveYaw, faceExcessivePitch, faceExcessiveRoll, faceValidPose, faceNotFound	V2 pose; V3 pose when set, otherwise faceStatusTexts.facePoseInvalid

With V3, the lighting texts always come from faceStatusTexts. With V1, Android uses faceStatusTexts for all messages.

Customize the camera permission alert

cameraPermissionAlert is shown when camera access has been denied:

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

Keep instructions short and actionable. When several checks fail, guide the user through geometry first and lighting second.