JavaScript Liveness¶

The Liveness module provides facial liveness detection for web applications. It verifies that a real person is present during identity verification, preventing spoofing attacks using photos or videos.

Two liveness providers are available: Face01 and Face06.

startLiveness(options)¶

Starts a liveness session using the specified provider.

await biometrid.startLiveness(options);

ILivenessOptions¶

Parameter	Type	Required	Description
`processId`	`string`	yes	The process ID to associate with the liveness session
`provider`	`string`	yes	Liveness provider to use: `"face01"` or `"face06"`
`liveness`	`any`	no	Provider-specific liveness parameters
`data`	`any`	no	Additional data passed to the provider
`settings`	`ILivenessConfig`	no	Provider configuration — see ILivenessConfig
`compare`	`boolean`	no	Whether to compare the liveness result against a reference
`encryptionKey`	`string`	no	Encryption key used for securing liveness data
`container`	`HTMLElement \\| string`	no	DOM element or CSS selector where the liveness widget will be rendered

Providers¶

Face01Face06

style and i18n are properties of options.liveness when using the Face01 provider.

Style¶

Full style customization object:

style: {
  overlayCustomization: {
    backgroundColor: "#ffffff",
    brandingImage: "path/to/logo.png"
  },
  frameCustomization: {
    backgroundColor: "#ffffff",
    borderColor: "#cccccc",
    borderWidth: 2,
    borderCornerRadius: 8,
    shadow: ""
  },
  ovalCustomization: {
    strokeColor: "#00838f",
    progressColor1: "#00838f",
    progressColor2: "#00838f",
    progressStrokeWidth: 5,
    strokeWidth: 5
  },
  feedbackCustomization: {
    backgroundColor: "#00838f",
    textColor: "#ffffff",
    textFont: "",
    cornerRadius: 8,
    shadow: ""
  },
  cancelButtonCustomization: {
    customImage: "",
    location: "top_left"
  },
  guidanceCustomization: {
    backgroundColors: "#ffffff",
    foregroundColor: "#222222",
    headerFont: "",
    subtextFont: "",
    readyScreenHeaderFont: "",
    readyScreenSubtextFont: "",
    retryScreenHeaderFont: "",
    retryScreenSubtextFont: "",
    buttonFont: "",
    buttonTextNormalColor: "#ffffff",
    buttonBackgroundNormalColor: "#00838f",
    buttonTextHighlightColor: "#ffffff",
    buttonBackgroundHighlightColor: "#006670",
    buttonTextDisabledColor: "#ffffff",
    buttonBackgroundDisabledColor: "#aaaaaa",
    buttonBorderColor: "",
    buttonBorderWidth: 0,
    buttonCornerRadius: 8,
    readyScreenHeaderTextColor: "#222222",
    readyScreenSubtextTextColor: "#555555",
    retryScreenHeaderTextColor: "#222222",
    retryScreenSubtextTextColor: "#555555",
    retryScreenImageBorderColor: "#00838f",
    retryScreenImageBorderWidth: 2,
    retryScreenImageCornerRadius: 8,
    retryScreenOvalStrokeColor: "#00838f",
    retryScreenSlideshowImages: [],
    retryScreenSlideshowInterval: 2000,
    enableRetryScreenSlideshowShuffle: true
  },
  resultScreenCustomization: {
    backgroundColors: "#ffffff",
    foregroundColor: "#222222",
    messageFont: "",
    showUploadProgressBar: true,
    uploadProgressFillColor: "#00838f",
    uploadProgressTrackColor: "#dddddd",
    animationRelativeScale: 1.0,
    successAnimationForegroundColor: "#00838f",
    successAnimationBackgroundColor: "#ffffff",
    unsuccessAnimationForegroundColor: "#dd4444",
    unsuccessAnimationBackgroundColor: "#ffffff"
  },
  securityWatermarkImage: "facetec"
}

i18n¶

Internationalization strings object:

