Getting Started with the SDK

About CafSDK

This technical documentation covers the implementation of CafSDK for React Native, detailing the configuration, initialization, execution of capture flows, and advanced customizations.

Currently, CafSDK integrates two main modules: Face Liveness (FL) and Document Detector (DD), executed sequentially with a unified configuration interface.

What is Face Liveness

It is the module that validates the authenticity of a face captured by a photo application, ensuring that the image corresponds to a real person.

Technical characteristics:

URL configuration for authentication (authBaseUrl) and liveness verification (livenessBaseUrl).
Flags to enable screen capture and debug mode.
Support for multiple authentication providers.

What is Document Detector

It is the module that enables the capture and processing of documents (e.g., ID card, social security card, passport, etc.).

Technical characteristics:

Configuration of a step-by-step flow defined by CafDocumentDetectorFlow for document capture.
Operational parameters, such as timeout, manual capture flags, and other settings.
Possibility of using the camera for framing validations, or document file upload.

Get started with the SDK

Add the dependency

CafSDK supports integration via both JavaScript Package Manager, providing flexibility to choose the dependency manager that best suits your project. This guide explains the necessary steps to add CafSDK to your React Native project and provides details about the available modules.

Requirements for adding

To use the CafSDK modules in React Native, ensure that your project meets the minimum requirements:

React Native

Requirement

Version

React Native Version

0.73.x

Node.js

Android

Requirement

Version

Android SDK API - minimum version (minSdk)

Android SDK API - compile version (compileSdk)

Kotlin

1.9.10

Gradle

8.4

Android Gradle Plugin (AGP)

8.3.2

iOS

Requirement

Version

iOS Deployment Target

13.0

Xcode

16.2

Swift

5.10

Steps to add

React Native

Step 1 - Add the dependency

Use your preferred JavaScript package manager (npm or yarn) to install the desired CafSDK modules. Below are the commands to install the main modules and their optional UI interfaces.

Note: The -ui packages allow advanced visual customization.

CafFaceLiveness

Install the CafFaceLiveness module:

npm install @caf.io/react-native-face-liveness

If you want a customized interface.

npm install @caf.io/react-native-face-livenes-ui

DocumentDetector

Install the DocumentDetector module:

npm install @caf.io/react-native-document-detector

If you want a customized interface.

npm install @caf.io/react-native-document-detector-ui

Android

Step 1 - Add the Maven repository

Note: This step is only required if you’re building with Expo, skip it for a React Native CLI project.

In this step, you need to inform Gradle where to locate the CafSDK artifacts and additional dependencies that may be used (such as those related to Caf Face Liveness, DocumentDetector or FingerPrintJS).

To do this, configure the project's settings.gradle.kts file (usually located at the root level), including the following repositories:

Caf Repository: where the CafSDK artifacts are hosted.
iProov Repository: required if you are using the CafFaceLiveness module, which depends on iProov artifacts for secure processing.
FingerPrintJS Repository: internal dependency of the modules.
JitPack: for dependencies hosted via JitPack (Github).

Configuration example:

repositories {
    // Caf Repository
    maven { url = uri("https://repo.combateafraude.com/android/release") }
    
    // iProov Repository
    maven { url = uri("https://raw.githubusercontent.com/iProov/android/master/maven/") }
    
    // FingerPrintJS Repository
    maven { setUrl("https://maven.fpregistry.io/releases") }
    
    // JitPack
    maven { setUrl("https://jitpack.io") }
}

More details

Flexibility: this configuration allows the project to download all necessary dependencies from different sources, ensuring compatibility and updated versions.
Maintenance: if there are updates to the repositories or changes in the publication structure, simply update this section to reflect the new URLs.
Context: the inclusion of repositories is done only once at the project level, ensuring that all modules can access the necessary artifacts.

iOS

Step 1 - Install iOS native dependencies

After installing the SDK modules, you need to install the native iOS dependencies using CocoaPods.

Navigate to the ios/ directory of your React Native project and run:

pod install

This step is mandatory for iOS to correctly link the native modules and their required dependencies.
Always re-run pod install whenever native dependencies are added or updated.

How to initialize the SDK

This guide explains how to initialize the CafSDK on iOS. It covers the requirements, permissions, global configuration, module-specific configuration, and builder initialization.

Permissions

Android

For the modules to operate correctly, you must declare the following permissions in your AndroidManifest.xml:

For Face Liveness

Permission

Description

Necessity

android.permission.CAMERA

Allows access to the camera to capture images and perform face verification (liveness).

Mandatory.

android.permission.INTERNET

Allows communication with authentication and verification services (HTTPS/WSS).

Mandatory.

For Document Detector

Permission

Description

Necessity

android.permission.CAMERA

Allows access to the camera to capture document. images.

Only for capture

android.permission.INTERNET

Allows captured images to be sent to servers for processing and validation.

Mandatory.

android.permission.READ_EXTERNAL_STORAGE

Allows access to stored files and images for processing, if necessary.

Only for upload.

iOS

For the SDK modules to function correctly, you must declare the following permissions in your Info.plist:

For Face Liveness:

Permission

Description

Necessity

NSCameraUsageDescription

Allows access to the camera to capture images and perform face verification (liveness).

Mandatory.

Network access

Allows communication with authentication and verification services (HTTPS/WSS).

Mandatory.

For Document Detector:

Permission

Description

Necessity

NSCameraUsageDescription

Allows access to the camera to capture document. images.

Only for capture

Network access

Allows captured images to be sent to servers for processing and validation.

Mandatory.

NSPhotoLibraryUsageDescription

Allows access to stored files and images for processing, if necessary.

Only for upload.

Configurations

The initialization process is divided into two parts: global configuration and module-specific configuration.

Global configuration

Using the useCafSdk hook for create a object, which serves as the central container for all configurations. This configuration defines the execution order of the modules and the visual identity (through a color configuration).

Essential parameters

mobileToken: token that authenticates the request and ensures that only authorized clients start the flow.
personId unique user identifier for which the flow will be executed.
environment: defines the execution environment, for example, CafEnvironment.PROD for production. This enables switching between development, homologation, and production environments.
presentationOrder: defines the sequence in which the modules will be executed. This order is crucial to ensure that the capture flow follows the business logic defined by your project.
- For example, if the flow requires the document to be captured before liveness verification, the order should place the Document Detector module before Face Liveness.
- Important: depending on the implementation, there may be variations in names, such as CafModuleType.FACE_LIVENESS or CafModuleType.FACE_LIVENESS_UI, which indicate whether a version without an interface or a version with an interface will be used.

