Skip to main content

Face Camera

The Face Camera component provides a live face capture experience with real-time feedback, automatic capture, and development/production modes.

Properties​

Core Properties​

  • isOpen: Boolean
    Starts or stops the camera. Automatically set to false after capture or error.

  • environment: String
    Defines the mode of operation:

    • production (default): Standard secure mode.
    • development: Enables debugging and relaxed protections.

  • deviceId: String
    Specifies the ID of the camera device to use. The component validates that the provided value matches an available video input. If invalid or omitted, the default/front-facing camera is selected.

  • initializationTimeoutDuration: Number (milliseconds)
    How long the component waits for initialization to finish before timing out. Default: 30000 (30s). If initialization is not completed within this period, a timeout error is raised and the camera fails to start.

  • autoCaptureTimeoutDuration: Number (milliseconds)
    How long the component waits after initialization for an automatic face capture before timing out. Default: 60000 (60s). When the timeout expires, an auto-capture error (code 4) is dispatched and the camera closes automatically. Set to 0 to disable.

  • showBackButton: Boolean
    Controls the visibility of the back button used to exit the camera. Default: true.

  • enableOrientationLock: Boolean
    If true, the component attempts to lock the screen orientation to portrait on supported devices/browsers. Default: false.

Detection Feedback​

  • hints: FaceDetectionHint
    Customizes user guidance messages used by detection feedback. Any fields you omit fall back to sensible defaults.

  • detectionState: FaceDetectionState (read-only)
    Indicates the current detection state. Useful for custom UI logic.

  • detectionText(faceState): Function
    Returns the human-readable guidance message for the provided FaceDetectionState, applying your hints and defaults.

  • isInPreview: Boolean (read-only)
    Indicates whether the component is currently showing a captured image preview.

Text Customization​

The Face Camera component provides comprehensive text customization to support internationalization and branding. There are multiple ways to supply text, with the following precedence (highest to lowest):

  1. uiTexts (recommended)
  2. texts (alternative text customization)
  3. accessibilityTexts (legacy, backward compatibility)
  4. Component defaults

In addition, ARIA labels use their own precedence: ariaLabels → uiTexts (where applicable) → accessibilityTexts (legacy) → defaults.

UI Text Customization (Recommended)​

  • uiTexts: Object
    Allows overriding all user-facing copy used by the component. You may provide a partial object; any missing keys fall back to defaults.

Supported keys:

  • step1Title, step1Description
  • step2Title, step2Description
  • step3Title, step3Description
  • faceInstruction
  • landscapeTitle, landscapeSubtitle
  • landscapeButtonLabel, landscapeButtonAriaLabel
  • orientationErrorMessage
  • deviceOrientationText, landscapeOrientationText, portraitOrientationText

Example:

<live-face-camera id="live-face-camera"></live-face-camera>
<script>
  const liveFaceCamera = document.getElementById('live-face-camera');
  liveFaceCamera.uiTexts = {
    step1Title: 'Step One',
    step1Description: 'Align your face inside the oval',
    orientationErrorMessage: 'Please rotate your device to portrait to continue'
  };
</script>

Alternative Text Customization​

  • texts: Object
    An alternative way to supply user-facing copy (keys are the same as uiTexts). If both uiTexts and texts provide a value for the same key, uiTexts wins.

Accessibility-Specific Customization​

  • ariaLabels: Object
    Supplies ARIA labels for interactive controls. Recognized keys:

    • backButton
    • forcePortraitMode

  • accessibilityTexts: Object (legacy)
    Legacy accessibility strings kept for backward compatibility. Recognized keys include:

    • backButtonAriaLabel
    • placeYourFaceText
    • capturedPhotoText

Note: For the visible “Place your face…” guidance the component resolves text in this order: uiTexts.faceInstruction → uiTexts.step1Description → accessibilityTexts.placeYourFaceText → default.

Text Precedence Example​

// Given the following configuration:
liveFaceCamera.uiTexts = { faceInstruction: 'Center your face' };
liveFaceCamera.texts = { faceInstruction: 'Look straight ahead' };

// The rendered instruction will be:
// "Center your face" (from uiTexts) because uiTexts takes precedence over texts.

Events​

  • BeforeInitializeEventName
    Dispatched before initialization begins (no models loaded yet). Useful to prepare UI state or start timers.

  • InitializeEventName
    Dispatched when the component is initialized and ready.

  • BeforeOpenEventName
    Dispatched when the camera begins to open.

  • OpenEventName
    Dispatched when the camera is fully open.

  • DetectEventName
    Dispatched on each detection. detail.errors contains an array of detection issues (if any).

  • BeforeCaptureEventName
    Dispatched when the capture process begins.

  • CaptureEventName
    Dispatched on successful capture. detail includes:

    • imageBase64: Base64-encoded image string.
    • encryptedFile: Encrypted Blob for verification.

  • CloseEventName
    Dispatched when the camera closes.

  • UserCanceledEventName
    Dispatched when the user taps the back arrow to exit the camera without capturing an image.

  • FailureEventName
    Dispatched on error. detail.error is of type FaceCameraError.

Type Definitions​

type FaceDetectionHint = {
  notInitializedHint?: string;
  initializingHint?: string;
  faceNotFoundHint?: string;
  tooManyFacesHint?: string;
  faceAngleTooLargeHint?: string;
  probabilityTooSmallHint?: string;
  faceTooSmallHint?: string;
  faceCloseToBorderHint?: string;
};

enum FaceDetectionState {
  NotInitialized = 'NOT_INITIALIZED',
  FaceNotFound = 'FACE_NOT_FOUND',
  TooManyFaces = 'TOO_MANY_FACES',
  FaceAngleTooLarge = 'FACE_ANGLE_TOO_LARGE',
  ProbabilityTooSmall = 'PROBABILITY_TOO_SMALL',
  FaceTooSmall = 'FACE_TOO_SMALL',
  FaceCloseToBorder = 'FACE_CLOSE_TO_BORDER',
}

type FaceCameraError = {
  code: number;
  message: string;
};