> 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/document-detector.md).

# Document Detector

Install and launch Document Detector for Flutter. Learn configuration options, UI setup, customization paths, event streams, and result handling.

{% hint style="warning" %}
This guide covers **caf\_sdk 2.4.0** and above (Certta DevX). For the previous `CafSdk` sequential flow, see the [legacy documentation](https://docs.caf.io/caf-sdk/flutter/getting-started-with-the-sdk).
{% endhint %}

## Prerequisites

Before proceeding, ensure the Certta SDK is properly installed. If you haven't done this yet, please refer to our Installation Guide.

{% content-ref url="/pages/8imRjz3wgDSO5c2vhnO5" %}
[Installation Guide](/caf-sdk/flutter/installation-guide.md)
{% endcontent-ref %}

Enable `documentDetector` (and `documentDetectorUI` if you want the built-in UI) in `caf-modules-config.json`.

Subscribe to the matching `eventStream` **before** calling `open()`.

## Starting Document Detector

To start the Document Detector flow, call `certta.documentDetector.open()` and pass a `CerttaDocumentDetectorConfiguration` object.

{% hint style="info" %}
`CerttaDocumentDetectorConfiguration` and `CerttaDocumentDetector` are the headless Document Detector module. The `flow` list is required.
{% endhint %}

```dart
import 'package:flutter/services.dart';
import 'package:caf_sdk/certta_sdk.dart';

final certta = CerttaSdk();

certta.documentDetector.eventStream.listen((event) {
  if (event.success != null) {
    // Handle success — event.success!.response is a JWT
  } else if (event.error != null) {
    // Handle error
  }
});

try {
  await certta.documentDetector.open(
    CerttaDocumentDetectorConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
    ),
  );
} on PlatformException catch (e) {
  // Handle BRIDGE_EXCEPTION
}
```

`open()` throws a `PlatformException` with code `BRIDGE_EXCEPTION` when the native mapper rejects the configuration.

### `CerttaDocumentDetectorConfiguration` parameters

| Parameter                     | Default | Description                                                             |
| ----------------------------- | ------- | ----------------------------------------------------------------------- |
| `flow`                        | *None*  | Ordered list of capture steps. **Required.**                            |
| `uploadSettings`              | `null`  | Settings for uploading document images.                                 |
| `showPreview`                 | `true`  | Shows a preview screen for user confirmation when `true`.               |
| `requestTimeout`              | `60`    | Maximum time (in seconds) for network requests.                         |
| `showPopup`                   | `false` | Displays a guidance popup during capture when `true`.                   |
| `maxRetryAttempts`            | `3`     | Maximum retries after a failed capture. Use `-1` for unlimited retries. |
| `messageCustomization`        | `null`  | In-flow capture messages.                                               |
| `previewCustomization`        | `null`  | Preview screen copy.                                                    |
| `uploadCustomization`         | `null`  | Upload dialog copy.                                                     |
| `uploadMessagesCustomization` | `null`  | Messages shown while the document is sent and processed.                |
| `retryCustomization`          | `null`  | Retry screen copy.                                                      |

## Starting Document Detector UI

To launch Document Detector with the customized UI module, call `certta.documentDetectorUi.open()` and pass a `CerttaDocumentDetectorUiConfiguration`.

{% hint style="info" %}
Enable `documentDetectorUI` in `caf-modules-config.json`. The native layer maps `flow` into the document selection screen.
{% endhint %}

```dart
import 'package:flutter/services.dart';

try {
  await certta.documentDetectorUi.open(
    CerttaDocumentDetectorUiConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
      documentSelectionScreen:
          const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
        title: 'Choose a document',
        description: 'Select the document you want to use',
      ),
    ),
  );
} on PlatformException catch (e) {
  // Handle BRIDGE_EXCEPTION
}

certta.documentDetectorUi.eventStream.listen((event) {
  if (event.success != null) {
    // Handle success
  } else if (event.error != null) {
    // Handle error
  }
});
```

### `CerttaDocumentDetectorUiConfiguration` parameters

Inherits every field from `CerttaDocumentDetectorConfiguration`, plus:

| Parameter                 | Default | Description                                                               |
| ------------------------- | ------- | ------------------------------------------------------------------------- |
| `instructionScreen`       | `null`  | Instructions shown before camera or file gallery.                         |
| `documentSelectionScreen` | `null`  | Title and description of the document picker. Documents come from `flow`. |

### Deep dive into customizations

{% content-ref url="/pages/0TegyBTuSJdamfST2Vfc" %}
[UI Customizations](/caf-sdk/flutter/document-detector/ui-customizations.md)
{% endcontent-ref %}

## Supported documents

| Document     | 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.                                                                           |
| `PASSPORT`   | Passport document, displaying the photo and personal data.                                                      |
| `CTPS_FRONT` | Front side of the CTPS document, where the photo is located.                                                    |
| `CTPS_BACK`  | Back side of the CTPS document.                                                                                 |
| `ANY`        | Allows submission of any type of document, including all those listed above or any other unclassified document. |

In Dart, use the `CafDocument` enum (`CafDocument.rgFront`, `CafDocument.cnhBack`, `CafDocument.passport`, and so on). The values above are the serialized identifiers.

### Supported file formats (`CafFileFormat`)

Used by `CafDocumentDetectorUploadSettings.fileFormats`.

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

{% hint style="info" %}
Full HEIC support is available on iOS only.
{% endhint %}

## Understanding Document Detector events and results

### `success` (`CerttaSuccess`)

Triggered when the document is captured and processed successfully.

* `response`: a JWT with the result data from the Document Detector flow.

{% 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 %}

### `error` (`CerttaError`)

Triggered when capture fails (network issues, user cancellation, camera permission denials, or configuration errors).

* `type`: error identifier mapped from the native SDK.
* `cause`: additional context, when present.

| Event                 | Typical cause                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `InitializationError` | **`configure`** not called, empty token or user ID, or invalid **`maxRetryAttempts`**.                                              |
| `PermissionError`     | Camera (or related) permission denied.                                                                                              |
| `NetworkError`        | Connectivity or server-side issues surfaced as network class errors.                                                                |
| `SecurityError`       | Security checks failed.                                                                                                             |
| `UnknownError`        | Other failures not mapped to a specific case.                                                                                       |
| `Cancelled`           | Occurs when the user abandons the flow before completion, such as by pressing the back button or sending the app to the background. |


---

# 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/document-detector.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.