Code example for creating the global configuration:

const { initialize, response } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // or CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // or CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      waitForAllServices: true,         // Optional, default is true
    }
  },
  () => {
    // Apply modules configuration
  },
);

Module-specific configuration

After defining the global configurations, it is necessary to configure the modules individually. This specific configuration allows adjusting specific operational parameters, ensuring they behave according to the requirements of your capture flow.

Document Detector configuration

Using the useCafDocumentDetector hook, you can configure the Document Detector module. This module is responsible for capturing and processing documents, such as ID cards or passports.

The Document Detector module is responsible for capturing and processing documents. Its configuration involves several parameters.

Mandatory parameter:

Capture flow (flow):
- Defines a list of steps (CafDocumentDetectorFlow) that specifies which document will be captured.
- This flow can be customized according to the types of documents to be validated by the application.

Operational parameters:

useAdb, useDebug, and useDeveloperMode are flags that activate specific modes for testing and development, allowing greater flexibility during the integration phase.
manualCaptureEnabled and manualCaptureTime control whether manual capture is allowed and, if so, define the time limit (in seconds) for the user to perform the action manually.
requestTimeout defines the maximum time (in seconds) that the system will wait for a server response.
showPopup determines whether a confirmation or instruction pop-up will be displayed to the user after document capture.

Code example for Document Detector configuration:

const { applyCafDocumentDetector } = useCafDocumentDetector({ // useCafDocumentDetectorUI for UI
  configuration: {
    flow: [
      { document: CafDocument.RG_FRONT },
      { document: CafDocument.RG_BACK }
    ],
    securitySettings: {
      useAdb: true,
      useDebug: true,
      useDeveloperMode: true,
    },
    manualCaptureEnabled: true,
    manualCaptureTime: 30,
    requestTimeout: 60,
    showPopup: true
  }
});

You will be applying the applyCafDocumentDetector function to configure the Document Detector module with the specified parameters. This configuration is essential to ensure that the module operates as expected, capturing and processing documents according to your application's requirements.

const { initialize, response } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // or CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // or CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      waitForAllServices: true,         // Optional, default is true
    }
  },
  () => {
    // Apply modules configuration
    applyCafDocumentDetector() // applyCafDocumentDetectorUI for UI
  },
);

Face Liveness configuration

Using the useCafFaceLiveness hook, you can configure the Face Liveness module. This module is responsible for verifying the authenticity of a face captured by a photo application.

The Face Liveness module is essential to ensure the security and reliability of the facial verification process, as it has the function of validating whether the captured face belongs to a real person.

Loading (Loading Screen):
- The loading flag defines whether a loading screen should be displayed while the module performs processing. This improves the user experience by informing them that the process is in progress.
Service URLs:
- authBaseUrl and livenessBaseUrl are optional endpoints for the authentication and liveness verification services, respectively.
- Once configured, these values must be configured with valid URLs, where authBaseUrl usually uses the HTTPS protocol for security, and livenessBaseUrl uses WSS (Secure WebSocket).
Certificates:
- When assigning values to service URLs, it is also necessary to provide the certificates list and ensure secure communications with trusted servers (when using reverse proxy).
Additional Options:
- screenCaptureEnabled enables or disables the ability to capture the screen during the verification process.
- debugModeEnabled allows logs and additional information to be available during execution, facilitating debugging.
Execute Face Authentication:
- executeFaceAuth sets whether to execute face authentication.

Code example for Face Liveness configuration:

const { applyCafFaceLiveness } = useCafFaceLiveness({
  configuration: {
    loading: true,                                                  // Displays loading screen during processing
    authBaseUrl: 'https://base-url.com',                            // Optional, endpoint for authentication
    livenessBaseUrl: 'wss://base-url.com',                          // Optional, endpoint for liveness check
    certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Optional, only user with reverse proxy
    screenCaptureEnabled: true,                                     // Allows screen capture if necessary
    debugModeEnabled: true,   
    executeFaceAuth: false                                     
  },
});

You will be applying the applyCafFaceLiveness function to configure the Face Liveness module with the specified parameters. This configuration is crucial to ensure that the module operates correctly, verifying the authenticity of the captured face according to your application's requirements.

const { initialize, response } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // or CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // or CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      waitForAllServices: true,         // Optional, default is true
    }
  },
  () => {
    // Apply modules configuration
    applyCafFaceLiveness() // applyCafFaceLivenessUI for UI
  },
);

These initial configurations are fundamental to ensure that the SDK operates as expected. Each parameter was designed to offer flexibility and security, allowing the capture flow to be adapted to the specific needs of your application.

Upon completing these configurations, the SDK will be ready to be initialized and executed, ensuring robust and efficient integration with the modules.

Events Handling

In useCafSdk hook, the response object contains a properties that handles events generated during the execution of the capture flow. This callback is essential for managing the flow of events, such as successful captures, errors, and user cancellations.

The response object includes the following properties:

log: captures log messages with different levels (DEBUG, USAGE, INFO). These messages help identify the internal behavior of the flow.
loading: indicates the start of module processing. Useful for displaying visual progress indicators.
success: upon successful completion, each module triggers an event containing a CafSuccessResponse object with the results.
error: if a problem occurs during execution, this event is triggered with the error message, allowing the application to handle the failure.
failure: indicates a face liveness failure, providing details about the type of failure and a description.
cancelled: indicates that the user or system interrupted the flow, enabling recovery actions or notifications.

Initializing the SDK

After defining the global and module-specific configurations, you can initialize the CafSDK using the initialize function provided by the useCafSdk hook. This function starts the capture flow according to the defined configurations and handles the events generated during execution.

Code examples:

const { initialize, response } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,    // or CafModuleType.FACE_LIVENESS_UI
        CafModuleType.DOCUMENT_DETECTOR // or CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      waitForAllServices: true,           // Optional, default is true
    }
  },
  () => {
    // Apply modules configuration
    applyCafFaceLiveness() // applyCafFaceLivenessUI for UI
    applyCafDocumentDetector() // applyCafDocumentDetectorUI for UI
  },
);

return (
  <Button title="Start Capture" onPress={initialize} />
)

Completing a session

A complete session in CafSDK covers the entire flow, from initialization to completion - whether this completion is a successful validation, an error, or a cancellation by the user.

Complete session definition

Complete Execution: the session is considered complete when each module in the capture flow triggers a Success event, indicating that all operations were successfully performed.
Flow Interruption: if an error occurs or if the user cancels the process at any point, the session is interrupted, and the Error or Cancelled event is triggered, allowing the application to take the necessary measures.

