> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/react-native/getting-started-with-the-sdk.md).

# 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)** | 34      |
| **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:

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

### Step 2: Configure Module Selection

{% tabs %}
{% tab title="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:

{% code title="app.json" %}

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

{% endcode %}
{% endtab %}

{% tab title="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.

{% code title="caf-modules-config.json" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you omit the SDK modules configuration, all modules are enabled by default, and **`iproov-lite`** is set as the default Face Liveness provider.
{% endhint %}

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.

{% hint style="warning" %}
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.
{% endhint %}

### Step 3: iOS Configuration

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

```sh
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:

{% hint style="warning" %}
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.
{% endhint %}

```typescript
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](https://developer.apple.com/documentation/xcode/adding-support-for-languages-and-regions)

[CFBundleLocalizations](https://developer.apple.com/documentation/bundleresources/information-property-list/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()`.

{% hint style="warning" %}
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.
{% endhint %}

**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:**

<pre class="language-typescript"><code class="lang-typescript"><strong>const { initialize, response, initialized } = useCafSdk();
</strong>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&#x3C;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 &#x26;&#x26; appliedDocumentDetector;
  },
);
</code></pre>

### **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:**

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```proguard
### 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:

```kotlin
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/react-native-sdk\@5.0.0

#### 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()`

```tsx
// 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**

```tsx
// 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**

```tsx
// 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**

```tsx
// 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**

```tsx
// 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:

```tsx
// 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/react-native-sdk\@4.5.2

#### Release date

* 07-20-2026

#### Fixes

* Race conditions during the return of the Success Event

### @caf.io/react-native-sdk\@4.5.1

#### Release date

* 06-10-2026

#### Fixes

* Maven CDN Fortface not found

### @caf.io/react-native-sdk\@4.4.1

#### Release date

* 06-10-2026

#### Fixes

* Maven CDN Fortface not found

### @caf.io/react-native-sdk\@4.3.1

#### Release date

* 06-10-2026

#### Fixes

* Maven CDN Fortface not found

### @caf.io/react-native-sdk\@4.5.0

#### 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/react-native-sdk\@4.4.0

#### Release date

* 04-27-2026

{% hint style="warning" %}
**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](#step-2-configure-module-selection) for details.
{% endhint %}

#### 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](#proguardr8-rules)):

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

### @caf.io/react-native-sdk\@4.3.0

{% hint style="warning" %}
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.
{% endhint %}

#### 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/react-native-sdk\@4.2.0

#### 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/react-native-sdk\@4.1.1

#### 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/react-native-sdk\@4.0.0

#### 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:**

```typescript
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/react-native-sdk\@3.0.0

#### 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/react-native-sdk\@2.1.0

### 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/react-native-sdk\@2.0.0

#### 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:

    ```json
    {
      "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**:

   ```bash
   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**:

   ```bash
   npm install @caf.io/react-native-sdk@2.0.0
   ```
3. **Create module configuration file**: Create `caf-modules-config.json` in your project root:

   ```json
   {
     "documentDetector": true,
     "faceLiveness": true,
     "documentDetectorUI": false,
     "faceLivenessUI": false
   }
   ```
4. **Update imports**:

   ```typescript
   // 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:

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

### @caf.io/react-native-sdk\@1.1.0

#### 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/react-native-face-liveness\@4.1.0

#### New Features

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

### @caf.io/react-native-face-liveness-ui\@1.1.0

#### New Features

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

### @caf.io/react-native-document-detector\@4.1.0

#### New Features

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

### @caf.io/react-native-document-detector-ui\@1.1.0

#### New Features

* **New Properties:**
  * `CafDocumentDetectorUIBuilderInstructionScreenConfiguration` now has `enable` property to customize the instruction screen

### @caf.io/react-native-sdk\@1.0.0

#### New Features

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

### @caf.io/react-native-face-liveness\@4.0.0

#### New Features

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

### @caf.io/react-native-face-liveness-ui\@1.0.0

#### New Features

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

### @caf.io/react-native-document-detector\@4.0.0

#### New Features

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

### @caf.io/react-native-document-detector-ui\@1.0.0

#### New Features

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

### @caf.io/react-native-sdk\@1.0.0-beta1

#### 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/react-native-face-liveness\@4.0.0-beta1

#### 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/react-native-face-liveness-ui\@1.0.0-beta1

#### 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/react-native-document-detector\@4.0.0-beta1

#### 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/react-native-document-detector-ui\@1.0.0-beta1

#### 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/react-native-sdk\@1.0.0-beta1

#### 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/react-native/getting-started-with-the-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.