> 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-3.md).

# Smart Capture

{% hint style="warning" %}

## This guide covers version 7.0.0 and above. For versions below 7.0.0, please see the [legacy documentation](/caf-sdk/ios/getting-started-with-the-sdk-5.md).

{% endhint %}

### Overview

**Smart Capture** captures identity documents with guided flows and optional **auto capture** and **preview**. It uses the same **Certta** session as Face Liveness and Document Detector: **configure** credentials once, then open the capture UI.

On iOS, Smart Capture is integrated through **`CerttaSmartCapture`**, **`CerttaSmartCaptureDelegate`** and the **SmartCapture** framework module. **`CerttaSmartCaptureConfiguration`** maps to **`CafSmartCaptureConfig`** for the unified **`CafSDKProvider`** pipeline.

If **SmartCapture** is not linked in your target, the SDK cannot register a Smart Capture service; **`CafSDKProvider`** will not add a capture module for that flow (link the product as required by your distribution).

For **Certta session** setup (token, user ID, environment), see the **Certta session (quick start)**. For **Document Detector** (step-based flow, **`CerttaDocumentDetectorConfiguration`**), see **Document Detector for iOS (Certta)**.

***

### Prerequisites

Before proceeding, ensure the **CAF SDK** is properly installed. If you have not done this yet, refer to our **installation guide** (Swift Package Manager or CocoaPods).

You also need:

* **Camera** permission string in **Info.plist** (**`NSCameraUsageDescription`**).
* **Active Certta session** — **`Certta.shared.configure(configuration:)`** with non-empty **`mobileToken`** and **`userID`** (same contract as Face Liveness and Document Detector).
* **SmartCapture** framework linked in your target, in addition to **CafSDK** and any other products your integration requires (see your package / Pod instructions).

```xml
<key>NSCameraUsageDescription</key>
<string>We need the camera to capture your document.</string>
```

***

### CerttaSmartCaptureConfiguration

These map internally to **`CafSmartCaptureConfig`** for the unified **`CafSDKProvider`** pipeline.

All parameters have defaults; override only what you need.

| Parameter            | Type           | Description                                                                   |
| -------------------- | -------------- | ----------------------------------------------------------------------------- |
| **`requestTimeout`** | `TimeInterval` | Network / request timeout in seconds. Default: **`60`**.                      |
| **`previewEnabled`** | `Bool`         | Whether the post-capture **preview** step is enabled. Default: **`true`**.    |
| **`autoCapture`**    | `Bool`         | Whether **automatic capture** is enabled when supported. Default: **`true`**. |

***

### Starting Smart Capture

Use the **`CerttaSmartCapture`** singleton. Set **`delegate`** (or conform the presenting **`UIViewController`** to **`CerttaDocumentDetectorDelegate`**); resolution matches Document Detector: **`delegate ?? (presenter as? CerttaDocumentDetectorDelegate)`**.

```swift
CerttaSmartCapture.shared.delegate = self

CerttaSmartCapture.shared.open(
    from: self,
    configuration: CerttaSmartCaptureConfiguration(
        requestTimeout: 60,
        previewEnabled: true,
        autoCapture: true
    )
)
```

**`loadSession(from:configuration:)`** is available with the same **`CerttaSmartCaptureConfiguration`** to preload resources before **`open`**. Unified **`.loading` / `.loaded`** events are **not** delivered to **`CerttaDocumentDetectorDelegate`**; use **`didLog`** for diagnostics where needed.

***

### Understanding Smart Capture events and results

Smart Capture uses the same **`CerttaDocumentDetectorDelegate`** as **Document Detector** so session, success, failure, and cancel handling stay consistent across Certta document products.