Completion events

Success:
- Returns results after all modules complete when waitForAllServices is enabled otherwise each module that ends successfully sends a CafSuccessResponse event, which includes:
  - moduleName: identifies the module that completed the operation (e.g., "DOCUMENT_DETECTOR" or "FACE_LIVENESS").
  - signedResponse: a JWT Token containing the result data obtained by the module's execution. This data may include information relevant to the process, such as captured images or validation results.
Failure:
- If a module fails to complete its operation, it triggers a CafFailureResponse event, which includes:
  - response: a JWT Token containing the result data obtained by the module's execution. This data may include information relevant to the process, such as captured images or validation results.
  - type: the type of failure
  - description: a descriptive message explaining the failure, allowing for appropriate error handling or user notifications.
Error/Cancelled:
- If the flow is interrupted due to a failure or cancellation:
  - Error: a event is triggered with a descriptive message of the problem, allowing the implementation of recovery logic or user notifications.
  - Cancelled: if the process is canceled (e.g., by the user), the event is triggered, allowing resource cleanup or the display of informative messages.

These steps ensure that you have a complete and technical view of the CafSDK flow initialization and completion process, allowing for simplified integration and the implementation of appropriate strategies for handling each step of the capture flow.

Advanced flow customization

Learn how to customize and adjust the CafSDK capture flow to meet specific business and user experience requirements.

Execution order

The order in which the modules will be executed is defined in the presentationOrder field of the CafSdkBuilderConfiguration object.
This sequence is fundamental, as it directly impacts the flow logic. For example, if the process requires the document to be captured before facial verification, the order must reflect this priority.

Specific configuration

To customize the modules individually, use the useCafDocumentDetector and useCafFaceLiveness hooks. They allow you to adjust critical parameters, such as:

Capture time: defines the timeout for the user to perform manual capture.
Timeout: establishes the maximum waiting limit for a service response.
Debug flags: enable or disable debug modes to facilitate problem identification during development.
Layout and other parameters: allow configuring visual and operational elements specific to each module.

Visual customization

With the CafColorConfiguration object, you can align the visual identity of the capture flow with your application's design. This ensures that visual elements (buttons, backgrounds, and indicators) are consistent with your brand identity.

Logging and monitoring

The unified callback implements different log levels (DEBUG, USAGE, INFO), which enables a detailed view of each step of the flow. These logs are essential for integrating with monitoring tools, adjusting performance, or identifying problems in real time.

Example of a implementation

import React, { useEffect } from 'react';
import { Button } from 'react-native'
import { useCafFaceLiveness } from '@caf.io/react-native-face-liveness'
import { useCafDocumentDetector } from '@caf.io/react-native-document-detector'
import { useCafSdk, CafEnvironment, CafModuleType } from '@caf.io/react-native-sdk'

export const Home = () => {
  const { applyCafFaceLiveness } = useCafFaceLiveness({
    configuration: {
      loading: true,
      debugModeEnabled: true,
    },
  });

  const { applyCafDocumentDetector } = useCafDocumentDetector({
    configuration: {
      flow: [
        { document: CafDocument.RG_FRONT },
        { document: CafDocument.RG_BACK }
      ],
      manualCaptureEnabled: true,
      manualCaptureTime: 45,
      requestTimeout: 60,
      showPopup: true
    }
  });

  const { initialize, response } = useCafSdk(
    {
      mobileToken: "mobile-token",
      personId: "person-id",
      environment: CafEnvironment.PROD,
      configuration: {
        presentationOrder: [
          CafModuleType.FACE_LIVENESS,    
          CafModuleType.DOCUMENT_DETECTOR 
        ],
        colorConfiguration: {
          primaryColor: "#0000FF",
          secondaryColor: "#00FF00",
        },
        waitForAllServices: true, // Optional, default is true       
      }
    },
    () => {
      applyCafFaceLiveness()
      applyCafDocumentDetector()
    },
  );

  useEffect(() => {
    if (response.success?.moduleName === 'FACE_LIVENESS') {
      console.log(response.success.signedResponse);
    } else if (response.success?.moduleName === 'DOCUMENT_DETECTOR') {
      console.log(response.success.signedResponse);
    }
  }, [response.success]);

  return (
    <Button title="Start Capture" onPress={initialize} />
  )
}

Face Liveness configuration

The integration of the Caf Face Liveness (FL) module is done through its configuration in the useCafFaceLiveness hook. Once applied within the useCafSdk initialization callback, the module automatically executes in the defined position of the presentationOrder.

The Face Liveness configuration is passed using the CafFaceLivenessConfiguration object, where the SDK behavior is customized through the CafFaceLivenessBuilderConfiguration. See below the main available parameters:

Property

Type

Description

loading

boolean

Enables or disables the loading screen before starting the flow. Default: true.

authBaseUrl

string

Reverse proxy URL for authentication. Must use HTTPS. Optional. Required only when using a reverse proxy.

livenessBaseUrl

string

Reverse proxy URL for Face Liveness verification. Must use WSS. Optional. Required only when using a reverse proxy.

certificates

string[]

Base64-encoded (SHA-256 SPKI) certificates for secure communication over WSS. Optional. Required only when using a reverse proxy.

screenCaptureEnabled

boolean

Enables or disables screen capture during liveness verification. Default: false.

debugModeEnabled

boolean

Enables verbose debug logging and developer tools for testing purposes. Default: false.

executeFaceAuth

boolean

Enables or disables the execution of the Face Authentication. Default: false.

Configuration example:

const { applyCafFaceLiveness } = useCafFaceLiveness({
  configuration: {
    loading: true,
    debugModeEnabled: true,
    screenCaptureEnabled: true,
    authBaseUrl: "https://my.proxy.io/v1/faces/", // Optional
    livenessBaseUrl: "wss://my.proxy.io/ws/",     // Optional
    certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="] // Optional
    executeFaceAuth: false // Optional, default is false
  }
});

const { initialize, response } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,
        CafModuleType.DOCUMENT_DETECTOR,
      ],
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00",
      },
      waitForAllServices: true // Optional
    }
  },
  () => {
    applyCafFaceLiveness(); // Triggers the liveness module
  }
);

Results

After the successful execution, a success event is triggered. The result is returned through the response object from the useCafSdk hook, and follows the structure of the CafSuccessResponse type:

moduleName: the module identifier (e.g., "FACE_LIVENESS").
signedResponse: a JWT token with the verification data.

Custom configurations – Face Liveness