i18n: {
  feedbackCenterFace: "Center Your Face",
  feedbackFaceNotFound: "Keep Face in Oval",
  feedbackFaceNotLookingStraightAhead: "Look Straight Ahead",
  feedbackFaceNotUpright: "Hold Your Head Straight",
  feedbackHoldSteady: "Hold Steady",
  feedbackMovePhoneAway: "Move Away",
  feedbackMoveAwayWeb: "Move Away",
  feedbackMovePhoneCloser: "Move Closer",
  feedbackMovePhoneToEyeLevel: "Move Phone To Eye Level",
  feedbackMoveToEyeLevelOfCamera: "Move Eyes to Camera Level",
  feedbackUseEvenLighting: "Use Even Lighting",
  instructionsHeaderReady: "Liveness Check",
  instructionsMessageReady: "Position your face in the oval and hold still.",
  instructionsHeaderRetry: "Unacceptable Image",
  instructionsMessageRetry: "Please try again.",
  retryInstructionMessage1: "Place Your Face Straight in the Oval",
  retryInstructionMessage2: "Remove Obstructions",
  resultSuccessMessage: "Liveness Confirmed",
  resultUploadingMessage: "Uploading...",
  resultFailedMessage: "Please Try Again",
  resultTryAgainMessage: "Try Again",
  feedbackTooMuchBackgroundInFrame: "Too Much Background Visible",
  feedbackTooBright: "Decrease Lighting",
  feedbackTooDark: "More Lighting Needed"
}

Response¶

startLiveness resolves with an object whose shape depends on the outcome.

Success:

Field	Type	Description
`sessionId`	`string`	The session identifier
`auditTrail`	`array`	Audit trail images captured during the session
`faceScan`	`string`	The encrypted face scan data
`results`	`any`	Present if the server returned a response. Contains `response.results` if available, otherwise the full `response` object

{
  "sessionId": "abc123",
  "auditTrail": ["..."],
  "faceScan": "...",
  "results": { "..." }
}

Failure — the promise rejects with an error string indicating the reason:

`error` value	Description
`"LIVENESS_ERROR"`	The liveness check failed
`"NO_ATTEMPTS"`	The user has exhausted all allowed attempts
`"USER_ENROLL"`	The user enrollment step failed

translations is a property of options.liveness when using the Face06 provider.

translations¶

