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.

CafSDK is a unified SDK that integrates multiple modules for identity verification: Face Liveness (FL) and Document Detector (DD), executed sequentially with a unified configuration interface.

What is Face Liveness

Face Liveness is the module that validates the authenticity of a face captured by a photo application, ensuring that the image corresponds to a real person and not a spoofing attempt.

Technical characteristics:

• URL configuration for authentication (authBaseUrl) and liveness verification (livenessBaseUrl)
• Support for reverse proxy configuration with certificate pinning
• Flags to enable screen capture and debug mode
• Configurable retry attempts and face authentication execution
• Support for multiple authentication providers

What is Document Detector

Document Detector 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
• Support for multiple document types (RG, CNH, Passport, etc.)
• Operational parameters, such as timeout, manual capture flags, and other settings
• Possibility of using the camera for framing validations, or document file upload
• Advanced customization options for UI, messages, and behavior

---

Installation

Requirements

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	18

Android

Requirement	Version
Android SDK API - minimum version (minSdk)	26
Android SDK API - compile version (compileSdk)	36
Kotlin	1.9.10
Gradle	8.4
Android Gradle Plugin (AGP)	8.3.2

iOS

Requirement	Version
iOS Deployment Target	15.0
Xcode	26.0
Swift	5.10

Step 1: Install the SDK

Install the main SDK package:

npm install @caf.io/react-native-sdk

Step 2: Configure Module Selection

Expo

When using Expo, you don't need to manually create the caf-modules-config.json file, it generates automatically from app.json.

To configure the SDK, add the following plugin to your app.json file:

app.json

{
  "plugins": [
    // ... your plugins
    [
      "@caf.io/react-native-sdk",
      {
        // SDK modules configuration
        "documentDetector": true,
        "faceLiveness": true,
        "documentDetectorUI": true,
        "faceLivenessUI": true,
        "livenessProviders": ["iproov-lite", "payface"],
        "fingerprint": true
      }      
    ]
  ]
}

Community CLI

To configure the SDK, create a caf-modules-config.json file in your app's root directory to control which native modules are included.

caf-modules-config.json

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": ["iproov-lite", "payface"],
  "fingerprint": true
}

If you omit the SDK modules configuration, all modules are enabled by default, and iproov-lite is set as the default Face Liveness provider.

Set each module flag to true to include it, or false to exclude it.

livenessProviders accepts a string array .

iProov and Protobuf

• iproov-lite: use when your app targets Protobuf JavaLite—the usual choice for a smaller binary footprint on Android.
• iproov-full: use when you need Protobuf Java (full) together with iProov.

If you include the PayFace provider, you must also use iProov Lite (iproov-lite). PayFace is built against Protobuf JavaLite; mixing it with iproov-full causes Protobuf dependency conflicts at build time.

Fingerprint

The Fingerprint module is optional and is configured in caf-modules-config.json via the fingerprint property (boolean). It defaults to false, so you don't need to add the property unless you want to use it. To enable the module, explicitly set "fingerprint": true.

Requires a Face Liveness module. Fingerprint is collected as part of the liveness flow, so it is only bundled when faceLiveness or faceLivenessUI is also enabled. Setting "fingerprint": true without a liveness module enabled has no effect.

Important: Please contact CAF Support to request activation. If it is not enabled on our side, the SDK will not trigger the fingerprint library and no data will be sent, even if the property is set to true locally.

Step 3: iOS Configuration

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.

---

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

---

Basic Implementation

Simple Example

Here's a basic implementation example:

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

import React, { useEffect } from 'react';
import { SafeAreaView, View, Button, Text } from 'react-native';
import {
  useCafSdk,
  CafModuleType,
  CafEnvironment,
  CafDocument,
  useCafFaceLiveness,
  useCafDocumentDetector,
} from '@caf.io/react-native-sdk';

function App(): React.JSX.Element {
  const { initialize, startSDK, response, initialized } = useCafSdk();

  const { applyCafFaceLiveness } = useCafFaceLiveness();

  const { applyCafDocumentDetector } = useCafDocumentDetector();

  const handleInitialize = async () => {
    const result = await initialize({
      configuration: {
        presentationOrder: [
          CafModuleType.FACE_LIVENESS, 
          CafModuleType.DOCUMENT_DETECTOR
        ],
        enableSecurityModule: true,
      },
      mobileToken: 'your-mobile-token',
      environment: CafEnvironment.PROD,
      personId: 'user-person-id',
    },
    async () => {
      const appliedFaceLiveness = await applyCafFaceLiveness({
        maxRetryAttempts: 0,
        executeFaceAuth: false,
      });
      const appliedDocumentDetector = await applyCafDocumentDetector({
        flow: [{ document: CafDocument.CNH_FULL }],
        uploadSettings: {
          enable: true,
        },
        manualCaptureEnabled: false,
        securitySettings: {
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        },
        maxRetryAttempts: 0,
      });
      return appliedFaceLiveness && appliedDocumentDetector;
    });
  };

  const handleStartSDK = () => {
    if (initialized) {
      startSDK();
    }
  };

  useEffect(() => {
    handleInitialize();
  }, []);

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

  return (
    <SafeAreaView>
      <View>
        <Button 
          title="Start" 
          onPress={handleStartSDK} 
          disabled={response.loading}
        />
        {response.loading && <Text>Processing...</Text>}
      </View>
    </SafeAreaView>
  );
}

export default App;

---

Configuration

Language

Android

The language is automatically set according to the language configured on the device without any additional settings.

iOS

According to Apple's documentation, configuring Localizations and CFBundleLocalizations should be done in Xcode:

Adding support for languages and regions

CFBundleLocalizations

After these settings, the SDK will recognize the device's language.

Global Configuration

