For the complete documentation index, see llms.txt. This page is also available as Markdown.

Face Liveness & Face Authenticator

Enables integration of facial verification into applications, providing a secure and seamless user authentication experience.

Face Liveness & Face Authenticator

The CafFaceLiveness Web SDK provides facial liveness detection with support for multiple providers, each offering different features and capabilities. The SDK automatically routes to the appropriate provider based on your mobile token configuration.

Supported providers

Provider
Description

Caf

Liveness 2D validation using Caf's solutions

FaceTec

FaceTec's 2D liveness detection technology

iProov

Liveness detection with GPA and LA technologies

Payface

Payface's facial verification technology

Quick start

1. Installation

Include the SDK script in your HTML file:

<script src="https://repo.combateafraude.com/javascript/release/caf-face-liveness/0.18.0/caf-face-liveness_0.18.0.umd.js"></script>

Or include it via JavaScript:

const sdkScript = document.createElement("script");
sdkScript.src =
  "https://repo.combateafraude.com/javascript/release/caf-face-liveness/0.18.0/caf-face-liveness_0.18.0.umd.js";
document.body.appendChild(sdkScript);

You can also download the SDK file from the Caf CDN and then include it directly in your project. This is useful if you prefer to host the SDK file or if you want to avoid loading it from a CDN.

2. Basic usage

Complete example

Here's a ready-to-use HTML example:

SDK reference

Initialization

Initializes the SDK with the provided configuration.

Init parameter
Type
Required or Optional
Description

sdkToken

string

Required

SDK token for authentication

personId

string

Required

Unique identifier for the user

config

object

Optional

SDK configuration options.

Check the Configuration options section for more details.

customization

object

Optional

Appearance and text customization options.

Check the Customization options section for more details.

Configuration options

Config parameter
Type
Required or Optional
Description
Provider Support

htmlContainerId

string

Required (iProov)

ID of the HTML container for the SDK UI. Required only when the selected provider is iProov.

iProov

enableDebugMode

boolean

Optional

Enable debug mode for development

All Providers

performFaceAuthentication

boolean

Optional

Whether to perform face authentication along with liveness detection

Enabling face authentication requires a previously registered face for the given personId. Check the Face Authentication section for more details.

All Providers

language

string

Optional

Language for the UI. Supported values: "en_US", "es_MX", "pt_BR"

All Providers

disableAnalytics

boolean

Optional

Disable analytics tracking

All Providers

cameraPreviewFilter

string

Optional

Filter for the camera preview. Supported values: "shaded", "classic", "vibrant", "clear", "blur"

When using the "clear" camera filter with GPA enabled, the SDK will not be able to be executed and will throw an error. If GPA is enabled, make sure to use a different camera filter option.

iProov

reverseProxy

object

Optional

Reverse proxy configuration.

Check the Reverse proxy configuration section for more details.

iProov

Customization options

Customization parameter
Type
Description
Provider Support

appearance.captureButtonIcon

string

URL of the capture button icon

Caf, FaceTec

appearance.captureIconSize

string

Size of the capture button icon

Caf, FaceTec

appearance.captureButtonColor

string

Color of the capture button

Caf, FaceTec

appearance.fontFamily

string

Font family for the UI

Caf, FaceTec

loader.enabled

boolean

Show a loading overlay (spinner only) while the iProov capture UI loads. Default: false

iProov

loader.color

string

Spinner color. If omitted, falls back to startButton.backgroundColor, then #666666.

iProov

startButton.label

string

Start button text

iProov

startButton.color

string

Start button text color

iProov

startButton.backgroundColor

string

Start button background color

iProov

startButton.borderRadius

string

Start button border radius

iProov

startButton.border

string

Start button border style

iProov

startButton.padding

string

Start button padding

iProov

startButton.margin

string

Start button margin

iProov

messages.title

string

Title text for the UI

Caf, FaceTec

messages.loading

string

Loading message during capture

Caf, FaceTec

messages.errors.captureFailed

string

Error message when capture fails

Caf, FaceTec

Handling initialization errors

Errors that can occur during the init() method:

Error name
Description

CafSdkInitError

An error occurred during the SDK initialization (e.g. missing required parameters).

CafSdkSessionError

Error while creating session to perform liveness or face authentication. Check if the token provided is valid and not expired.

CafUnknownError

An unknown internal error occurred

Any other unexpected errors will be thrown as JavaScript default Error class.

Example:

Running

Executes the face liveness detection process.

Run parameter
Type
Required or Optional
Description

options

object

Optional

Options for the run method.

Check the Run options section for more details.

Run options

Run option
Type
Description

cancelPromise

Promise<void>

Promise that resolves when the operation should be cancelled.

onCaptureProcessingStart

function

Callback that is called when capture processing starts.

onCaptureProcessingEnd

function

Callback that is called when capture processing ends.

