> 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/flutter/changelog.md).

# Changelog

Flutter SDK release notes. Track versions, breaking changes, provider updates, and migration notes for Certta, Face Liveness, and Document Detector.

## Release notes

{% hint style="danger" %}
Due to a Payface obfuscation error, version **2.3.0** have been deprecated and should no longer be used. For more information, please contact our support team.
{% endhint %}

### caf\_sdk\@2.5.0

#### **Release date**

* 10/13/2026

#### **Highlights**

* **Android: result recovery after process death.** If the OS kills the app process while a Caf, Certta Document Detector or Certta Document Detector UI flow is open (for example, the user stays in the gallery during an upload), the result is no longer lost. It is delivered to the Dart stream once your app subscribes to it again.

#### **Updates**

* Recovered results are delivered through the same streams you already use: `eventStream` (`CafSdk`), `CerttaDocumentDetectorEvent` and `CerttaDocumentDetectorUiEvent`. No new events, names or payloads.
* Subscribe to the stream as early as possible (for example, in `initState` of your first screen). A recovered event is delivered when the listener attaches.
* Only the last result is kept. Face Liveness flows are not recovered.
* Android only. iOS behavior is unchanged.
* No API changes and no migration needed.

### caf\_sdk\@2.4.0

#### Release date

* 09/28/2026

#### Highlights

* **Certta DevX (first hybrid release):** New `CerttaSdk` API with Document Detector and Face Liveness (core and UI) on Android and iOS.
* Configure the session once with `configureSdk(CerttaConfiguration)`, then open each module independently (`liveness.open`, `documentDetector.open`, `documentDetectorUi.open`).
* The sequential `CafSdk` / `initializeCafSdk` API remains available in the same package.

#### Updates

* New public import: `package:caf_sdk/certta_sdk.dart`.
* Per-module event streams (`CerttaLivenessEvent`, `CerttaDocumentDetectorEvent`, `CerttaDocumentDetectorUiEvent`) and `CerttaSdk.logStream`.
* Runtime `updateUserId` / `updateMobileToken` after the initial session configuration.
* `CerttaLivenessFailure` with stable `cause` codes and `description` for user-facing text.
* Bridge mapper rejections throw `PlatformException` with code `BRIDGE_EXCEPTION`.

See the [Installation Guide](/caf-sdk/flutter/installation-guide.md) and [Migrating from CafSdk](/caf-sdk/flutter/migrating-from-cafsdk.md).

### caf\_sdk\@2.2.0

#### **Release date**

* 08/14/2026

#### **Highlights**

* **Android 16 compatibility:** Updated Flutter plugin 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**

* Flutter Plugin `compileSdk` / `targetSdk` updated to **36**.

### caf\_sdk\@2.1.0

#### Release date

* 08-03-2026

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

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

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

### caf\_sdk\@2.0.0

#### Release date

* 07-06-2026