The useCafSdk hook serves as the central container for all configurations. The global configuration defines the execution order of the modules and the visual identity, and is passed to the initialize() function.

Returned values:

• initialize: Function that initializes the SDK and applies module configurations. Returns Promise<boolean> indicating if all configurations were applied successfully. Accepts the global configuration and a callback function that applies module-specific configurations.
• startSDK: Function that starts the SDK flow after initialization.
• loadSession: Optional function to pre-load the user session before starting the SDK flow.
• response: Object containing event handlers for the SDK execution (success, error, loading, etc.).
• initialized: Boolean state indicating if the initialize function successfully applied all module configurations. This state can be used to verify that configurations were applied correctly before calling startSDK().

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

Essential parameters (passed to initialize()):

• 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 (PROD, BETA, DEV)
• presentationOrder: Defines the sequence in which the modules will be executed
• enableSecurityModule: Enables or disables the security module. Optional, default is true

Code example for creating the global configuration:

const { initialize, response, initialized } = useCafSdk();
const { applyCafFaceLiveness } = useCafFaceLiveness();
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Initialize SDK with global configuration
await initialize(
  {
    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
      ],
      enableSecurityModule: true,       // Optional, default is true
      waitForAllServices: true,         // Optional, default is true
      enableTransitionScreens: true,    // Optional, default is true
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#CCCCCC",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#E5E5E7",
      },
    }
  },
  async () => {
    // Apply modules configuration
    // All apply functions now return Promise<boolean>
    const appliedFaceLiveness = await applyCafFaceLiveness({
      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 when using reverse proxy
      screenCaptureEnabled: true,                                     // Allows screen capture if necessary
      debugModeEnabled: true,                                         // Enables debug logging
      executeFaceAuth: false,                                         // Enables face authentication
      maxRetryAttempts: 2,                                            // Maximum retry attempts
    });
    const appliedDocumentDetector = await applyCafDocumentDetector({
      flow: [
        { document: CafDocument.RG_FRONT },
        { document: CafDocument.RG_BACK }
      ],
      securitySettings: {
        useAdb: true,
        useDebug: true,
        useDevelopmentMode: true,
      },
      manualCaptureEnabled: true,
      manualCaptureTime: 30,
      requestTimeout: 60,
      showPopup: true,
      maxRetryAttempts: 2,
      uploadSettings: {
        enable: true,
        compress: true,
        fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
        maxFileSize: 5, // 5MB
      },
    });

    return appliedFaceLiveness && appliedDocumentDetector;
  },
);

Session Pre-loading (Optional)

The loadSession() method allows you to pre-load the user session before starting the SDK flow. This improves the Face Liveness SDK opening time by preparing the session and camera initialization in advance, resulting in faster SDK startup when startSDK() is called.

When to use:

• When you want to optimize the user experience by reducing the initial loading time
• When you have the opportunity to pre-load the session before the user actually needs to start the flow
• Particularly useful for Face Liveness module initialization

Code example:

const { initialize, startSDK, loadSession, response, initialized } = useCafSdk();
const { applyCafFaceLiveness } = useCafFaceLiveness();
const { applyCafDocumentDetector } = useCafDocumentDetector();

// Initialize SDK (builds configurations)
// initialize() now returns Promise<boolean>
await initialize(
  {
    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
      ],
      enableSecurityModule: true,       // Optional, default is true
      waitForAllServices: true,         // Optional, default is true
      enableTransitionScreens: true,    // Optional, default is true
      colorConfiguration: {
        primaryColor: "#0000FF",
        secondaryColor: "#00FF00",
        backgroundColor: "#FFFFFF",
        contentColor: "#000000",
        mediumColor: "#CCCCCC",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#E5E5E7",
      },
    }
  },
  async () => {
    // Apply modules configuration
    // All apply functions now return Promise<boolean>
    const appliedFaceLiveness = await applyCafFaceLiveness({
      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 when using reverse proxy
      screenCaptureEnabled: true,                                     // Allows screen capture if necessary
      debugModeEnabled: true,                                         // Enables debug logging
      executeFaceAuth: false,                                         // Enables face authentication
      maxRetryAttempts: 2,                                            // Maximum retry attempts
    });
    const appliedDocumentDetector = await applyCafDocumentDetector({
      flow: [
        { document: CafDocument.RG_FRONT },
        { document: CafDocument.RG_BACK }
      ],
      securitySettings: {
        useAdb: true,
        useDebug: true,
        useDevelopmentMode: true,
      },
      manualCaptureEnabled: true,
      manualCaptureTime: 30,
      requestTimeout: 60,
      showPopup: true,
      maxRetryAttempts: 2,
      uploadSettings: {
        enable: true,
        compress: true,
        fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
        maxFileSize: 5, // 5MB
      },
    });

    return appliedFaceLiveness && appliedDocumentDetector;
  },
);

// Pre-load the session (optional)
loadSession();

// Later, when ready to start the flow
startSDK();

Important notes:

• This method is optional and can be called after initialize() but before start()
• Pre-loading the session helps reduce the initial loading time when start() is eventually called
• This is particularly beneficial for Face Liveness module initialization

Module-Specific Configuration

Face Liveness Configuration

Using the useCafFaceLiveness hook, you can configure the Face Liveness module. The configuration is applied when calling the applyCafFaceLiveness function:

const { applyCafFaceLiveness } = useCafFaceLiveness();

// Apply configuration when initializing
await applyCafFaceLiveness({
  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 when using reverse proxy
  screenCaptureEnabled: true,                                     // Allows screen capture if necessary
  debugModeEnabled: true,                                         // Enables debug logging
  executeFaceAuth: false,                                         // Enables face authentication
  maxRetryAttempts: 2,                                            // Maximum retry attempts
});

Document Detector Configuration