Returns

The method returns a Promise<string> that resolves with a JWT token string containing the execution result.

Important: The fields described below are contained in the decoded payload of this JWT token. You must decode and verify the JWT token to access these fields.

JWT payload structure

After decoding the JWT, the payload contains an object with the following properties:

  • imageUrl (string): Temporary URL of the captured image

  • isAlive (boolean): Indicates if the liveness check was successful

  • isMatch (boolean): Indicates if the face authentication was successful (if enabled)

  • sessionId (string): Unique session identifier for the execution

  • personId (string): The person ID used for the execution

Handling run errors

Errors that can occur during the run() method:

Error name
Description

CafCameraPermissionError

Error getting camera permission

CafCameraPermissionDeniedError

Camera permission denied by the user

CafCameraUnsupportedError

Camera is not supported by the browser/device

CafSdkRunError

An error occurred while running the SDK

CafSdkCanceledError

SDK run canceled by the user or cancelPromise

CafFaceLivenessError

Error during liveness validation

CafFaceAuthenticationError

Error during face authentication

CafFaceNotFoundError

No registered face was found for the user

CafUnknownError

An unknown internal error occurred

CafUnsupportedError

SDK is not supported on this device, browser or operating system.

CafDeviceMotionPermissionDeniedError

Device motion permission denied by the user.

Any other unexpected errors will be thrown as JavaScript default Error class.

Example:

Dispose

Cleans up SDK resources. It should be called when the SDK is no longer needed.

Example

Products

Face Liveness

The SDK provides face liveness detection to ensure that the user is alive and present during the process.

How Face Liveness works

  1. Camera access: The SDK requests access to the user's camera

  2. Face capture: The SDK captures a photo of the user's face

  3. Liveness validation: The SDK analyzes the captured face to check if the user is alive

  4. Result: The JWT token payload includes the isAlive field indicating if the user is alive

Face Liveness result interpretation

isAlive
Meaning

true

✅ User is alive and liveness check passed

false

❌ Liveness detection failed

Face Authentication

The SDK supports face authentication to be performed in addition to liveness detection. When enabled, after liveness validation, the SDK will compare the captured face against a previously registered face to verify the user's identity.

To enable face authentication, set the performFaceAuthentication parameter to true during SDK initialization:

How Face Authentication works

  1. Face registration: The user's face must be previously registered using the personId

  2. Face Liveness: The SDK captures the user's face and performs liveness validation

  3. Face Authentication: The captured face is compared against the registered face for the given personId

  4. Result: The JWT token payload includes the isMatch field indicating if there is a match with the registered face

Face Authentication result interpretation

isAlive
isMatch
Meaning

true

true

✅ User is alive and face matches registered face

true

false

⚠️ User is alive but face does not match

false

-

❌ Liveness detection failed

Reverse proxy configuration

If you choose to use a reverse proxy, you must configure it to properly forward requests to the appropriate endpoints. Below is the mapping for redirection:

  • /v1/https://web.us.prd.caf.io/bff/

  • /std/https://us.rp.secure.iproov.me/

  • /std/ws/wss://us.rp.secure.iproov.me/ws/

  • /assets/https://cdn.iproov.app/

Reverse proxy configuration example

Supposing your domain is my.proxy.io, your SDK configuration would look like this:

Note: The paths provided in this example are just for reference. You can configure your proxy and paths according to your best practice standards.

Integration options

To perform integration through an iframe, camera and fullscreen permissions must be provided.

iOS Sensor Permission Requirements

Recent iOS 26 releases introduced changes that broke the motion-sensor permission flow for iframe integrations. The workaround that relied on a pre-flight permission button stopped working and has been deprecated.

Starting in version 0.14.1, the bundled iProov provider has been upgraded, which natively handles the new iOS requirements when the Web SDK runs inside an iframe. The only supported path is to upgrade your integration to CafFaceLiveness 0.14.1 (or newer). Earlier versions will not work on the latest iOS 26 devices, even if you keep the previous workaround in place.

After upgrading, you can embed the iframe exactly as shown above. No extra buttons or custom permission flows are necessary.

To use the SDK through a Webview, camera permission must be granted in your native application.

Example implementation on Android:

AndroidManifest.xml

MainActivity

Sample android project for webview implementation, in addition it is necessary to be able to open the application in full screen, the example shows how to configure it correctly.

SDK events

The SDK dispatches various events during its lifecycle to be able to handle different scenarios of the liveness detection process and provide a better user experience.

Listen for events using the DOM event listener pattern:

Currently, events are only available when using the iProov provider. Event support for other providers is planned for future releases.

Available events

Event Name
Description
Provider Support

started

Liveness detection process begins

iProov

sdk-button-ready

SDK start button is ready for interaction

iProov

sdk-button-clicked

User clicked the SDK start button

iProov