Use custom configurations to route requests through secure proxies and ensure that the correct protocols (WSS for Face Liveness and HTTPS for authentication) are used.

Reverse proxy configuration (optional)

This advanced configuration allows the Face Liveness module to communicate through a reverse proxy using the WSS (WebSocket Secure) protocol. To configure it properly in React Native, set the appropriate properties inside the useCafFaceLiveness hook.

Proxy URL: define your proxy to communicate with the desired endpoint. For example, you can use: wss://us.rp.secure.iproov.me/ws or another compatible URL.
Face Liveness URL Configuration: use the livenessBaseUrl property to configure the Face Liveness URL. Remember that the protocol must be WSS.
Certificate Definition: use the certificates property to define the necessary certificates. These certificates must be the Base64 encoded SHA256 hashes of the proxy certificates.

Code example:

const { applyCafFaceLiveness } = useCafFaceLiveness({
  configuration: {
    livenessBaseUrl: "wss://my.proxy.io/ws/",
    certificates: [
      "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
      "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
      "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
    ]
  }
});

Reverse Proxy for Authentication (optional)

For authentication communication, it is necessary to configure the reverse proxy with an HTTPS URL. This configuration directs authentication requests to the appropriate environment.

Proxy URL: define your proxy to communicate. For example, you can use: https://api.public.caf.io/.
Authentication URL Configuration: use the authBaseUrl property to specify the authentication URL, ensuring the HTTPS protocol is used.

Code example:

const { applyCafFaceLiveness } = useCafFaceLiveness({
  configuration: {
    authBaseUrl: "https://my.proxy.io/v1/faces/"
  }
});

Note: In practice, both configurations (Face Liveness and authentication) can be combined in a single configuration object passed to the useCafFaceLiveness hook.

Configuration Structures

When using the UI module (from the @caf.io/react-native-face-liveness-ui package), Caf provides ready-to-use instruction screens with customizable settings. Below are the configuration options available for customizing both the behavior and the interface of the Face Liveness flow.

Caf Face Liveness Instructions Screen

This configuration allows you to customize the instruction screen that is shown before the Face Liveness flow starts.

Property

Type

Description

Default value

image

string

Image displayed in the screen header. The value can be a URL, the resource ID (in string format) or the resource name present in the drawable folder.

null

title

string

Screen title (e.g., "Instructions to Scan Face").

null

description

string

Brief description text (e.g., "Follow the steps below.").

null

steps

string[]

Ordered list of instructions (e.g., listOf ("Keep the phone steady"; "Good lighting")).

null

buttonText

string

Text for the confirmation button (e.g., "Start scanning").

null

Caf Color Configuration

You can define global colors used across the UI module screens by providing values in hex format.

Property

Type

Description

Format example

primaryColor

string

Main color for buttons and highlights.

#FF0000

secondaryColor

string

Secondary color for complementary elements.

#00FF00

backgroundColor

string

Screen background color.

#FFFFFF

contentColor

string

Color used for texts and icons.

#000000

mediumColor

string

Neutral color for elements like progress bars.

#CCCCCC

Code examples

Check out the example below for how to configure the Face Liveness module using the React Native UI module. It includes:

Instruction screen customization
Reverse proxy settings for authentication and liveness verification
UI color customization
Other builder options like debug mode and screen capture

const { applyCafFaceLivenessUI } = useCafFaceLivenessUI({
  configuration: {
    loading: true,
    authBaseUrl: "https://my.proxy.io/v1/faces/", 
    livenessBaseUrl: "wss://my.proxy.io/ws/",    
    certificates: [
      "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
      "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
      "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9=",
    ],
    screenCaptureEnabled: true,
    debugModeEnabled: true,
    executeFaceAuth: false, 
  },
  instructionScreenConfiguration: {
    image: "scan_icon", // Image Url or Local image uri
    title: "Custom title",
    description: "Follow the steps below:",
    steps: ["Keep the phone steady", "Ensure good lighting"],
    buttonText: "Start scanning",
  },
});

const { initialize } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS_UI,
        CafModuleType.DOCUMENT_DETECTOR,
      ],
      colorConfiguration: {
        primaryColor: "#FF0000",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#D1D1D1",
      },
    },
  },
  () => {
    applyCafFaceLivenessUI(); // Starts the module after SDK initialization
  }
);

More Information

Certificate requirements

Certificates: they must be the Base64 encoded SHA-256 hashes of the SPKI (Subject Public Key Info) of the certificate.

Protocol application

Face Liveness: The URL for Face Liveness must use the wss:// when using a reverse proxy.
Authentication: The URL for authentication must use the https:// when using a reverse proxy.

Document Detector configuration

The Caf Document Detector (DD) module is configured similarly to Face Liveness, but with a focus on document capture and processing.

Configuration and execution

In React Native, the module is configured through the useCafDocumentDetector hook, where you define the capture flow and other behavioral flags. Execution is handled by calling applyCafDocumentDetector() within the unified SDK initialization callback.

Main parameters:

flow: a list of steps (CafDocumentDetectorFlow) that defines which document and which angles or parts should be captured.
securitySettings: a set of flags that control the module's behavior, such as:
- useAdb: enables ADB debugging mode.
- useDebug: enables debug mode for detailed logs.
- useDeveloperMode: enables developer mode for advanced testing features.
manualCaptureEnabled and manualCaptureTime: configure whether manual capture is allowed and what the timeout for the action is.
requestTimeout: maximum time to wait for server responses or user actions.
showPopup: determines whether a confirmation or instruction message will be presented to the user.

Configuration example for Document Detector:

const { applyCafDocumentDetector } = useCafDocumentDetector({
  configuration: {
    flow: [
      { document: CafDocument.RG_FRONT },
      { document: CafDocument.RG_BACK }
    ],
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true,
    securitySettings: {
      useDebug: true,
      useAdb: true,
      useDevelopmentMode: true,
    },
  }
});

const { initialize } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.FACE_LIVENESS,
        CafModuleType.DOCUMENT_DETECTOR
      ],
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00"
      }
    }
  },
  () => {
    applyCafDocumentDetector(); // Executes the document capture module
  }
);

Results

After the successful execution, a success event is triggered. The result is returned through the response object from the useCafSdk hook, and follows the structure of the CafSuccessResponse type:

moduleName: the module identifier (e.g., "DOCUMENT_DETECTOR").
signedResponse: a JWT token with the verification data.

Custom configurations - Document Detector