{% hint style="warning" %}
**Breaking change:** The `eventStream` now emits a **typed `Stream<CafResponse>`** instead of a `Stream<dynamic>` with raw `Map` payloads. Update every listener: replace `event['eventName']` / `event['response']` with the typed fields — `event.success`, `event.error`, `event.failure`, `event.log`, `event.loading`, `event.loaded`, and `event.cancelled`. See [Event Handling](/caf-sdk/flutter/getting-started-with-the-sdk.md#event-handling) for the full migration example.
{% endhint %}

#### Highlights

* **More consistent error reporting**: Errors occurring during flow initialization that relate to the SDK's internal integration are now emitted via the `error` event as `BRIDGE_EXCEPTION`, so they can be handled the same way as any other SDK error.

#### Breaking Changes

* **Typed event stream**: `CafSdk.eventStream` is now `Stream<CafResponse>`. Consumers must access the typed fields of `CafResponse` (`success`, `error`, `failure`, `log`, `loading`, `loaded`, `cancelled`) instead of indexing a `Map`.
* **Flattened module configuration classes**: The per-module `...BuilderConfiguration` wrappers were removed. Fields are now passed directly on the module configuration objects, and the UI configurations extend the base configuration instead of nesting it:
  * `CafFaceLivenessBuilderConfiguration` removed — pass fields directly on `CafFaceLivenessConfiguration`.
  * `CafDocumentDetectorBuilderConfiguration` removed — pass fields directly on `CafDocumentDetectorConfiguration`.
  * `CafFaceLivenessUIBuilderInstructionScreenConfiguration` → `CafFaceLivenessUIInstructionScreenConfiguration`, and the field `instructionScreenConfiguration` → `instructionScreen`.
  * `CafDocumentDetectorUIBuilderInstructionScreenConfiguration` → `CafDocumentDetectorUIInstructionScreenConfiguration`, and the field `instructionScreenConfiguration` → `instructionScreen`.
  * `CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration` → `CafDocumentDetectorUIDocumentSelectionScreenConfiguration`, and the field `documentSelectionScreenConfiguration` → `documentSelectionScreen`.
  * The SDK-level `CafSdkConfiguration` is unchanged and still takes `configuration: CafSdkBuilderConfiguration(...)`.
* **`initializeCafSdk` return type**: changed from `Future<bool?>` to `Future<bool>`.

#### Updates

* **Event name constants**: Added the `CafSdkEventName` constants (`CafUnifiedEvent.*`) for identifying emitted events.
* **New `CafErrorType` values**: Added `INVALID_RESPONSE_EXCEPTION`, `CAMERA_EXCEPTION`, `FACE_AUTHENTICATION`, and `BRIDGE_EXCEPTION`. Note that `BRIDGE_EXCEPTION` reports errors that occur while initializing or starting the flow; listen for it on the `error` event and handle it as part of your normal error handling.
* **`CafSuccessResponse`**: `signedResponse` is now typed as `String?` (previously `dynamic`), and `moduleName` resolution is more resilient to native identifier variations.

#### Migration Guide — 1.x → 2.0.0

Three things changed for integrators: how you read events, how you build module configurations, and the return type of `initializeCafSdk`. The SDK-level `CafSdkConfiguration` (with `CafSdkBuilderConfiguration`) is unchanged.

**1. Read events from the typed stream**

```dart
// Before (1.x) — raw Map
_cafSdk.eventStream.listen((event) {
  final name = event['eventName'];
  final response = event['response'];
});

// After (2.0.0) — typed CafResponse
_cafSdk.eventStream.listen((event) {
  if (event.success != null) {
    print('${event.success!.moduleName} -> ${event.success!.signedResponse}');
  } else if (event.error != null) {
    print('${event.error!.type} - ${event.error!.description}');
  }
  // also: event.failure, event.log, event.loading, event.loaded, event.cancelled
});
```

**2. Remove the module `...BuilderConfiguration` wrapper**

Pass the fields directly on the module configuration object.

```dart
// Before (1.x)
final faceLivenessConfig = CafFaceLivenessConfiguration(
  configuration: CafFaceLivenessBuilderConfiguration(
    loading: true,
    maxRetryAttempts: 2,
  ),
);

// After (2.0.0)
final faceLivenessConfig = CafFaceLivenessConfiguration(
  loading: true,
  maxRetryAttempts: 2,
);
```

```dart
// Before (1.x)
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  configuration: CafDocumentDetectorBuilderConfiguration(
    flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
    manualCaptureEnabled: false,
  ),
);

// After (2.0.0)
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  manualCaptureEnabled: false,
);
```

**3. Update the UI configurations (wrapper + renamed types and fields)**

```dart
// Before (1.x)
final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  configuration: CafFaceLivenessBuilderConfiguration(loading: true),
  instructionScreenConfiguration:
      CafFaceLivenessUIBuilderInstructionScreenConfiguration(title: 'Face Liveness'),
);

// After (2.0.0)
final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  loading: true,
  instructionScreen:
      CafFaceLivenessUIInstructionScreenConfiguration(title: 'Face Liveness'),
);
```

```dart
// Before (1.x)
final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  configuration: CafDocumentDetectorBuilderConfiguration(
    flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  ),
  instructionScreenConfiguration:
      CafDocumentDetectorUIBuilderInstructionScreenConfiguration(enable: true),
  documentSelectionScreenConfiguration:
      CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration(title: 'Choose document'),
);

// After (2.0.0)
final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  instructionScreen:
      CafDocumentDetectorUIInstructionScreenConfiguration(enable: true),
  documentSelectionScreen:
      CafDocumentDetectorUIDocumentSelectionScreenConfiguration(title: 'Choose document'),
);
```

**4. Rename type imports (if you imported the removed types)**

| Removed (1.x)                                                      | Use instead (2.0.0)                                         |
| ------------------------------------------------------------------ | ----------------------------------------------------------- |
| `CafFaceLivenessBuilderConfiguration`                              | `CafFaceLivenessConfiguration`                              |
| `CafDocumentDetectorBuilderConfiguration`                          | `CafDocumentDetectorConfiguration`                          |
| `CafFaceLivenessUIBuilderInstructionScreenConfiguration`           | `CafFaceLivenessUIInstructionScreenConfiguration`           |
| `CafDocumentDetectorUIBuilderInstructionScreenConfiguration`       | `CafDocumentDetectorUIInstructionScreenConfiguration`       |
| `CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration` | `CafDocumentDetectorUIDocumentSelectionScreenConfiguration` |

**5. Update the `initializeCafSdk` return type**

`initializeCafSdk` now returns `Future<bool>` instead of `Future<bool?>`. Remove any null checks on the awaited result.

```dart
// Before (1.x)
final bool? started = await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
);
if (started == true) {
  // ...
}

// After (2.0.0)
final bool started = await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
);
if (started) {
  // ...
}
```

### caf\_sdk\@1.5.0

#### Release date

* 05-25-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\_sdk\@1.4.0

#### Release date

* 05-08-2026

#### Fixes

* **DocumentDetector**: Fixed behavior when handling RG (Brazilian National Identity Card) with the digital document option.

### caf\_sdk\@1.3.0

#### Release date

* 04-13-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](/caf-sdk/flutter/installation-guide.md#step-2-configure-module-selection) for details.
{% endhint %}

#### Highlights

* **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 [Code obfuscation](/caf-sdk/flutter/installation-guide.md#code-obfuscation)):

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

### caf\_sdk\@1.2.0

#### Release date

* 02-09-2026

{% hint style="warning" %}
Versions earlier than 1.2.0 will result iProov Liveness to become inoperable as of March 12, 2026. To ensure proper functionality and service continuity, please use version 1.2.0 or later.
{% endhint %}

#### Highlights

* **Updated Liveness Provider**: Critical update to the iProov provider version for improved stability

#### Updates

* **iProov Liveness Provider**: Updated the internal iProov provider version.

### caf\_sdk\@1.1.0

#### Release date

* 02-09-2026

#### Highlights

* **New Security Module**: Introduction of `CafSecurity` module for security validations
* **PayFace Integration**: Added support for PayFace (Fortface) as an optional Face Liveness provider
* **Stability Improvements**: Major crash fixes and stability improvements for the Document Detector module

#### Features

* **CafSecurity Module**:
  * Added a new module specifically for security validations
  * **Configuration**: Added `enableSecurityModule` flag in `CafSdkConfiguration` (default value: `true`)
* **PayFace (Fortface) Integration**:
  * Optional Face Liveness provider integration
  * **Configuration**: New property `payFaceDebugMode` in `CafFaceLivenessConfiguration` to enable debug mode for the PayFace provider

#### Fixes

* **DocumentDetector**:
  * **Activity Lifecycle**: Resolved multiple crashes related to activity lifecycle management (initialization, pause, and resume states)
  * **Camera Lifecycle**: Improved camera resource management and thread lifecycle to prevent crashes during SDK shutdown
  * **UI Components**: Resolved theme compatibility issues and fragment transaction exceptions
  * **Network Requests**: Corrected response body handling to prevent errors when reading network responses
  * **Data Access**: Improved cursor initialization and validation before accessing database data
  * **ANR Prevention**: Optimized document controller instance checks to prevent "Application Not Responding" issues
  * **General**: Internal improvements and stability corrections
* **FaceLiveness**:
  * **Sessions**: Fixed session creation errors
  * **UI**: Fixed color tint on remote images in the Instructions screen

#### Updates

* **Build Configuration**:
  * **ProGuard Rules**: Added necessary ProGuard rules for PayFace integration

### caf\_sdk\@1.0.1

#### Release date

* 03-09-2026

#### Updates

* **Updated iProov Liveness Provider**: Update iProov provider version.
* **Updated iOS minimum deployment target**: Updated to `15.0`.

#### Fixes

* **DocumentDetector**
  * **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\_sdk\@1.0.0

#### Release date

* 10-27-2025

#### Highlights

* **First Flutter SDK Release**: Complete Flutter implementation of the CAF SDK for identity verification
* **Unified SDK**: Single package containing all CAF modules (Face Liveness and Document Detector) with both core and UI variants
* **Flutter-Native Integration**: Seamless integration with Flutter's widget system and state management
* **Cross-Platform Support**: Full support for both Android and iOS platforms
* **Type-Safe Configuration**: Strongly typed Dart configuration classes for better development experience

#### Features

* **Module Configuration System**:
  * **`caf-modules-config.json`**: 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
    }
    ```
* **Core SDK Features**:
  * **CafSdk Class**: Main SDK class for initialization and configuration
  * **Event Stream**: Real-time event handling through Dart streams
  * **Module Management**: Sequential execution of modules with configurable presentation order
  * **Error Handling**: Comprehensive error types and failure handling
  * **Configuration Builder**: Type-safe configuration using builder pattern
* **Face Liveness Module**:
  * **Core Module**: `CafFaceLivenessConfiguration` for programmatic control
  * **UI Module**: `CafFaceLivenessUIConfiguration` with customizable instruction screens
  * **Features**: Authentication URLs, certificate pinning, debug mode, retry attempts
  * **Customization**: Instruction screens with images, titles, descriptions, and steps
* **Document Detector Module**:
  * **Core Module**: `CafDocumentDetectorConfiguration` for programmatic control
  * **UI Module**: `CafDocumentDetectorUIConfiguration` with full UI customization
  * **Document Types**: Support for RG, CNH, Passport, RNE, CTPS, and more
  * **Upload Support**: File upload with compression, format control, and size limits
  * **Proxy Configuration**: Support for proxy servers with authentication
  * **Message Customization**: Customizable user messages throughout the flow
* **Advanced Configuration**:
  * **Color Theming**: Complete UI color customization through `CafColorConfiguration`
  * **Security Settings**: Development flags, debug mode, and security controls
  * **Flow Control**: Manual capture, timeouts, retry attempts, and popup controls
  * **Instruction Screens**: Customizable instruction screens for both modules

#### Technical Implementation

* **Flutter Integration**:
  * **Method Channels**: Native communication through Flutter's method channel system
  * **Stream-Based Events**: Real-time event handling using Dart streams
  * **State Management**: Proper lifecycle management with `StatefulWidget` support
  * **Error Handling**: Comprehensive error handling with typed exceptions
* **Platform Support**:
  * **Android**: Full support with ProGuard/R8 rules and Maven repository configuration
  * **iOS**: Complete integration with CocoaPods and native iOS modules
  * **Permissions**: Proper permission handling for camera and network access
* **Performance**:
  * **Selective Module Loading**: Only load enabled modules to optimize bundle size
  * **Memory Management**: Proper resource cleanup and memory management
  * **Network Optimization**: Efficient network communication with retry mechanisms

#### Installation and Setup

* **Package Installation**: Simple installation via `flutter pub add caf_sdk`
* **Module Configuration**: Easy module selection through JSON configuration file
* **Platform Setup**: Clear instructions for Android and iOS platform configuration
* **Permission Management**: Comprehensive permission setup for both platforms

#### Documentation

* **Complete Examples**: Full implementation examples for both basic and advanced usage
* **Configuration Guide**: Detailed configuration options for all modules
* **Event Handling**: Comprehensive event handling examples and patterns
* **Error Reference**: Complete error types and failure scenarios documentation

#### Breaking Changes

* **First Release**: This is the first release of the Flutter SDK, so there are no breaking changes from previous versions.

#### Known Issues

* **iOS Simulator**: Some features may not work properly in iOS Simulator due to camera limitations
* **Android Emulator**: Camera-dependent features require physical devices for testing
* **Network Requirements**: All modules require internet connectivity for proper operation


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-sdk/flutter/changelog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.