translations: {
  camera_next_button_aria: "camera_next_button_aria",
  canceled_user: "canceled_user",
  client_camera: "client_camera",
  close_button_aria: "close_button_aria",
  error: "error",
  error_asset_fetch: "error_asset_fetch",
  error_asset_fetch_message: "error_asset_fetch_message",
  error_camera: "error_camera",
  error_camera_in_use: "error_camera_in_use",
  error_camera_in_use_message: "error_camera_in_use_message",
  error_camera_message: "error_camera_message",
  error_camera_not_supported: "error_camera_not_supported",
  error_camera_not_supported_message: "error_camera_not_supported_message",
  error_camera_permission_denied: "error_camera_permission_denied",
  error_camera_permission_denied_message: "error_camera_permission_denied_message",
  error_client: "error_client",
  error_consent: "error_consent",
  error_device_motion_denied: "error_device_motion_denied",
  error_device_motion_denied_message: "error_device_motion_denied_message",
  error_device_motion_unsupported: "error_device_motion_unsupported",
  error_device_motion_unsupported_message: "error_device_motion_unsupported_message",
  error_fullscreen_change: "error_fullscreen_change",
  error_fullscreen_change_message: "error_fullscreen_change_message",
  error_integration_unloaded: "error_integration_unloaded",
  error_invalid_token: "error_invalid_token",
  error_invalid_token_message: "error_invalid_token_message",
  error_network: "error_network",
  error_no_camera: "error_no_camera",
  error_no_camera_message: "error_no_camera_message",
  error_no_face_found: "error_no_face_found",
  error_no_face_found_message: "error_no_face_found_message",
  error_not_supported: "error_not_supported",
  error_not_supported_message: "error_not_supported_message",
  error_server: "error_server",
  error_server_message: "error_server_message",
  error_token_timeout: "error_token_timeout",
  error_token_timeout_message: "error_token_timeout_message",
  error_too_many_requests: "error_too_many_requests",
  error_too_many_requests_message: "error_too_many_requests_message",
  error_transaction_canceled: "error_transaction_canceled",
  error_user_timeout: "error_user_timeout",
  failed: "failed",
  failure_eyes_closed: "failure_eyes_closed",
  failure_face_too_close: "failure_face_too_close",
  failure_face_too_far: "failure_face_too_far",
  failure_misaligned_face: "failure_misaligned_face",
  failure_background_issue: "failure_background_issue",
  failure_device_issue: "failure_device_issue",
  failure_device_restart: "failure_device_restart",
  failure_eyewear: "failure_eyewear",
  failure_lighting_issues: "failure_lighting_issues",
  failure_face_not_found: "failure_face_not_found",
  failure_frames_blurry: "failure_frames_blurry",
  failure_motion_issue: "failure_motion_issue",
  failure_multiple_faces: "failure_multiple_faces",
  failure_network_problem: "failure_network_problem",
  failure_obscured_face: "failure_obscured_face",
  failure_sunglasses: "failure_sunglasses",
  failure_too_bright: "failure_too_bright",
  failure_too_dark: "failure_too_dark",
  failure_too_much_movement: "failure_too_much_movement",
  failure_processing_fault: "failure_processing_fault",
  failure_system_error: "failure_system_error",
  failure_timeout: "failure_timeout",
  failure_rejected: "failure_rejected",
  failure_user_not_found: "failure_user_not_found",
  failure_unknown: "failure_unknown",
  iproov_ready_button: "iproov_ready_button",
  iproov_ready_title: "iproov_ready_title",
  iproov_success: "iproov_success",
  label_camera_selector: "label_camera_selector",
  label_secured_by_iproov_aria: "label_secured_by_iproov_aria",
  language_file: "language_file",
  logo_aria: "logo_aria",
  passed: "passed",
  progress_assessing_genuine_presence: "progress_assessing_genuine_presence",
  prompt_genuine_presence_scan_completed: "prompt_genuine_presence_scan_completed",
  progress_assessing_liveness: "progress_assessing_liveness",
  progress_confirming_identity: "progress_confirming_identity",
  progress_creating_identity: "progress_creating_identity",
  progress_finding_face: "progress_finding_face",
  progress_identifying_face: "progress_identifying_face",
  progress_loading: "progress_loading",
  progress_streaming: "progress_streaming",
  prompt_align_face_accessibility: "prompt_align_face_accessibility",
  prompt_align_face_accessibility_desktop: "prompt_align_face_accessibility_desktop",
  prompt_connecting: "prompt_connecting",
  prompt_genuine_presence_align_face: "prompt_genuine_presence_align_face",
  prompt_get_ready: "prompt_get_ready",
  prompt_grant_permission: "prompt_grant_permission",
  prompt_grant_permission_message: "prompt_grant_permission_message",
  prompt_grant_permission_button: "prompt_grant_permission_button",
  prompt_hold_still: "prompt_hold_still",
  prompt_kiosk_align_face: "prompt_kiosk_align_face",
  prompt_kiosk_keep_still: "prompt_kiosk_keep_still",
  prompt_liveness_align_face: "prompt_liveness_align_face",
  prompt_liveness_no_target: "prompt_liveness_no_target",
  prompt_liveness_scan_completed: "prompt_liveness_scan_completed",
  prompt_loading: "prompt_loading",
  prompt_rotate_portrait: "prompt_rotate_portrait",
  prompt_rotate_portrait_short: "prompt_rotate_portrait_short",
  prompt_scanning: "prompt_scanning",
  prompt_too_close: "prompt_too_close",
  prompt_too_far: "prompt_too_far",
  prompt_too_high: "prompt_too_high",
  prompt_too_left: "prompt_too_left",
  prompt_too_low: "prompt_too_low",
  prompt_too_right: "prompt_too_right",
  prompt_genuine_presence_too_bright: "prompt_genuine_presence_too_bright",
  prompt_genuine_presence_too_dark: "prompt_genuine_presence_too_dark"
}

Response¶

startLiveness resolves with an object whose shape depends on the outcome.

Field	Type	Description
`status`	`boolean`	`true` if liveness passed, `false` otherwise
`type`	`string`	Present on failure. Always `"failed"`
`reasons`	`array`	Present on failure. One or more feedback entries explaining why the check failed
`reasons[].feedback_code`	`string`	Machine-readable code identifying the failure reason (e.g. `"lighting_issues"`, `"motion_issue"`)
`reasons[].localized_description`	`string`	Human-readable description of the failure reason, suitable for display to the user
`error`	`string`	Present on failure. `"LIVENESS_ERROR"` when attempts remain; `"NO_ATTEMPTS"` when the user has exhausted all attempts

Success — status is true and no other failure fields are present:

{
  "status": true,
  "..."
}

Failure (attempts remaining) — status is false and error is "LIVENESS_ERROR":

{
  "status": false,
  "type": "failed",
  "reasons": [
    {
      "feedback_code": "lighting_issues",
      "localized_description": "Make sure your face is well lit and free from glare"
    }
  ],
  "error": "LIVENESS_ERROR"
}

Failure (no attempts remaining) — status is false and error is "NO_ATTEMPTS":

{
  "status": false,
  "type": "failed",
  "reasons": [
    {
      "feedback_code": "motion_issue",
      "localized_description": "Align your face in the oval and then try to keep still"
    }
  ],
  "error": "NO_ATTEMPTS"
}

Note

reasons is only present on failure and may contain multiple entries if more than one issue was detected.