To configure the Caf Document Detector in React Native, use the useCafDocumentDetector hook with a configuration object following the CafDocumentDetectorConfiguration and CafDocumentDetectorBuilderConfiguration interfaces.

This allows you to control:

The capture flow (flow)
UI customization (labels, illustrations, preview)
Proxy and upload behavior
Feedback messages
Security and debug options

Core configuration

Properties of CafDocumentDetectorBuilderConfiguration.

Property

Type

Description

flow

CafDocumentDetectorFlow[]

Defines the document capture flow. See CafDocumentDetectorFlow

uploadSettings

CafDocumentDetectorUploadSettings?

Settings for document upload. See CafDocumentDetectorUploadSettings

manualCaptureEnabled

boolean?

Enables or disables manual capture.

manualCaptureTime

number?

Timeout for manual capture (in seconds).

requestTimeout

number?

Timeout for requests (in seconds).

showPopup

boolean?

Enables or disables popups before capture.

proxySettings

CafDocumentDetectorProxySettings?

Proxy settings. See CafDocumentDetectorProxySettings

previewShow

boolean?

Enables or disables the preview screen after capture.

messageCustomization

CafDocumentDetectorMessageCustomization?

Message settings displayed during capture. See CafDocumentDetectorMessageCustomization

getUrlExpireTime

string?

Defines how long the image URL will remain active on the server until it expires. Accepts intervals such as 30m (minutes), 24h (hours), or 10d (days).

allowedPassportCountryList

CafCountryCodes[]?

List of allowed countries for passports. See CafCountryCodes

securitySettings

CafDocumentDetectorSecuritySettings?

Enables debug tools and developer testing features.

previewCustomization

CafDocumentDetectorPreviewCustomization?

Customization for the image preview screen shown after capture. See CafDocumentDetectorPreviewCustomization

uploadCustomization

CafDocumentDetectorUploadCustomization?

Customization for the upload screen shown after capture. See CafDocumentDetectorUploadCustomization

CafDocumentDetectorFlow

Defines each step in the capture process. Each step corresponds to a document and optionally includes visual customization:

flow: [
  {
    document: CafDocument.RG_FRONT,
  }
]

Property

Type

Description

document

CafDocument

Specifies the document to be captured in the step. Check the supported types below.

stepLabel

string?

Sets the text displayed at the bottom of the layout.

showStepLabel

boolean?

Toggles the visibility of the text at the top of the layout.

illustration

string?

Sets the illustration displayed in the popup before capture.

Supported Documents

Name

Description

RG_FRONT

Front side of the RG document, where the photo is located.

RG_BACK

Back side of the RG document.

RG_FULL

Open RG document, displaying both the front and back sides together.

CNH_FRONT

Front side of the CNH document, where the photo is located.

CNH_BACK

Back side of the CNH document.

CNH_FULL

Open CNH document, displaying both the front and back sides together.

CRLV

CRLV document.

RNE_FRONT

Front side of the RNE or RNM document.

RNE_BACK

Back side of the RNE or RNM document.

PASSPORT

Passport document, displaying the photo and personal data.

CTPS_FRONT

Front side of the CTPS document, where the photo is located.

CTPS_BACK

Back side of the CTPS document.

ANY

Allows submission of any type of document, including all those listed above or any other unclassified document.

CafDocumentDetectorUploadSettings

Configures the settings related to document upload.

Property

Type

Description

enable

boolean?

Enables or disables this feature.

compress

boolean?

Enables or disables file compression before upload.

fileFormats

CafFileFormat[]?

Specifies the accepted file formats for upload.

maxFileSize

number?

Sets the maximum file size limit in KB.

Currently, the supported file formats are:

Type

Value

PNG

image/png

JPG

image/jpg

JPEG

image/jpeg

PDF

application/pdf

HEIF

image/heif

HEIC

image/heic

CafDocumentDetectorPreviewCustomization

Configures the settings for the image preview screen shown after capturing a document. This allows you to customize the user interface and behavior of the preview screen.

Property

Type

Description

title

string?

Sets the title displayed on the screen.

message

string?

Sets the message displayed on the screen.

okButton

string?

Sets the message displayed on the confirmation button.

tryAgainButton

string?

Sets the message displayed on the button for a new capture.

CafDocumentDetectorProxySettings

To enable the SDK to route document upload requests through a proxy server, you can configure the proxySettings object inside the CafDocumentDetectorConfiguration.

Property

Type

Description

hostname

string

Sets the domain or IP address of the proxy service.

port

number

Sets the port to be used.

authentication

CafDocumentDetectorProxySettingsAuthentication?

Sets the authentication parameters for the proxy, if necessary.

CafDocumentDetectorProxySettingsAuthentication

If your proxy server requires authentication, provide credentials via the authentication field.

Property

Type

Description

user

string

Username to be used for authentication.

password

string

Password to be used for authentication.

CafDocumentDetectorMessageCustomization

To customize the messages displayed during the document capture flow, use the messageCustomization configuration object within CafDocumentDetectorBuilderConfiguration. This allows you to override default system messages to provide a more localized, guided, or brand-aligned user experience.

All properties are optional and can be defined selectively based on your needs.

Property

Description

waitMessage

Message displayed when starting the camera.

fitTheDocumentMessage

Message prompting the user to fit the document within the frame.

holdItMessage

Message displayed during the capture process.

verifyingQualityMessage

Message displayed during the quality verification request.

lowQualityDocumentMessage

Message displayed when document capture fails due to low quality.

uploadingImageMessage

Message displayed when saving the captured image to the server.

openDocumentWrongMessage

Message displayed if an open document is detected.

unsupportedDocumentMessage

Message for unsupported documents.

wrongDocumentMessage

Message displayed when the document type is incorrect.

documentNotFoundMessage

Message displayed when no document is detected.

sensorLuminosityMessage

Message displayed when the brightness level is too low.

sensorOrientationMessage

Message displayed when the orientation threshold is not met.

sensorStabilityMessage

Message displayed when the device is not stable enough.

popupDocumentSubtitleMessage

Subtitle message displayed in the popup presenting the document illustration.

positiveButtonMessage

Message displayed on the confirmation button.

predictorScanDocumentMessage

Message prompting the user to scan a document.

predictorGetCloserMessage

Message prompting the user to get closer to the document.

predictorCentralizeMessage

Message prompting the user to center the document on the screen.

predictorMoveAwayMessage

Message prompting the user to move away from the document.

predictorAlignDocumentMessage

Message prompting the user to align the document.

predictorTurnDocumentMessage

Message prompting the user to rotate the document 90 degrees.

predictorCapturedMessage