Using the useCafDocumentDetector hook, you can configure the Document Detector module. The configuration is applied when calling the applyCafDocumentDetector function:

const { applyCafDocumentDetector } = useCafDocumentDetector();

// Apply configuration when initializing
await applyCafDocumentDetector({
  flow: [
    { document: CafDocument.RG_FRONT },
    { document: CafDocument.RG_BACK }
  ],
  securitySettings: {
    useAdb: true,
    useDebug: true,
    useDevelopmentMode: true,
  },
  manualCaptureEnabled: true,
  manualCaptureTime: 30,
  requestTimeout: 60,
  showPopup: true,
  maxRetryAttempts: 2,
  uploadSettings: {
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
    maxFileSize: 5, // 5MB
  },
});

---

Event Handling

The response object from the useCafSdk hook contains properties that handle events generated during the execution of the capture flow:

• log: Captures log messages with different levels (DEBUG, USAGE, INFO)
• loading: Indicates the start of module processing
• success: Upon successful completion, each module triggers an event containing a CafSuccessResponse[] object
• error: If a problem occurs during execution, this event is triggered with the error message
• failure: Indicates a face liveness failure, providing details about the type of failure
• cancelled: Indicates that the user or system interrupted the flow

Error Types (CafErrorType)

Enum Case	Trigger Condition
CAMERA_PERMISSION	Camera access denied
UNSUPPORTED_DEVICE	Unsupported device specs
NETWORK_EXCEPTION	Network connectivity issues
SERVER_EXCEPTION	Backend processing failure
TOKEN_EXCEPTION	Invalid/expired token
CAPTURE_ALREADY_ACTIVE_EXCEPTION	Concurrent capture session
UNEXPECTED_ERROR_EXCEPTION	Critical unrecoverable error
USER_TIMEOUT_EXCEPTION	Capture timeout exceeded
IMAGE_NOT_FOUND_EXCEPTION	Missing image data
TOO_MANY_REQUESTS_EXCEPTION	API rate limit exceeded
UNKNOWN_EXCEPTION	Unclassified error
LIBRARY_EXCEPTION	Low-level framework error
PERMISSION_EXCEPTION	Missing system permissions
INVALID_EXCEPTION	Invalid response received
SEQUENCE_INVALID	Invalid operation sequence
LIVENESS_EXCEPTION	Face liveness specific error
FINGERPRINT_EXCEPTION	Fingerprint related error
STORAGE_EXCEPTION	Storage access error
PROXY_EXCEPTION	Proxy configuration error
SECURITY_EXCEPTION	Security validation error
BRIDGE_EXCEPTION	Native ↔ React Native bridge communication error

Failure Types (CafFailureType)

Enum Case	Trigger Condition	GPA	LA
UNKNOWN	Generic failure	✅	❌
TOO_MUCH_MOVEMENT	Excessive head motion	✅	❌
TOO_BRIGHT	Over-illumination	✅	❌
TOO_DARK	Low light conditions	✅	❌
MISALIGNED_FACE	Face alignment failure	✅	❌
FACE_TOO_FAR	Face too distant	✅	❌
FACE_TOO_CLOSE	Face too close	✅	❌
SUNGLASSES	Eye-obscuring eyewear	✅	❌
OBSCURED_FACE	Partial face obstruction	✅	✅
EYES_CLOSED	Closed eyes during capture	✅	✅
MULTIPLE_FACES	Multiple faces detected	✅️	✅️
BACKGROUND_ISSUE	Unsuitable background	❌	✅
DEVICE_ISSUE	Incompatible device	❌	✅
EYEWEAR	Eyewear detected	❌	✅
FACE_NOT_FOUND	Face detection failure	❌	✅
FRAMES_BLURRY	Blurry frames detected	❌	✅
MOTION_ISSUE	Device motion error	❌	✅
LIGHTING_ISSUES	Poor lighting conditions	❌	✅
REJECTED	Transaction rejected	❌	✅
SYSTEM_ERROR	Internal system error	❌	✅
TIMEOUT	Session timeout	❌	✅
USER_NOT_FOUND	User lookup failure	❌	✅
DEVICE_RESTART	Device state error	❌	✅
PROCESSING_FAULT	Processing error	❌	✅

---

Document Types

Supported Documents (CafDocument)

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
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 type of document, including all those listed above or any other unclassified document

Supported File Formats (CafFileFormat)

Type	Value
PNG	image/png
JPG	image/jpg
JPEG	image/jpeg
PDF	application/pdf
HEIF	image/heif
HEIC	image/heic

---

Advanced Configuration

Face Liveness UI Configuration

When using the UI module, you can customize instruction screens:

const { applyCafFaceLivenessUI } = useCafFaceLivenessUI();

// Apply configuration when initializing
await applyCafFaceLivenessUI({
  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, 
  maxRetryAttempts: 2,
  instructionScreen: {
    image: "scan_icon", // Image URL or local asset name
    title: "Custom title",
    description: "Follow the steps below:",
    steps: ["Keep the phone steady", "Ensure good lighting"],
    buttonText: "Start scanning",
  },
});

Document Detector UI Configuration

const { applyCafDocumentDetectorUI } = useCafDocumentDetectorUI();

// Apply configuration when initializing
await applyCafDocumentDetectorUI({
  flow: [{ document: CafDocument.RG_FRONT }], 
  manualCaptureEnabled: true,
  manualCaptureTime: 45,
  requestTimeout: 60,
  showPopup: true,
  securitySettings: {
    useDebug: true,
    useDevelopmentMode: true,
    useAdb: true,
  },
  maxRetryAttempts: 2,
  instructionScreen: {
    enable: true,
    captureTitle: "Capture your document",
    captureSteps: [
      "Keep the phone steady",
      "Ensure good lighting",
      "Avoid reflections"
    ],
    buttonText: "Start",
  },
  documentSelectionScreen: {
    title: "Select the document type",
    description: "Choose which document you want to submit",
  },
});

