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
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);2. Basic usage
Complete example
Here's a ready-to-use HTML example:
SDK reference
Initialization
Initializes the SDK with the provided configuration.
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
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
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
Important: Starting from version 0.13.0, the SDK's error handling has changed. Review and update your integration to align with the new error names and behavior.
Errors that can occur during the init() method:
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
Example:
Running
Executes the face liveness detection process.
Run options
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 imageisAlive(boolean): Indicates if the liveness check was successfulisMatch(boolean): Indicates if the face authentication was successful (if enabled)sessionId(string): Unique session identifier for the executionpersonId(string): The person ID used for the execution
Handling run errors
Important: Starting from version 0.13.0, the SDK's error handling has changed. Review and update your integration to align with the new error names and behavior.
Errors that can occur during the run() method:
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.
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
Camera access: The SDK requests access to the user's camera
Face capture: The SDK captures a photo of the user's face
Liveness validation: The SDK analyzes the captured face to check if the user is alive
Result: The JWT token payload includes the
isAlivefield indicating if the user is alive
Face Liveness result interpretation
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
Face registration: The user's face must be previously registered using the
personIdFace Liveness: The SDK captures the user's face and performs liveness validation
Face Authentication: The captured face is compared against the registered face for the given
personIdResult: The JWT token payload includes the
isMatchfield indicating if there is a match with the registered face
Face Authentication result interpretation
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:
Available events
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:
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:
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 withcustomization.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 givenpersonId, 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-clickedevent, dispatched when the user clicks the iProov start button. Use it alongside the existingsdk-button-readyevent 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:
CafUnsupportedErrorandCafDeviceMotionPermissionDeniedError.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
Important for iProov provider: Updating to version 0.14.1 or newer is required for iframe integrations on the latest iOS releases.
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
Breaking change: Error names have changed in v0.13.0. We highly recommend reviewing the SDK Reference section before upgrading to this version to keep compatibility.
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
Last updated