Message confirming that the document has been captured.

CafCountryCodes

Complete list of the official codes currently assigned according to ISO 3166-1 alpha-3.

Customizing Screens

When using the UI module (from the @caf.io/react-native-document-detector-ui package), Caf provides ready-to-use instruction screens with customizable settings. Below are the configuration options available for customizing both the behavior and the interface of the Document Detector flow.

CafDocumentDetectorInstructionsScreen

The instructionScreenConfiguration object in CafDocumentDetectorUIConfiguration allows you to customize instructional content for both the capture and upload steps.

Property

Type

Description

captureImage

string?

Image displayed in the header of the screen. The value can be a URL, a resource ID (as a string), or the name of the resource in the drawable folder.

captureTitle

string?

Screen title (e.g., "Instructions for Scanning the Face").

captureSteps

string[]?

Ordered list of instructions to guide the capture step.

uploadImage

string?

URL or local asset name to be shown during the upload step.

uploadTitle

string?

Title displayed above the upload instructions.

uploadSteps

string[]?

Ordered list of instructions to guide the user during the upload step.

description

string?

Brief descriptive text (e.g., "Follow the steps below").

buttonText

string?

Text for the confirmation button (e.g., "Start Scanning").

CafDocumentDetectorDocumentSelectionScreen

The documentSelectionScreenConfiguration field allows you to customize the screen where the user chooses which document to submit.

Property

Type

Description

title

string?

Screen title (e.g., "Select the Document").

description

string?

Brief descriptive text (e.g., "Choose the document you want to submit").

CafDocument

Value

Description

RG_FRONT

Front side of the RG document, where the photo is located.

RG_BACK

Back side of the RG document.

RG_FULL

Open RG document, displaying both the front and back sides together.

CNH_FRONT

Front side of the CNH document, where the photo is located.

CNH_BACK

Back side of the CNH document.

CNH_FULL

Open CNH document, displaying both the front and back sides together.

CRLV

CRLV document.

RNE_FRONT

Front side of the RNE or RNM document.

RNE_BACK

Back side of the RNE or RNM document.

CTPS_FRONT

Front side of the CTPS document, where the photo is located.

CTPS_BACK

Back side of the CTPS document.

PASSPORT

Passport document, displaying the photo and personal data.

ANY

Allows submission of any other type of document that is not classified.

Caf Color Configuration

You can define global colors used across the UI module screens by providing values in hex format.

Property

Type

Description

Format example

primaryColor

string

Main color for buttons and highlights.

#FF0000

secondaryColor

string

Secondary color for complementary elements.

#00FF00

backgroundColor

string

Screen background color.

#FFFFFF

contentColor

string

Color used for texts and icons.

#000000

mediumColor

string

Neutral color for elements like progress bars.

#CCCCCC

Code example

The following example demonstrates how to configure the Document Detector UI module in React Native, including:

Document selection screen
Instruction screen
UI color customization
Developer/test environment flags

const { applyCafDocumentDetectorUI } = useCafDocumentDetectorUI({
  configuration: {
    flow: [], // Flow can be empty; selection is handled via UI
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true,
    securitySettings: {
      useDebug: true,
      useDevelopmentMode: true,
      useAdb: true,
    },
  },
  instructionScreenConfiguration: {
    captureTitle: "Capture your document",
    captureSteps: [
      "Keep the phone steady",
      "Ensure good lighting",
      "Avoid reflections"
    ],
    buttonText: "Start",
  },
  documentSelectionScreenConfiguration: {
    title: "Select the document type",
    description: "Choose which document you want to submit",
  },
});

const { initialize } = useCafSdk(
  {
    mobileToken: "mobile-token",
    personId: "person-id",
    environment: CafEnvironment.PROD,
    configuration: {
      presentationOrder: [
        CafModuleType.DOCUMENT_DETECTOR_UI
      ],
      colorConfiguration: {
        primaryColor: "#FF0000",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#D1D1D1"
      },
    },
  },
  () => {
    applyCafDocumentDetectorUI(); // Starts the Document Detector UI flow
  }
);

CafSuccessResponse

In React Native, when a module completes successfully, the SDK emits a CafUnifiedEvent.Success event. This event contains a typed object conforming to the CafSuccessResponse structure, representing the result of the executed module.

This response is strongly typed based on the module name, and provides a structured result rather than just a JWT string.

export type CafSuccessResponse<
  K extends keyof typeof CafModuleType = keyof typeof CafModuleType,
> = {
  [M in K]: {
    moduleName: M;
    signedResponse: CafModuleResultMap[StringToNumberMap[M]];
  };
}[K];

Property

Type

Description

moduleName

String

Name of the module issuing its result in the success event.

signedResponse

String

JWT containing the data obtained by the module's execution.

Code example

useEffect(() => {
  if (response.success?.moduleName === "FACE_LIVENESS") {
    const result = response.success.signedResponse;
    // Handle result (e.g., send to backend, update UI)
  }

  if (response.success?.moduleName === "DOCUMENT_DETECTOR") {
    const result = response.success.signedResponse;
    // Process captured document data
  }
}, [response.success]);

Additional resources

ProGuard/R8 Rules

Check out the code block with the ProGuard/R8 rules necessary for CafSDK and its dependencies to function correctly even after code obfuscation and optimization. These rules preserve essential information (such as signatures, annotations, and internal classes) and prevent critical classes from being removed or altered.

### React Native ProGuard/R8 rules for Caf SDK ########################
-dontobfuscate

-keep,allowobfuscation @interface com.facebook.proguard.annotations.DoNotStrip
-keep,allowobfuscation @interface com.facebook.proguard.annotations.KeepGettersAndSetters

-keep @com.facebook.proguard.annotations.DoNotStrip class *
-keepclassmembers class * {
    @com.facebook.proguard.annotations.DoNotStrip *;
}

-keepclassmembers @com.facebook.proguard.annotations.KeepGettersAndSetters class * {
  void set*(***);
  *** get*();
}

-keep class * extends com.facebook.react.bridge.JavaScriptModule { *; }
-keep class * extends com.facebook.react.bridge.NativeModule { *; }

-keepclassmembers,includedescriptorclasses class * { native <methods>; }
-keepclassmembers class *  { @com.facebook.react.uimanager.annotations.ReactProp <methods>; }
-keepclassmembers class *  { @com.facebook.react.uimanager.annotations.ReactPropGroup <methods>; }
-dontwarn com.facebook.react.**
### END React Native ProGuard/R8 rules #############################