Proxy Configuration

For Document Detector proxy settings:

const { applyCafDocumentDetector } = useCafDocumentDetector();

// Apply configuration when initializing
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  proxySettings: {
    hostname: "proxy.example.com",
    port: 8080,
    authentication: {
      user: "username",
      password: "password"
    }
  },
});

Message Customization

Customize messages displayed during the capture flow:

const { applyCafDocumentDetector } = useCafDocumentDetector();

// Apply configuration when initializing
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  messageCustomization: {
    waitMessage: "Preparing camera...",
    fitTheDocumentMessage: "Position the document within the frame",
    holdItMessage: "Hold steady...",
    verifyingQualityMessage: "Verifying document quality...",
    lowQualityDocumentMessage: "Document quality is too low. Please try again.",
    uploadingImageMessage: "Uploading document...",
    positiveButtonMessage: "Continue",
  }
});

---

Complete Implementation Example

Here's a complete example showing both Face Liveness UI and Document Detector UI:

import React, { useEffect } from 'react';
import { SafeAreaView, View, Button, Text } from 'react-native';
import {
  useCafSdk,
  CafModuleType,
  CafEnvironment,
  CafDocument,
  CafFileFormat,
  useCafFaceLivenessUI,
  useCafDocumentDetectorUI,
} from '@caf.io/react-native-sdk';

function App(): React.JSX.Element {
  const { applyCafFaceLivenessUI } = useCafFaceLivenessUI();
  const { applyCafDocumentDetectorUI } = useCafDocumentDetectorUI();
  const { initialize, startSDK, loadSession, response, initialized } = useCafSdk();

  const handleInitialize = async () => {
    await initialize(
      {
        configuration: {
          presentationOrder: [
            CafModuleType.FACE_LIVENESS_UI,
            CafModuleType.DOCUMENT_DETECTOR_UI
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
          enableTransitionScreens: true,
          colorConfiguration: {
            primaryColor: "#007AFF",
            secondaryColor: "#34C759",
            backgroundColor: "#FFFFFF",
            contentColor: "#000000",
            mediumColor: "#8E8E93",
            dialogBackgroundColor: "#FFFFFF",
            dialogBorderColor: "#E5E5E7",
          },
        },
        mobileToken: 'your-mobile-token',
        environment: CafEnvironment.PROD,
        personId: 'user-person-id',
      },
      async () => {
        const appliedFaceLivenessUI = await applyCafFaceLivenessUI({
          maxRetryAttempts: 2,
          executeFaceAuth: true,
          debugModeEnabled: false,
          instructionScreen: {
            image: "face_scan_icon",
            title: "Face Verification",
            description: "We need to verify your identity",
            steps: [
              "Position your face in the frame",
              "Ensure good lighting",
              "Follow the instructions on screen"
            ],
            buttonText: "Start Verification",
          },
        });
        const appliedDocumentDetectorUI = await applyCafDocumentDetectorUI({
          flow: [
            { document: CafDocument.RG_FRONT },
            { document: CafDocument.RG_BACK }
          ],
          manualCaptureEnabled: true,
          manualCaptureTime: 30,
          requestTimeout: 60,
          showPopup: true,
          maxRetryAttempts: 2,
          uploadSettings: {
            enable: true,
            compress: true,
            fileFormats: [CafFileFormat.PNG, CafFileFormat.JPG],
            maxFileSize: 5, 
          },
          securitySettings: {
            useDebug: false,
            useDevelopmentMode: false,
            useAdb: false,
          },
          instructionScreen: {
            enable: true,
            captureTitle: "Document Capture",
            captureSteps: [
              "Keep the phone steady",
              "Ensure good lighting",
              "Avoid reflections",
              "Fit the document in the frame"
            ],
            buttonText: "Start Capture",
          },
          documentSelectionScreen: {
            title: "Select Document Type",
            description: "Choose the document you want to submit",
          },
        });

        return appliedFaceLivenessUI && appliedDocumentDetectorUI;
      },
    ).then((result: boolean) => {
      if (result) {
        loadSession();
      }
    });
  };

  const handleStartSDK = () => {
    if (initialized) {
      startSDK();
    }
  };

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

  useEffect(() => {
    if (response.error) {
      console.error('SDK Error:', response.error);
    }
  }, [response.error]);

  useEffect(() => {
    if (response.failure) {
      console.warn('SDK Failure:', response.failure);
    }
  }, [response.failure]);

  useEffect(() => {
    if (response.log) {
      console.log('SDK Log:', response.log);
    }
  }, [response.log]);

  useEffect(() => {
    handleInitialize();
  }, []);

  return (
    <SafeAreaView>
      <View style={{ padding: 20 }}>
        <Button 
          title="Start Identity Verification" 
          onPress={handleStartSDK}
          disabled={response.loading}
        />
        {response.loading && <Text>Processing...</Text>}
      </View>
    </SafeAreaView>
  );
}

export default App;

---

ProGuard/R8 Rules

Add these ProGuard/R8 rules to your proguard-rules.pro file for Android:

### 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.** { *; }
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### 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
• Handle errors gracefully: Implement proper error handling for all possible error and failure scenarios
• Test with different devices: Ensure compatibility across various device specifications and screen sizes

---

Known issues

Crash: Screen fragments should never be restored

Description

In React Native applications that consume native Android SDKs, a crash may occur when the operating system recreates the main Activity after it has been destroyed in the background. The typical error displayed is:

java.lang.IllegalStateException: Screen fragments should never be restored

Context

Android may destroy background processes to free up system resources. When the user returns to the application, the system attempts to restore the previous Activity state, including screen fragments. The react-native-screens library, used for navigation management, does not support this behavior by default and throws an exception.

Solution

Add the following override to your project's MainActivity.kt file, as recommended in the react-native-screens documentation:

package com.your.app

import android.os.Bundle;
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;

class MainActivity : ReactActivity() {

  //...code

  override fun onCreate(savedInstanceState: Bundle?) {
      supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
      super.onCreate(savedInstanceState);
  }

  //...code
}

By setting RNScreensFragmentFactory as the fragment factory before calling super.onCreate(), the library can properly handle fragment restoration when the Activity is recreated.

Impact

This change allows the application to gracefully handle Activity recreation scenarios without crashing, maintaining a seamless user experience even when the system reclaims resources in the background.

---

Release Notes

@caf.io/[email protected]

Release date

• 08/14/2026

Highlights

• Android 16 compatibility: Updated React Native module to support Android 16 (compileSdk / targetSdk 36), aligning with Google Play requirements for apps targeting recent Android versions.

Fixes

Face Liveness: Fixed an issue in the Payface flow where a failed face validation could still be reported as success. The SDK now correctly treats validation failures and shows the appropriate message to the user.

Document Detector: Fixed capture and upload issues on tablets and devices in landscape mode, including a brief incorrect image orientation flash in the preview, auto-capture failures with misaligned final photos, and minor UI adjustments to layout margins and the close button.

Updates

• React Native Android module compileSdk / targetSdk updated to 36.

@caf.io/[email protected]

Release date

• 08-03-2026

Breaking change : The Fingerprint module is now optional and can be configured in caf-modules-config.json via the new fingerprint property (boolean). By default, fingerprint is set to false, meaning you do not need to add this property to the JSON unless you want to use it. To enable the module, you must explicitly add "fingerprint": true. Important: Fingerprint must also be enabled on Backoffice. If it is not enabled on Backoffice, the SDK will never call the fingerprint library and no data will be sent, even if the property is set to true locally.

Highlights

• Optional Fingerprint module: Control the inclusion of the fingerprint feature directly from caf-modules-config.json. It is disabled by default, ensuring you only include the dependency when strictly necessary.

Updates

• New fingerprint boolean field in caf-modules-config.json for Android and iOS.

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": [
    "iproov-lite",
    "payface",
    "facetec"
  ],
  "fingerprint": true
}