streaming

Streaming has started, remaining in fullscreen

iProov

streamed

End of streaming and exited fullscreen

iProov

passed

Liveness detection is successful

iProov

failed

Liveness detection fails

iProov

canceled

User cancels the process

iProov

error

An error occurred during the process

iProov

unsupported

Browser does not support the SDK

iProov

Event details: iProov "failed" event

When liveness detection fails, the failed event provides specific feedback:

The table below summarizes the possible failed event details:

Feedback
Reason
LA
GPA

eyes_closed

Keep your eyes open

face_too_far

Move your face closer to the screen

face_too_close

Move your face farther from the screen

misaligned_face

Keep your face in the oval

multiple_faces

Ensure only one person is visible

obscured_face

Remove any face coverings

sunglasses

Remove sunglasses

too_bright

Ambient light too strong or screen brightness too low

too_dark

Your environment appears too dark

too_much_movement

Please keep still

unknown

Try again

Event details: iProov "error" event

When an error occurs during the liveness detection process, the error event provides additional details about the error:

The table below summarizes the possible error event details:

Feedback
Reason

unknown

Try again

client_camera

There was an error getting video from the camera

client_error

An unknown error occurred

error_asset_fetch

Unable to fetch assets

error_camera

The camera cannot be started for unknown reasons

error_camera_in_use

The camera is already in use and cannot be accessed

error_camera_not_supported

The camera resolution is too small

error_camera_permission_denied

The user denied our camera permission request

error_device_motion_denied

The user denied our device motion permission request

error_device_motion_unsupported

Your device does not seem to fully report device motion

error_fullscreen_change

Exited fullscreen without completing iProov

error_invalid_token

The sdk internal token is invalid

error_network

Network error

error_no_face_found

No face could be found

error_not_supported

The device or integration isn't able to run the Web SDK

error_server

An error occurred when communicating with iProov's servers

error_token_timeout

The token was claimed too long after being created

error_too_many_requests

The service is under high load and the user must try again

error_user_timeout

The user started the claim but did not stream in time

integration_unloaded

The SDK was unmounted from the DOM before it finished

sdk_unsupported

The SDK has passed end of life and is no longer supported

Release notes

CafFaceLiveness v0.18.0

Features

  • iProov loading overlay: Added an opt-in loading overlay (spinner only) that covers the iProov capture UI while assets load, avoiding a blank screen between run() and the capture window. Enable it with customization.loader.enabled.

Improvements

  • Dependencies updated: Updated Payface provider with important security enhancements and improvements to facial capture.

CafFaceLiveness v0.17.2

Fixes

  • iProov provider: Fixed zoom behavior issue on tablets in landscape mode, ensuring proper display scaling across all devices.

  • Payface provider: Extended SDK loading timeout window and added diagnostic logging to improve initialization reliability on slow network connections.

CafFaceLiveness v0.17.1

Improvements

  • Dependencies updated: Updated Payface provider with important security enhancements and improvements to facial capture.

Fixes

  • iProov provider: Fixed an issue where the facial capture screen was not displayed correctly in fullscreen on iOS mobile devices.

CafFaceLiveness v0.17.0

New Features

  • Specific handling for unregistered face: Added CafFaceNotFoundError. When no face is registered for the given personId, the SDK now throws this specific error instead of a generic one, significantly improving error handling on the frontend.

Improvements

  • Better handling of user failure errors, including face not found, camera permission denied, and device motion errors.

  • Dependencies updated: Updated internal dependencies to enhance security and stability.

  • Logging: Enhanced internal logging and analytics for better debugging and monitoring.

CafFaceLiveness v0.16.0

Features

  • Start button click event: Added a new sdk-button-clicked event, dispatched when the user clicks the iProov start button. Use it alongside the existing sdk-button-ready event to track user engagement during the verification flow.

Fixes

  • Fixed an error that could occur when calling dispose() after the liveness flow had already completed.

CafFaceLiveness v0.15.1

Improvements

  • Dependencies updated: Updated iProov provider and internal dependencies to enhance performance and stability.

  • Error handling: Improved error handling for the iProov provider.

  • Logging: Enhanced internal logging and analytics for better debugging and monitoring.

Features

  • Analytics: Added new events to the internal analytics system to better track browser compatibility and support.

CafFaceLiveness v0.14.3

Fixes

  • Added errors for unsupported browsers and device motion denied permissions: CafUnsupportedError and CafDeviceMotionPermissionDeniedError.

  • Improved analytics by adding more specific logs for errors and failures using iProov provider.

CafFaceLiveness v0.14.2

Enhanced SDK Analytics

  • Improved logging by adding information about capture attempts and specific quality metrics.

  • Added abandonment tracking: when a user abruptly leaves the journey before completion, such as closing the browser window, minimizing the tab, or navigating to a different page, the SDK will track this event to provide better insights about the user journey and possible reasons for abandonment.