### GSON ##################################################################
# Gson uses generic type information stored in a class file when working with fields.
# ProGuard removes such information by default, so configure it to keep all of it.
-keepattributes Signature
# For using GSON @Expose annotation
-keepattributes *Annotation*
### END GSON ##################################################################

### Retrofit ##################################################################
# Preserve generic signatures, inner classes, and enclosing methods for Retrofit reflection.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Retain runtime-visible annotations on methods and parameters.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Keep annotation default values.
-keepattributes AnnotationDefault
# Retain service method parameters for interfaces with Retrofit annotations.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suppress warnings for build tooling and certain JSR 305 annotations.
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
# Explicitly keep Retrofit interfaces to prevent nullification by R8.
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
# Preserve continuations used by Kotlin suspend functions.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# For R8 full mode: keep generic return types for Retrofit methods.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preserve Retrofit Response class.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### END Retrofit ##############################################################

### OkHttp ####################################################################
# Suppress warnings for JSR 305 annotations.
-dontwarn javax.annotation.**
# Adapt resource filenames for internal public suffix database.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suppress warnings for Animal Sniffer and platform-specific classes.
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
# Keep all OkHttp and Okio classes.
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### END OkHttp ################################################################

### Kotlin Serialization ######################################################
# Keep Companion objects for serializable classes.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Keep serializer functions on companion objects.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Retain INSTANCE and serializer for serializable objects.
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve Companion objects in kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve serializer lookup for serializable classes (adjust package name as needed).
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### END Kotlin Serialization #################################################

### AutoValue ################################################################
-dontwarn com.google.auto.**
-dontwarn autovalue.shaded.com.**
-dontwarn sun.misc.Unsafe
-dontwarn javax.lang.model.element.Modifier
### END AutoValue ############################################################

### CAF - Combate a Fraude ############################################## 
# Keep exceptions attributes.
-keepattributes Exceptions
# Preserve all classes, interfaces, and class members for CAF modules.
-keep class com.caf.facelivenessiproov.** { *; }
-keep class com.combateafraude.documentdetector.** { *; }
-keep class com.combateafraude.** { *; }
-keep interface com.combateafraude.** { *; }
-keep class io.caf.** { *; }
-keep interface io.caf.** { *; }
-keepclassmembers class com.combateafraude.** { *; }
# Suppress warnings for java.nio.file and certain OkHttp internal classes.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Keep fields in classes extending GeneratedMessageLite (for Tink usage).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preserve TensorFlow classes.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preserve IProov classes and Protobuf classes.
-keep public class com.iproov.sdk.IProov { public *; }
-keep class com.iproov.** { *; }
-keep class com.iproov.**$* { *; }
-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }
-dontwarn com.google.protobuf.**
# Suppress warnings for concurrent Flow classes.
-dontwarn java.util.concurrent.Flow*
# Preserve Kotlin and kotlinx classes.
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
### END CAF - Combate a Fraude #########################################

Technical Support and Usage Tips

Technical Support If you have any questions or difficulties with the integration, contact Caf's technical support.

Usage tips

Run tests: perform tests on real devices to validate requirements and flow performance.
Explore customizations: use advanced customization options to tailor the flow to your project's needs.
Monitor performance: integrate monitoring tools to track logs and the flow's performance in production.

Release notes

@caf.io/[email protected]

New Features

Implementation: New property in @caf.io/react-native-face-liveness and @caf.io/react-native-face-liveness-ui the new property executeFaceAuth allows for more granular control over the face authentication process.

@caf.io/[email protected]

New Features

New Property: The executeFaceAuth property allows for more granular control over the face authentication process.

@caf.io/[email protected]

New Features

New Property: The executeFaceAuth property allows for more granular control over the face authentication process.

@caf.io/[email protected]

New Features

Internal Improvements: The @caf.io/react-native-document-detector package has been updated to improve internal handling of document capture flows, enhancing performance and reliability.

@caf.io/[email protected]

New Features

Internal Improvements: The @caf.io/react-native-document-detector-ui package has been updated to improve internal handling of document capture flows, enhancing performance and reliability.

@caf.io/[email protected]

New Features

Introducing @caf.io/react-native-sdk: A unified SDK for integrating both Face Liveness and Document Detector modules in React Native applications.
Builder Pattern Support: Simplified setup using CafSdkBuilderConfiguration, allowing type-safe configuration and modular composition.
Unified Configuration Model: Manage execution order (presentationOrder), UI theming (CafColorConfiguration), and flow behavior in a centralized way.
Consistent Module Handling: Shared authentication, environment (CafEnvironment), logging (CafLog), and response structure across all modules.
Simplified Integration: React hook for initializing and managing the full SDK lifecycle.
Live State Tracking: Provides a unified response object with real-time updates on loading, cancellation, success, failure, and logs.
Manual Triggering: Exposes initialize() to start the flow after native configuration is complete.
Built-in Event Management: Listens and reacts to all CafUnifiedEvent emissions, abstracting the native communication layer.

Runtime and Response Handling

Unified Response Interface: CafResponse includes structured result types:
- success using CafSuccessResponse
- failure using CafFailureResponse
- log, loading, cancelled, and error states
Strongly Typed Module Responses:
- CafDocumentDetectorResult
- CafFaceLivenessResult

Module Support

Supported modules through CafModuleType enum:
- DOCUMENT_DETECTOR
- DOCUMENT_DETECTOR_UI
- FACE_LIVENESS
- FACE_LIVENESS_UI

Configuration Enhancements

Flexible UI Customization:
- Color theming via CafColorConfiguration
- Custom confirmation step content via CafConfirmationNextStepContentConfiguration
Failure & Logging Support:
- Enum-based failure types (CafFailureType)
- Structured logs with log levels (CafLogLevel)

Breaking Changes

New Integration Module: @caf.io/react-native-sdk replaces any previous isolated implementations.

@caf.io/[email protected]

New Features

Modular SDK Integration: The Face Liveness module is now available as a standalone package for modular usage within the new @caf.io/react-native-sdk architecture.
New Hook: useCafFaceLiveness: Introduces a convenient React hook for applying and triggering face liveness flows with configuration support.
Direct Execution API: The hook exposes applyCafFaceLiveness() to trigger the flow using the latest configuration.

Configuration Enhancements

Typed Configuration via CafFaceLivenessConfiguration:
- Centralized object for configuring the liveness experience
- Supports nested CafFaceLivenessBuilderConfiguration for advanced control
Builder Options Include:
- authBaseUrl and livenessBaseUrl for proxying and custom endpoints
- certificates[] for TLS pinning
- screenCaptureEnabled toggle
- debugModeEnabled for verbose logs and developer tools
- Loading screen support via loading