@caf.io/[email protected]

Release date

• 07-06-2026

Breaking Changes

The intermediate configuration wrapper object was removed from all standalone module hooks. Configuration fields are now passed directly on the object.

Affected hooks:

• applyCafDocumentDetector()
• applyCafDocumentDetectorUI()
• applyCafFaceLiveness()
• applyCafFaceLivenessUI()

// Before (4.x)
await applyCafFaceLiveness({
  configuration: { loading: false, maxRetryAttempts: 0 },
});

// After (5.0.0)
await applyCafFaceLiveness({
  loading: false,
  maxRetryAttempts: 0,
});

Renamed configuration types

The BuilderConfiguration interfaces were removed. The public configuration types are now the flat Configuration interfaces:

Removed (4.x)	Use instead (5.0.0)
CafDocumentDetectorBuilderConfiguration	CafDocumentDetectorConfiguration
CafFaceLivenessBuilderConfiguration	CafFaceLivenessConfiguration
CafDocumentDetectorUIBuilderInstructionScreenConfiguration	CafDocumentDetectorUIInstructionScreenConfiguration
CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration	CafDocumentDetectorUIDocumentSelectionScreenConfiguration
CafFaceLivenessUIBuilderInstructionScreenConfiguration	CafFaceLivenessUIInstructionScreenConfiguration

CafDocumentDetectorConfiguration and CafFaceLivenessConfiguration are no longer wrappers around a nested configuration — they now hold the fields directly. CafDocumentDetectorUIConfiguration and CafFaceLivenessUIConfiguration now extend the base configuration instead of nesting it.

Renamed UI configuration fields

Removed field (4.x)	Use instead (5.0.0)
instructionScreenConfiguration	instructionScreen
documentSelectionScreenConfiguration	documentSelectionScreen

Response state behavior

The useCafSdk response lifecycle changed and may require adjustments if you relied on the previous implicit state resets:

• initialize() now resets the response object (success, failure, error, cancelled, log, loading) at the start of every call.
• The Success, Failure, Error, and Cancelled events now all set initialized back to false.
• The Loading and Loaded events no longer clear success / failure / error / cancelled — they only update the loading flag.

Features

• New error type CafErrorType.BRIDGE_EXCEPTION: emitted when the bridge receives an invalid/empty JSON payload or fails to map the configuration, instead of failing silently.
• Instruction screen toggle for Face Liveness UI: new optional enable?: boolean (default true) on CafFaceLivenessUIInstructionScreenConfiguration, matching the Document Detector UI instruction screen.

Migration Guide - 4.x → 5.0.0

The public bridge contract (native method names, event names such as CafUnifiedEvent.*, and response payload keys like moduleName / signedResponse) is unchanged. The only migration work is on the TypeScript configuration objects you pass to the module hooks.

1. Remove the nested configuration wrapper

Move every field out of the configuration object and pass it directly.

Document Detector

// Before (4.x)
await applyCafDocumentDetector({
  configuration: {
    flow: [{ document: CafDocument.RG_FRONT }],
    manualCaptureEnabled: false,
    maxRetryAttempts: 0,
  },
});

// After (5.0.0)
await applyCafDocumentDetector({
  flow: [{ document: CafDocument.RG_FRONT }],
  manualCaptureEnabled: false,
  maxRetryAttempts: 0,
});

Face Liveness

