> 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/ios/getting-started-with-the-sdk-4.md).

# Changelog

## Release notes

Latest changes for **CafSDK iOS**, ordered from newest to oldest.

### Release date

* 07/30/2026

### v7.4.1

#### Updates

* Updated the iProov dependency to **13.2.0** in `CafFaceLiveness`.
* **iProov SP change:** The liveness flow now follows the iProov SP provided by the backend. Server-side change — no integration changes required.

### v7.4.0

{% hint style="warning" %}
**Breaking change —Fingerprint dependency**

Starting in **v7.3.1**, `CafFingerprintProvider` is a separate, **opt-in** module and is no longer bundled automatically with Face Liveness. If your integration relies on device fingerprinting during the liveness flow, you must now add the module explicitly.

**CocoaPods** — add the subspec to your `Podfile`, alongside your existing Face Liveness install:

{% code overflow="wrap" %}

```
pod 'CafSDKiOS/CafFaceLiveness'pod 'CafSDKiOS/CafFingerprintProvider'   # enables fingerprinting
```

{% endcode %}

**Swift Package Manager** — add the `CafFingerprintProvider` product to your target (it is exposed independently from `CafFaceLiveness`):

{% code overflow="wrap" %}

```
.product(name: "CafFaceLiveness",        package: "CafSDKiOS"),.product(name: "CafFingerprintProvider", package: "CafSDKiOS")   
```

{% endcode %}
{% endhint %}

### Updates

* **Fingerprint SDK Upgrade**: The underlying FingerprintJS Pro SDK has been updated from version 2.7.0 to 2.16.0

### v7.0.0

#### Security

* Updated the **PayFace** provider to its latest version, strengthening security for the Face Liveness flow.

### v6.4.2

#### Improvements

* Analytics payloads now include richer and more standardized metadata across capture flows.

#### Security

* Added the `securityEnabled: Bool = false` property to `CafSDKConfiguration`, allowing security enforcement to be toggled programmatically. When set to `true`, the SDK performs strict security validation during initialization and execution; if a security violation is detected, the SDK throws a `securityException` and terminates the flow.

  ```swift
  let sdkConfig = CafSDKConfiguration(
      presentationOrder: [.faceLiveness, .documentDetector],
      securityEnabled: true
  )
  ```
* Removed the `CAFEnforceSecurity` `Info.plist` flag. Security enforcement is now controlled exclusively through the new `securityEnabled` property on `CafSDKConfiguration`. Existing integrations relying on the Info.plist flag must migrate to set `securityEnabled` programmatically.

#### Fixes

* Fixed issues affecting the RG document capture flow in `DocumentDetector`.

### v6.3.0

#### Improvements

* Removed the `KMP/CafSolutions` dependency from the liveness provider stack.
* Improved analytics payload quality with richer, more standardized metadata.

### v6.2.0

{% hint style="warning" %}
Versions earlier than `6.2.0` caused iProov Liveness to stop working after March 12, 2026. Use `6.2.0` or later.
{% endhint %}

#### Breaking changes

* Minimum supported iOS version is now **15.0+**.

#### Improvements

* Updated the iProov dependency to **13.1.0**.
* Added new `CafFailureType` cases:
  * `eyewear`
  * `faceNotFound`
  * `framesBlurry`
  * `lightingIssues`
  * `motionIssue`
  * `backgroundIssue`
  * `deviceIssue`
  * `deviceRestart`
  * `systemError`
  * `rejected`
  * `timeout`
  * `userNotFound`
  * `processingFault`

#### Important

* Reverse proxy support will be removed in a future release.
* An iProov-related update is required to avoid certificate issues.
* After **March 15, 2026**, **Face Liveness** and **Face Auth** services could become unavailable.

### v6.1.0

#### Improvements

* Updated the analytics implementation.

### v6.0.0

#### Breaking changes

* Renamed `CafInstructionsConfiguration` properties to support both capture and upload instruction screens:
  * `title` → `captureTitle`
  * `descriptionText` → `captureDescriptionText`
  * `steps` → `captureSteps`
  * `buttonTitle` → `captureButtonTitle`
  * `headerImage` → `captureHeaderImage`
* Added new upload instruction properties:
  * `uploadTitle`
  * `uploadDescriptionText`
  * `uploadSteps`
  * `uploadButtonTitle`
  * `uploadHeaderImage`

#### Security

* Added runtime protection checks for dynamic instrumentation and related threats.
* Added `securityException` to `CafErrorType`.
* The SDK now terminates the flow when it detects a security violation during initialization or execution.

### v5.7.0

#### New features