Breaking Changes

Legacy Hook and Flow Removed:
- useFaceLiveness has been removed and replaced with the new useCafFaceLiveness hook.
- startFaceLiveness() is no longer needed; the flow is now triggered via applyCafFaceLiveness() inside the hook.
Configuration Object Renamed and Simplified:
- FaceLivenessSettings ➜ replaced by CafFaceLivenessConfiguration, which contains a nested CafFaceLivenessBuilderConfiguration for better structure and type safety.
Enum Removals and Type Replacements:
- The following enums have been removed:
  - Stage ➜ no longer required no longer required Filter, Time ➜ no longer required; behavior now handled by configuration structure
  - Error ➜ replaced by standard error and failure structures
- Related conditional formatting and platform-specific enum transformations have been eliminated.
Response Format Simplified:
- FaceLivenessResponse, FaceLivenessResult, FaceLivenessError, and FaceLivenessFailure ➜ all removed

@caf.io/[email protected]

New Features

Modular UI Integration: The Face Liveness UI module is now available as a standalone package designed to work independently or as part of the new @caf.io/react-native-sdk architecture.
New Hook: useCafFaceLivenessUI: Provides a convenient React hook for applying and triggering the face liveness UI flow with support for custom configurations.
Direct Execution API: The hook exposes applyCafFaceLivenessUI() to initialize the native UI flow using the current configuration.

Configuration Enhancements

Typed Configuration via CafFaceLivenessUIConfiguration: A centralized object for managing both the functional and UI aspects of the liveness experience.
Builder Options Include:
- authBaseUrl and livenessBaseUrl for custom service endpoints
- certificates[] for secure TLS communication
- screenCaptureEnabled and debugModeEnabled flags
- Loading indicator control via the loading flag
Instruction Screen Customization via instructionScreenConfiguration:
- Support for an instructional image, title, description, and ordered step messages
- Customizable button label to guide users into the flow

@caf.io/[email protected]

New Features

Modular SDK Integration: The Document Detector module is now available as a standalone package for modular usage within the @caf.io/react-native-sdk architecture.
New Hook: useCafDocumentDetector: React hook that allows initializing the document detection flow by serializing and applying configuration through applyCafDocumentDetector().

Configuration Enhancements

Typed Configuration via CafDocumentDetectorConfiguration: Centralized and type-safe configuration using the CafDocumentDetectorBuilderConfiguration interface.
Advanced Flow Composition with flow: Define the capture sequence using CafDocumentDetectorFlow[], supporting various documents like RG, CNH, Passport, and more.
Expanded Upload Configuration:
- Control allowed formats (PNG, JPG, PDF, HEIC, etc.)
- File compression and size limits
- Full proxy support with authentication options
UI and Behavior Customization:
- Custom preview screen text and layout
- Document upload messages and assets
- Step-by-step guidance and instruction labels
- Timeout, manual capture, popup, and security settings
Message Customization Support: Fine-tune user feedback during the capture process with CafDocumentDetectorMessageCustomization.
Security Features: Configure development flags (useDevelopmentMode, useAdb, useDebug) for controlled testing environments.
Country Restrictions for Passports: Restrict accepted passport documents using allowedPassportCountryList based on ISO 3166-1 alpha-3 codes.

Breaking Changes

Legacy Hook and Flow Removed:
- useDocumentDetector has been removed and replaced with the new useCafDocumentDetector hook.
- startDocumentDetector() is no longer needed; flow execution now occurs through applyCafDocumentDetector() inside the hook.
Configuration Object Renamed and Restructured:
- DocumentDetectorSettings ➜ replaced by CafDocumentDetectorConfiguration, which wraps a structured CafDocumentDetectorBuilderConfiguration.
Step Configuration:
- DocumentDetectorStep[] ➜ replaced by CafDocumentDetectorFlow[] for defining document capture steps.
Message Customization:
- DocumentDetectorMessageSettings ➜ replaced by CafDocumentDetectorMessageCustomization.
Preview Settings:
- DocumentDetectorPreviewSettings ➜ replaced by CafDocumentDetectorPreviewCustomization.
Upload Settings:
- DocumentDetectorUploadSettings ➜ renamed to CafDocumentDetectorUploadSettings.
Proxy Settings:
- DocumentDetectorProxySettings ➜ replaced by CafDocumentDetectorProxySettings with equivalent structure but new type.
Security Settings:
- DocumentDetectorSecuritySettings ➜ replaced by CafDocumentDetectorSecuritySettings.
Sensor Configuration:
- DocumentDetectorSensorSettings ➜ no longer present as a standalone object.
Country Restriction:
- allowedPassportList used CountryCodes enum ➜ now uses CafCountryCodes.
Enum Restructuring:
- Enums like Stage, Resolution, CaptureMode, and Error were removed. Their behavior has been replaced by structured properties inside configuration objects or removed entirely for simplification.
Response Format Simplified:
- DocumentDetectorResponse, DocumentDetectorResult, and DocumentDetectorError ➜ no longer used. The module now returns its success/failure through the centralized response flow inside the SDK or is handled directly via native integration feedback.

@caf.io/[email protected]

New Features

Modular UI Integration: The Document Detector UI module is now available as a standalone package designed to work independently or as part of the new @caf.io/react-native-sdk architecture.
New Hook: useCafDocumentDetectorUI: Provides a React hook to apply and trigger the document detection UI flow with a clean and declarative interface.
Direct Execution API: The hook exposes applyCafDocumentDetectorUI() to initialize the native document detector UI flow using the latest configuration.

Configuration Enhancements

Typed Configuration via CafDocumentDetectorUIConfiguration: Centralized configuration combining core workflow, instructional screens, and document selection steps.
Builder Options Include:
- flow setup with CafDocumentDetectorFlow[] to define document capture steps
- Upload control via uploadSettings, including file size, compression, and format options
- Proxy setup with optional authentication via proxySettings
- Security flags for debugging and testing via securitySettings
- Manual capture toggles, preview screen control, and timeout customization
Instruction Screen Customization via instructionScreenConfiguration:
- Define images, titles, button labels, and instructional messages for both capture and upload phases
- Enhance user guidance with detailed step-by-step visuals and descriptions
Document Selection UI via documentSelectionScreenConfiguration:
- Optional screen allowing users to choose the document type before capture begins
- Customizable title and description to match your app’s tone and user flow

Last updated 14 days ago