// Before (4.x)
await applyCafFaceLiveness({
  configuration: { loading: false, maxRetryAttempts: 0 },
});

// After (5.0.0)
await applyCafFaceLiveness({
  loading: false,
  maxRetryAttempts: 0,
});

2. Update the UI hooks (config + renamed fields)

Document Detector UI

// Before (4.x)
await applyCafDocumentDetectorUI({
  configuration: { flow: [{ document: CafDocument.RG_FRONT }] },
  instructionScreenConfiguration: { enable: true, title: 'Capture' },
  documentSelectionScreenConfiguration: { title: 'Choose document' },
});

// After (5.0.0)
await applyCafDocumentDetectorUI({
  flow: [{ document: CafDocument.RG_FRONT }],
  instructionScreen: { enable: true, title: 'Capture' },
  documentSelectionScreen: { title: 'Choose document' },
});

Face Liveness UI

// Before (4.x)
await applyCafFaceLivenessUI({
  configuration: { loading: false },
  instructionScreenConfiguration: { title: 'Face liveness' },
});

// After (5.0.0)
await applyCafFaceLivenessUI({
  loading: false,
  instructionScreen: { enable: true, title: 'Face liveness' },
});

3. Update your type imports

If you imported any of the removed types, rename them:

// Before (4.x)
import type {
  CafDocumentDetectorBuilderConfiguration,
  CafFaceLivenessBuilderConfiguration,
  CafDocumentDetectorUIBuilderInstructionScreenConfiguration,
  CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration,
  CafFaceLivenessUIBuilderInstructionScreenConfiguration,
} from '@caf.io/react-native-sdk';

// After (5.0.0)
import type {
  CafDocumentDetectorConfiguration,
  CafFaceLivenessConfiguration,
  CafDocumentDetectorUIInstructionScreenConfiguration,
  CafDocumentDetectorUIDocumentSelectionScreenConfiguration,
  CafFaceLivenessUIInstructionScreenConfiguration,
} from '@caf.io/react-native-sdk';

4. Review your response handling (optional)

If your app depended on the old side effect where a Loading / Loaded event cleared success / failure / error, handle those resets explicitly. Note that initialize() now clears the response at the start of each run.

@caf.io/[email protected]

Release date

• 07-20-2026

Fixes

• Race conditions during the return of the Success Event

@caf.io/[email protected]

Release date

• 06-10-2026

Fixes

• Maven CDN Fortface not found

@caf.io/[email protected]

Release date

• 06-10-2026

Fixes

• Maven CDN Fortface not found

@caf.io/[email protected]

Release date

• 06-10-2026

Fixes

• Maven CDN Fortface not found

@caf.io/[email protected]

Release date

• 06-09-2026

Updates

• Payface Liveness Provider (Android): Update version from 1.18.2 to 1.19.2.
• Payface Liveness Provider (iOS): Update version from 1.5.2 to 1.8.2.

Fixes

FaceLiveness

• Infinite loading error occurs when the SDK returns an error.
• First initialization not working when using Payface provider.

@caf.io/[email protected]

Release date

• 04-27-2026

Breaking change : Face Liveness providers can now be configured in caf-modules-config.json via livenessProviders (string or array). When provided, it must list the chosen provider(s). Do not use iproov-lite and iproov-full together—iproov-full uses a different version of Protobuf, and combining them will cause duplicate class errors at build time. PayFace requires iproov-lite (Protobuf JavaLite); pairing PayFace with iproov-full causes build-time Protobuf conflicts. If omitted, the SDK defaults to iproov-lite on both platforms. An empty or invalid value causes a build error on Android; on iOS, an empty value also falls back to iproov-lite, but an invalid value causes a build failure. See Step 2: Configure Module Selection for details.

Features

• Configurable Face Liveness providers: Choose iproov-lite, iproov-full, payface, and/or facetec from caf-modules-config.json instead of relying on implicit native defaults.

Updates

• Liveness provider configuration:

  • New livenessProviders field in caf-modules-config.json for Android and iOS.
  • Documented Protobuf JavaLite vs Protobuf Java mapping for iproov-lite vs iproov-full.
  • Clarified multi-provider setups using an array, and the PayFace + iProov Lite requirement.
• iProov Liveness Provider: Documentation and defaults updated to reflect the new provider selection model.
• Android ProGuard / R8: If R8 reports missing classes for lint stubs shipped with the SDK, add the following to proguard-rules.pro (also listed under ProGuard/R8 Rules):

-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**

@caf.io/[email protected]

Versions earlier than 4.3.0 will result iProov Liveness to become inoperable as of March 12, 2026. To ensure proper functionality and service continuity, please use version 4.3.0 or later.

Release date

• 02/09/2026

Update

• Dependency update: Updated iProov version from 10.2.0 to 11.1.0 in Android.
• Dependency update: Updated iProov version from 12.2.1 to 13.1.0 in iOS.

Android & iOS

• New failure types: Added new failure to CafFailureType for better failure handling:

  • BACKGROUND_ISSUE
  • DEVICE_ISSUE
  • EYEWEAR
  • FACE_NOT_FOUND
  • FRAMES_BLURRY
  • MOTION_ISSUE
  • LIGHTING_ISSUES
  • REJECTED
  • SYSTEM_ERROR
  • TIMEOUT
  • USER_NOT_FOUND
  • DEVICE_RESTART
  • PROCESSING_FAULT

@caf.io/[email protected]

Release date

• 02/02/2026

Features

• New CafSecurity module: Added a new module with security validations.

  • New configuration flag: enableSecurityModule in CafSdkConfiguration with default value true

Fixes

• FaceLiveness

  • Fixed sessions creation erros.
  • Fixed color tint on remote images in the Instructions screen.

@caf.io/[email protected]

Release date

• 01/12/2026

Features