* Added `loadSession()` to `CafSDKProvider` for Face Liveness session preloading.
* While preloading runs, the unified callback emits `.loading` and `.loaded`.

#### Improvements

* Added analytics fields for better document capture visibility.
* `CafDocumentDetectorConfig.flow` now fails fast with `libraryException` when empty.
* Attestation and token validation now distinguish between network errors, invalid tokens, and invalid responses.

#### Behavior changes

* `manualCaptureTime` in `CafDocumentDetectorConfig` now defaults to `0` seconds.
* Manual capture remains configurable through `manualCaptureEnabled` and `manualCaptureTime`.

### v5.6.2

#### New features

* Added `faceAuthentication` to `CafErrorType` for backend errors when `executeFaceAuth` is enabled.

#### Improvements

* Improved analytics validation.

### v5.5.1

#### Fixes

* Fixed the `CafFaceLiveness` try-again flow.

#### Updates

* Downgraded Fingerprint from `2.7.0` to `2.6.0` due to compatibility issues.

### v5.5.0

#### New features

* Added optional **PayFace (Fortface)** provider support:
  * Swift Package Manager product: `FortfaceProvider`
  * CocoaPods subspec: `CafSDKiOS/FortfaceProvider`
* Added `flCustomizations` to `CafFaceLivenessConfig`.
* Added `CafFLPayFaceCustomization` for PayFace text and font customization.
* Added automatic localized side suffixes for `customTitles` in `CafSelectDocumentConfig`.

#### Documentation

* Updated getting started examples to include `FortfaceProvider` and `flCustomizations`.

### v5.4.4

#### New features

* Added per-document title and description overrides on the select-document screen through:
  * `CafSelectDocumentConfig.customTitles`
  * `CafSelectDocumentConfig.customDescriptions`
* These overrides affect both the selection list and the generated step labels.

### v5.4.3

#### Improvements

* Normalized error and failure messages for cleaner callback output.
* Failure screens now open full-screen for better consistency.

### v5.4.2

#### Fixes

* Improved completion reliability when no modal is presented.
* Providers now guarantee callbacks even when instruction or transition screens are disabled.
* Improved dismissal logic in Face Liveness and Document Detector to avoid stuck flows and missed callbacks.

### v5.4.1

#### Improvements

* Improved PDF upload validation with clearer messages for encrypted, locked, or unreadable files.
* Made cancellation behavior more consistent during document upload.

#### Fixes

* Fixed flow completion when transition screens are disabled.
* Fixed callback delivery in both batched and non-batched modes.
* Document selection now preserves the configured order when confirming multiple selections.

### v5.4.0

#### New features

* Added `enableTransitionScreens` to `CafSDKConfiguration`.
  * `true`: shows transition screens between modules.
  * `false`: runs modules sequentially without intermediate screens.
* Improved error handling and standardization across modules.
* Improved analytics for errors, sessions, and entrypoints.

#### Improvements

* Improved token validation messages for empty tokens and person IDs.

### v5.3.0

#### New features

* Added dialog customization colors to `CafColorConfiguration`:
  * `dialogBackgroundColor`
  * `dialogBorderColor`

### v5.2.0

#### New features

* Digital document flows for **RG Digital** and **CNH Digital** now:
  * force upload mode,
  * skip the photo source selection screen,
  * go directly to the upload flow.

#### Improvements

* `CafUploadSettings.enable` now defaults to `true`.
* Improved RG and CNH selection logic when front/back and full documents are available.
* Digital document options are now prioritized in selection screens.

#### Fixes

* Fixed an upload-flow issue caused by incorrect document selection.

### v5.1.0

#### Improvements

* Added security improvements to both Document Detector and `CafFaceLiveness`.
* Added `maxRetryAttempts` to Document Detector for server-error retry control.
* Default value: `2`.

#### Fixes

* `CafSDKProvider` initialization now correctly requires both `mobileToken` and `personId`.

### v5.0.2

#### Updates

* Updated the Xcode build version from `16.2` to `16.4`.

### v5.0.1

#### Improvements

* Updated `iProov` from `12.3.0` to `12.3.1`.

#### New features

* Moved `reverseProxyConfig: CafReverseProxyConfig` into `CafFaceLivenessConfig`.
* Consolidated `authBaseUrl`, `livenessBaseUrl`, and `certificates` under `CafFaceLivenessConfig`.
* Added `executeFaceAuth`.
* Added `maxRetryAttempts` to `CafFaceLivenessConfig`.

### v4.1.1

#### Improvements

* Improved hybrid analytics for **Flutter** and **React Native** integrations.