```swift
extension MyViewController: CerttaDocumentDetectorDelegate {

    func didFinish(signedResponse: String) {
        // Success — signed JWT / payload from CAF
    }

    func didFail(_ failure: CerttaDocumentDetectorFailure) {
        switch failure {
        case .processingFailed(let result, let cause):
            break
        }
    }

    func didFinishWith(_ error: CerttaError) {
        switch error {
        case .initializationError(let message): break
        case .permissionError(let message): break
        case .securityError(let message): break
        case .unknownError(let message): break
        case .networkError(let message): break
        }
    }

    func didCancel() {
        // User dismissed the flow
    }

    func didLog(level: String, message: String) {
        // Progress and informational messages
    }
}
```

#### `didFinish(signedResponse:)`

The string is the **signed result** from the module. Your backend or CAF integration documentation defines how to validate, decode, and store it. **Do not log the full token in production builds.**

#### `didFail(_ failure: CerttaDocumentDetectorFailure)`

Processing failures from the pipeline — today **`processingFailed(result:cause:)`**.

#### `didFinishWith(_ error: CerttaError)`

Blocking errors (session not configured, **camera permission**, **network**, **security**, **initialization**, etc.). **`CerttaError`** aligns with **Face Liveness** and other Certta modules. Use **`localizedDescription`** / **`message`** in alerts.

#### `didCancel()`

The user **cancelled** the flow. Return to the previous screen or offer retry.

#### `didLog(level:message:)`

Progress and informational events; map to UI or analytics as needed.

#### Types for other APIs

**`CerttaSmartCaptureEvent`**, **`CerttaSmartCaptureResult`**, and **`CerttaSmartCaptureFailure`** exist for higher-level or future APIs. The **Certta** path above uses **`CerttaDocumentDetectorDelegate`** for consistency with Document Detector and Face Liveness.

***

### Session and theming

Call **`Certta.shared.configure(configuration:)`** before **`open`** or **`loadSession`**.

Optional **`Certta.shared.setColorConfiguration(_:)`** applies when the Smart Capture UI reads session colors from **Certta** (same pattern as Document Detector and Face Liveness).

**Dark / light mode:** build **`CafColorConfiguration`** using **`UITraitCollection.current.userInterfaceStyle`** if you need different palettes per mode.

```swift
Certta.shared.setColorConfiguration(
    CafColorConfiguration(
        primaryColor: "#FFFFFF",
        secondaryColor: "#222222",
        contentColor: "#FFFFFF",
        backgroundColor: "#000000",
        mediumColor: "#555555",
        dialogBackgroundColor: "#1C1C1E",
        dialogBorderColor: "#E5E5E7"
    )
)
```

***

### Choosing Document Detector vs Smart Capture

| Product               | Entry point                         | Configuration                                                                           |
| --------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| **Smart Capture**     | **`CerttaSmartCapture.shared`**     | **`CerttaSmartCaptureConfiguration`** (timeout, preview, auto capture)                  |
| **Document Detector** | **`CerttaDocumentDetector.shared`** | **`CerttaDocumentDetectorConfiguration`** (flow steps, layout, upload, instructions, …) |

Both use **`CerttaDocumentDetectorDelegate`** and the same Certta session. Pick **Smart Capture** for the guided Smart Capture product; pick **Document Detector** when you need the classic step-based document flow and hub configuration described in **Document Detector for iOS (Certta)**.

***

### Release notes

See [**GitHub Releases**](https://github.com/combateafraude/caf-ios-sdk) for versions, breaking changes, and minimum Xcode / iOS.

***

### Technical support and usage tips

For more details and advanced usage scenarios, refer to the following resources:

* **GitHub repository:** source code, issue tracking, and release notes in the [CafSDK GitHub repository](https://github.com/combateafraude/caf-ios-sdk).
* **Document Detector (Certta):** Document Detector for iOS (Certta) — same delegate, different configuration and flow.
* **Document Detector configurations:** Document Detector configurations — **`CafDocumentDetectorConfig`** when using the Document Detector path or **`CafSDKProvider.Builder`**.
* **FAQs and troubleshooting:** check our FAQ section for common issues and troubleshooting tips.
* **Support:** for additional assistance, contact our support team or join our developer community forum.

We continuously update the documentation as new features and improvements are released. Stay up to date for future updates!


---

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