CafFaceLiveness v0.14.1

Fixes

  • Upgraded the iProov provider engine, fixing iframe launches on devices running iOS 26.x and eliminating the previous motion-sensor permission workaround.

CafFaceLiveness v0.14.0

Improvements

This version includes an update to our Payface provider that enhances the user experience, leading to higher success rates. Key improvements include:

  • Improved user guidance: New lighting alerts help users find the ideal conditions for a successful capture.

  • Enhanced accessibility: Clearer instructions create a smoother and more inclusive user journey.

  • More responsive experience: Canceling the capture is now faster, improving usability.

Features

  • Device fingerprinting: Collects device fingerprint during verification to strengthen fraud prevention and risk analysis. Disabled by default; contact our team to enable.

CafFaceLiveness v0.13.0

  • Simplified, name-based error handling: Consolidated error types into clear, descriptive names to improve consistency.

  • Dependencies updated: Enhanced SDK stability, security, and compatibility.

CafFaceLiveness v0.12.1

  • More robust image capture system: The SDK now features an intelligent fallback mechanism, ensuring that image capture works more reliably across different devices and browsers, even in scenarios with technical limitations.

  • Enhanced image quality validation: New validations have been implemented to prevent low-quality images, increasing the reliability of the capture process.

  • Performance optimization on initialization: The SDK initialization process is now faster and lighter, reducing the waiting time for the user.

  • Improved visual feedback: New events and status messages allow the user interface to more accurately inform the user about the capture moment.

CafFaceLiveness v0.12.0

Features

  • Enhanced Camera selection: Intelligent label/facing-mode detection with heuristic best-camera selection (Caf and FaceTec).

  • Unified discovery and stream reuse: Single user media discovery with stream reuse and automatic camera fallback, reducing permission prompts and speeding up initialization (Caf and FaceTec).

  • Faster camera switching: Near-instant camera switching with cached selections (Caf and FaceTec).

CafFaceLiveness v0.11.2

Improvements

Enhanced user experience during interruptions: Improved Face Liveness behavior when users experience focus changes or interruptions during face capture sessions using Payface provider.

  • Added pause/resume functionality when browser focus is lost (tab switching, minimizing, etc.)

  • Users can now recover from interruptions instead of restarting the entire capture process

  • Reduced session abandonment rates due to accidental interruptions

CafFaceLiveness v0.11.1

Fixes

Improved device compatibility: Enhanced Face Liveness stability and compatibility across various devices and browsers, significantly reducing session failures and improving user experience during the face verification process using Payface provider.

  • Fixed compatibility issues that were causing "unsupported" errors on certain devices

  • Improved camera initialization reliability across different mobile devices and browsers

  • Reduced abandonment rates during Face Liveness sessions

CafFaceLiveness v0.11.0

Features

Improved camera initialization: Refactored camera initialization when using Caf or FaceTec providers by moving camera setup from SDK initialization to execution phase, resulting in faster initialization and better resource management.

Fixes

  • Fixed an issue where the camera stream wasn't playing automatically when initializing the SDK inside a mobile WebView.

CafFaceLiveness v0.10.1

Fixes

  • Ensures the SDK closes properly after capture errors when using the Caf or FaceTec providers, preventing inconsistent states and allowing the user to retry the process.

CafFaceLiveness v0.10.0

Features

Enhanced analytics tracking: Improved analytics events tracking, providing better error monitoring and debugging capabilities of the SDK.

Fixes

  • Fixed camera startup failures and fullscreen overlay issues when using Caf or FaceTec providers.

  • Fixed reverse proxy configuration to properly forward requests to the desired endpoints.

CafFaceLiveness v0.9.0

Features

  • Fullscreen mode: Enable fullscreen mode when using Caf or FaceTec providers to enhance user experience.

  • Payface improvements: Updated Payface provider to improve observability and Webview compatibility.

CafFaceLiveness v0.7.3

Fixes

Fixed an issue where the SDK was not enabling face authentication when using the Payface provider. The SDK now correctly performs face authentication when the performFaceAuthentication option is set to true during initialization.

CafFaceLiveness v0.7.2

Introducing CafFaceLiveness, a Web SDK for facial liveness detection and authentication in web applications.

Features

  • Face Liveness Detection: Real-time validation to ensure user presence

  • Face Authentication: Optional identity verification against registered faces

  • Multi-Provider Support: Automatic routing between Caf, FaceTec, iProov, and Payface providers

  • Flexible Configuration: Customization options for UI and behavior

  • Multi-Language: Built-in support for English, Spanish, and Portuguese

  • Reverse Proxy: Secure API traffic through reverse proxy configuration

Note: This is the initial release of the CafFaceLiveness Web SDK. Future versions will include additional features, improvements, and expanded provider support.

Last updated