### v4.1.0

#### New features

* Added `customLocalization: String?` to Face Liveness builders.
* Added new Document Detector customization types:
  * `CafUploadMessagesCustomization`
  * `CafFailedPhotoCustomization`

### v4.0.0

#### Breaking changes

* `CafUnifiedResponse` now exposes only `signedResponse: String`.
* Removed the `[String: Any]` result dictionary.
* Added `invalidResponseException` to `CafErrorType`.
* Added retry support for interrupted or slow document uploads.

#### Migration notes

1. Update the dependency:
   * Swift Package Manager: `from: "4.0.0"`
   * CocoaPods: `pod 'CafSDKiOS', '~> 4.0.0'`
2. Update success handling to use `signedResponse`.
3. Remove all uses of `response.result`.
4. Add handling for `.invalidResponseException`.
5. If you relied on the old result dictionary, migrate to parsing the JWT in `signedResponse`.

```swift
case .success(let responses):
    responses.forEach { response in
        print("Module: \(response.moduleName) SignedResponse: \(response.signedResponse)")
    }
```

### v3.0.0

#### New features

* Improved analytics.
* Added detailed `.failure` handling to `CafUnifiedEvent`.
* Added `CafDDCustomization` and related customization types:
  * `CafPreviewCustomization`
  * `CafDDUploadCustomization`
  * `CafMessageCustomization`
* Added `customMessage` and `customOkButtonTitle` to `CafDocumentDetectorStep`.

#### Improvements

* Improved differentiation between operational failures and general execution errors.
* Document Detector now inherits its theme primarily from the global `CafColorConfiguration`.

#### Breaking changes

* `.failure` now uses `CafFailureType`.
* `.error` now uses `CafErrorType`.
* `CafDocumentDetectorConfig` no longer supports:
  * `previewTitle`
  * `previewSubtitle`
  * `previewConfirmLabel`
  * `previewRetryLabel`
  * `messageSettings`
* `CafDocumentDetectorLayout` no longer supports:
  * `primaryColor`
  * `uploadBackGroundColor`
  * `previewBackGroundColor`

#### Migration notes

1. Update `.failure` handling:

```swift
case .failure(response: String?, type: CafFailureType, description: String?)
```

2. Update `.error` handling:

```swift
case .error(type: CafErrorType, description: String)
```

3. Replace removed preview and message settings with `ddCustomizations`.
4. Replace step popup overrides with `customMessage` and `customOkButtonTitle`.
5. Move Document Detector color customization to the global `CafColorConfiguration`.

### v2.0.0

#### New features

* `CafSDKConfiguration(waitForAllServices: true)` now batches all module responses into a single `.success`.
* `.success` now always returns an array of responses.

#### Breaking changes

* `CafUnifiedEvent.success` changed to `success(responses: [CafUnifiedResponse])`.

#### Migration notes

1. Update to `v2.0.0` or later.
2. Change success handling to expect an array:

```swift
case .success(let responses):
    responses.forEach { response in
        // Handle each module response
    }
```

### v1.4.0

#### New features

* Introduced `CafSDKProvider` as the unified entry point for Face Liveness and Document Detector.
* Added `CafSDKProvider.Builder` for modular, type-safe setup.
* Added `CafSDKConfiguration` for execution order and shared UI theming.
* Unified authentication, environment, and logging across modules.

#### Documentation

* Revised Swift Package Manager and CocoaPods integration guides.
* Added detailed examples for `CafFaceLivenessConfig` and `CafDocumentDetectorConfig`.

#### Configuration enhancements

* Face Liveness:
  * instruction customization with `CafInstructionsConfiguration`
  * reverse proxy endpoints with `authBaseUrl` and `livenessBaseUrl`
* Document Detector:
  * multi-step capture flow with `[CafDocumentDetectorStep]`
  * UI customization with `CafDocumentDetectorLayout` and `CafMessageSettings`
  * proxy support with `CafProxySettings`

#### Breaking changes

* Added the new integration module: `CafSDK`
* Renamed modules:
  * `FaceLiveness` → `CafFaceLiveness`
  * `DocumentDetector` → `CafDocumentDetector`
* Updated minimum tooling:
  * Xcode `16.2+`
  * iOS `13.0+`

#### Migration notes

1. Replace standalone module initializers with `CafSDKProvider`.
2. Update enum cases to lowercase, for example `.CNH_FRONT` → `.cnhFront`.
3. Use `CafDocumentDetectorStep(stepType:)` instead of legacy constructors.


---

# 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/ios/getting-started-with-the-sdk-4.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.