• PayFace (Fortface) Provider Integration: Optional Face Liveness provider now available

  • New property payFaceDebugMode in CafFaceLivenessConfig to enable debug mode for the PayFace provider.

Fixes

• Fixed crashes in Document Detector module: Resolved multiple crashes related to activity lifecycle management, including initialization, pause, and resume states.
• Fixed crashes related to camera lifecycle: Improved camera resource management and thread lifecycle to prevent crashes during SDK shutdown and state transitions.
• Fixed crashes in UI components: Resolved theme compatibility issues and fragment transaction exceptions to ensure proper UI behavior.
• Fixed crashes in network requests: Corrected response body handling to prevent errors when reading network responses.
• Fixed crashes in data access: Improved cursor initialization and validation before accessing database data.
• Fixed ANR in Document Controller: Optimized document controller instance checks to prevent application not responding issues.
• Internal improvements and corrections: Additional stability enhancements and bug fixes.

@caf.io/[email protected]

Release date

• 11/27/2025

Breaking Changes

Race Condition Prevention:

To prevent race conditions, the following functions now return Promise<boolean>:

• initialize(): Now returns Promise<boolean>. The callback parameter also returns Promise<boolean>.
• applyCafFaceLiveness(): Now returns Promise<boolean>.
• applyCafFaceLivenessUI(): Now returns Promise<boolean>.

New State: initialized

A new initialized state is returned from the useCafSdk hook. This state allows you to verify if the initialize function successfully applied the module configurations.

The settings of the modules now are set in the functions initialize, applyCafDocumentDetector, applyCafFaceLiveness, applyCafDocumentDetectorUI, applyCafFaceLivenessUI.

Migration Example:

const { initialize, initialized } = useCafSdk();
const { applyCafDocumentDetector } = useCafDocumentDetector();
const { applyCafFaceLiveness } = useCafFaceLiveness();

function handleInitialize() {
  initialize(
    {
      environment: config.environment,
      mobileToken: config.mobileToken,
      personId: config.personId,
      configuration: {
        presentationOrder: [CafModuleType.DOCUMENT_DETECTOR, CafModuleType.FACE_LIVENESS],
        enableSecurityModule: true,
      },
    },
    async () => {
      const appliedDocumentDetectorSettings = await applyCafDocumentDetector({
        configuration: {
          flow: [{ document: CafDocument.RG_FRONT }],
          manualCaptureEnabled: false,
          securitySettings: {
            useAdb: true,
            useDebug: true,
            useDevelopmentMode: true,
          },
          maxRetryAttempts: 0,
        },
      });
      
      const appliedFaceLivenessSettings = await applyCafFaceLiveness({
        configuration: {
          loading: false,
          debugModeEnabled: true,
          maxRetryAttempts: 0,
        },
      });
      
      return appliedDocumentDetectorSettings && appliedFaceLivenessSettings;
    },
  ).then((res: boolean) => {
    if (res) {
      // loadSession();
      // startSDK();
    }
  });
}

Fixes

Document Detector / Document Detector UI

• Fixed crash when used empty flow in CafDocumentDetectorConfig: This issue was causing the SDK to close immediately during opening the document capture flow. Now the SDK will emit a new error event CafErrorType.LIBRARY_EXCEPTION with the message "Empty document options".
• Fixed error when use loadSession in Document Detector module: This issue was causing the SDK to close immediately during opening the document capture flow. Now the sdk will not emit a error SEQUENCE_INVALID.

@caf.io/[email protected]

Release date

• 11/17/2025

Features

SDK Initialization

• New Methods:

  • loadSession(): Pre-loads the user session before starting the SDK flow. This improves the SDK opening time by preparing the session and camera initialization in advance, resulting in faster SDK startup when start() is called. This method is optional and can be called after initialize() but before start().
  • start(): Starts the SDK flow after configuration has been built. This method initiates the sequential execution of the configured modules.

Response

• New Response:

  • response.success: An array of CafSuccessResponse objects.

Document Detector / Document Detector UI

Android

• Manual capture mode as default: Manual capture mode from the start is now set as the default, due to difficulties in capture using automatic mode.
• Analytics logs: Added detailed analytics logs to monitor document capture and upload details. These logs record messages, capture modes, fallback time, and sensors.

iOS

• Manual capture mode as default: Manual capture mode from the start is now set as the default, due to difficulties in capture using automatic mode.

Breaking Changes

• SDK Initialization Flow:

  • Previously, initialize() would automatically start the SDK after building configurations.
  • Now, initialize() only builds the SDK configurations and does not start the SDK automatically.
  • You must explicitly call startSDK() after initialize() to actually start the SDK flow.
  • The recommended flow is: initialize() → (optional) loadSession() → startSDK()

Fixes

Document Detector / Document Detector UI

Android

• Fixed crash "Image is already closed": This issue was causing the SDK to close immediately during document capture.
• Fixed crash when used empty flow in CafDocumentDetectorConfig: This issue was causing the SDK to close immediately during opening the document capture flow. Now the SDK will emit a new error event CafErrorType.LIBRARY_EXCEPTION with the message "Empty document options".
• Improved error messaging: Improved error messaging for incorrect document type detection to provide more accurate feedback during document validation.
• Fallback on capture mode: Improved state management for capture mode transitions to ensure consistent and reliable behavior when manual and automatic capture modes interact.
• Layout: Improved readability with increased line spacing and updated margins for more consistent layout and visual balance.
• UI Improvements: Prevented text overflow in the document detector by enabling truncation for long titles and step names and adjusting spacing.
• Light sensor deactivation: The light sensor has been disabled during the capture flow. Previously, the SDK used the device's light sensor to display the "Environment too dark" message, blocking capture until the sensor detected good lighting.
• Messages deactivation during manual capture: Messages during manual capture have been disabled to avoid friction during the capture flow.

iOS

• Error Messaging: Improved error messaging for incorrect document type detection to provide more accurate feedback during document validation.
• Attestation Reporting: More detailed attestation error reporting (network/invalid token/invalid response) with safer error handling.
• Document Identification: Fixed issue where document identification was not being displayed on the image capture screen even without custom configuration.

@caf.io/[email protected]

Release date

• 10/15/2025

Highlights

• 16kb page size support on Android

Features

• Group Labels: Optional group labels on the Document Selection screen to show custom titles and descriptions per document group (RG, CNH, Passport, etc.).

Fixes

Android

• Analytics improvements: Improved error reporting across face liveness flows: clearer network/server distinctions, precise camera permission handling.
• DocumentDetector: stopped auto-enabling document preview when not explicitly configured.

@caf.io/[email protected]

Highlights

• Unified SDK: Complete consolidation of all CAF modules into a single package, eliminating the need for multiple separate dependencies
• Simplified Integration: Streamlined installation and configuration process with unified module management
• Enhanced TypeScript Support: All type definitions consolidated into the main SDK package for better development experience
• Module Configuration: Added comprehensive module configuration system for flexible SDK setup

Breaking Changes

• Dependency Consolidation: The following packages are no longer required and should be removed from your project:

  • @caf.io/react-native-face-liveness
  • @caf.io/react-native-face-liveness-ui
  • @caf.io/react-native-document-detector
  • @caf.io/react-native-document-detector-ui
• Type Definitions Migration: All TypeScript types have been moved to @caf.io/react-native-sdk

  • Remove type imports from individual packages
  • Import all types from @caf.io/react-native-sdk
• Module Configuration: New configuration system using caf-modules-config.json file

  • Modules must be explicitly enabled/disabled in the configuration file
  • If no configuration file is provided, all modules are included by default

Features

• Module Configuration System:

  • caf-modules-config.json: New configuration file in project root to specify which modules to include
  • Available modules:

    • documentDetector: Enable/disable Document Detector module
    • faceLiveness: Enable/disable Face Liveness module
    • documentDetectorUI: Enable/disable Document Detector UI module
    • faceLivenessUI: Enable/disable Face Liveness UI module
  • Example configuration:

    {
      "documentDetector": true,
      "faceLiveness": true,
      "documentDetectorUI": false,
      "faceLivenessUI": false
    }

• Unified Error Handling: Consistent error handling across all modules
• Improved Performance: Optimized bundle size and runtime performance through selective module inclusion
• Enhanced Analytics: Unified analytics tracking across all modules

Fixes

iOS

• Race Condition Fix: Resolved race condition that prevented SDK from opening on iOS devices
• Memory Management: Improved memory handling during module transitions
• Navigation Issues: Fixed nested navigation problems in iOS

Android

• Permission Handling: Enhanced camera permission error reporting with distinct error classification
• Network Stability: Improved network error handling and retry mechanisms
• Build Compatibility: Updated build configurations for better compatibility

Cross-Platform

• Error Reporting: Enhanced server error message clarity by extracting and surfacing raw error payloads
• Loading States: Improved loading screen behavior and state management
• Module Lifecycle: Better handling of module initialization and cleanup

Migration Guide

To migrate from individual packages to the unified SDK:

1. Remove old dependencies:

   npm uninstall @caf.io/react-native-face-liveness @caf.io/react-native-face-liveness-ui @caf.io/react-native-document-detector @caf.io/react-native-document-detector-ui

2. Install the unified SDK:

   npm install @caf.io/[email protected]

3. Create module configuration file: Create caf-modules-config.json in your project root:

   {
     "documentDetector": true,
     "faceLiveness": true,
     "documentDetectorUI": false,
     "faceLivenessUI": false
   }

4. Update imports:

   // Before
   import { useCafFaceLiveness } from '@caf.io/react-native-face-liveness';
   import { useCafDocumentDetector } from '@caf.io/react-native-document-detector';
   
   // After
   import { 
     useCafFaceLiveness, 
     useCafDocumentDetector 
   } from '@caf.io/react-native-sdk';

5. Implementation remains the same: Your existing implementation code does not need to change. The hooks and their usage remain identical:

   // This code works exactly the same as before
   const { applyCafFaceLiveness } = useCafFaceLiveness(settings);
   const { applyCafDocumentDetector } = useCafDocumentDetector(settings);

@caf.io/[email protected]

New Features

• New Types:

  • CafErrorType and CafFailureType enums added to the SDK
• New Properties:

  • CafSdkBuilderConfiguration now has enableTransitionScreens property to enable/disable transition screens between modules
  • CafColorConfiguration now has dialogBackgroundColor and dialogBorderColor properties for dialog customization

@caf.io/[email protected]

New Features

• Internal Improvements: Enhanced internal handling of document capture flows, improving performance and reliability

@caf.io/[email protected]

New Features

• Internal Improvements: Enhanced internal handling of document capture flows, improving performance and reliability

@caf.io/[email protected]

New Features

• Internal Improvements: Enhanced internal handling of document capture flows, improving performance and reliability

@caf.io/[email protected]

New Features

• New Properties:

  • CafDocumentDetectorUIBuilderInstructionScreenConfiguration now has enable property to customize the instruction screen

@caf.io/[email protected]

New Features

• Implementation: New executeFaceAuth property in Face Liveness modules for more granular control over face authentication

@caf.io/[email protected]

New Features

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

@caf.io/[email protected]

New Features

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

@caf.io/[email protected]

New Features

• Internal Improvements: Enhanced internal handling of document capture flows, improving performance and reliability

@caf.io/[email protected]

New Features

• Internal Improvements: Enhanced internal handling of document capture flows, improving 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

@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