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

# Document Detector

{% hint style="warning" %}
This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the [legacy documentation](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% 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/wE8ByH57MIhDucnUQi54" %}
[Installation Guide](/caf-sdk/android/installation-guide.md)
{% endcontent-ref %}

## Starting Document Detector

To start the Document Detector flow, call `DocumentDetector.instance.open()` and pass a `DocumentDetectorConfiguration` object.

{% hint style="info" %}
This method accepts a callback to handle the results and events triggered during the Document Detector flow.
{% endhint %}

{% hint style="info" %}
The `DocumentDetectorConfiguration` and `CerttaDocumentDetector` classes are components of the `io.caf.sdk:document-detector` module.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(Document.RG_FRONT),
        DocumentDetectorStep(Document.RG_BACK)
    )
)
CerttaDocumentDetector.instance.open(config) { event ->
    when(event) {
        is DocumentDetectorEvent.Success -> {
            //handle success
        }
        is DocumentDetectorEvent.Error -> {
            //handle error
        }
    }
}

```

{% endtab %}

{% tab title="Java" %}

<pre class="language-java"><code class="lang-java"><strong>var config = new DocumentDetectorConfiguration(
</strong>    Arrays.asList(
        new DocumentDetectorStep(Document.RG_FRONT),
        new DocumentDetectorStep(Document.RG_BACK)
    )
);
CerttaDocumentDetector.getInstance().open(config, event -> {
    if (event instanceof DocumentDetectorEvent.Success) {
        var successEvent = (DocumentDetectorEvent.Success) event;
        // handle success
    } else if (event instanceof DocumentDetectorEvent.Error) {
        var errorEvent = (DocumentDetectorEvent.Error) event;
        // handle error
    }
});

</code></pre>

{% endtab %}
{% endtabs %}

### `DocumentDetectorConfiguration` Parameters

| Parameter          | Default                           | Description                                                                                                       |
| ------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `flow`             | *None*                            | The ordered list of steps defining which documents to capture (e.g., front and back). This parameter is required. |
| `uploadSettings`   | `UploadSettings(false)`           | Configuration settings for uploading the captured document images.                                                |
| `showPreview`      | `true`                            | Shows a preview screen of the captured document for user confirmation when true.                                  |
| `requestTimeout`   | `60`                              | The maximum allowed time (in seconds) for network requests to complete before timing out.                         |
| `showPopup`        | `false`                           | Displays a guidance popup during the capture process when true.                                                   |
| `customization`    | `DocumentDetectorCustomization()` | An object containing visual customization and branding settings for the detector UI.                              |
| `maxRetryAttempts` | `3`                               | Maximum retries after a failed capture attempt.                                                                   |

## Starting Document Detector UI

To launch the Document Detector flow with a customized user interface, call `CerttaDocumentDetectorUi.instance.open()` and pass a `DocumentDetectorUiConfiguration` object.

{% hint style="info" %}
The `DocumentDetectorUiConfiguration` and `CerttaDocumentDetectorUi` classes are components of the `io.caf.sdk:document-detector-ui` module.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront(), CafDocument.RGBack()),
    )
)
CerttaDocumentDetectorUi.instance.open(config) { event ->
    when(event) {
        is DocumentDetectorEvent.Success -> {
            //handle success
        }
        is DocumentDetectorEvent.Error -> {
            //handle error
        }
    }
}

```

{% endtab %}

{% tab title="Java" %}

```java
var config = new DocumentDetectorUiConfiguration(
    new CafDocumentDetectorDocumentSelectionScreen(
        Arrays.asList(new CafDocument.RGFront(), new CafDocument.RGBack())
    )
);
CerttaDocumentDetectorUi.getInstance().open(config, event -> {
    if (event instanceof DocumentDetectorEvent.Success) {
        var successEvent = (DocumentDetectorEvent.Success) event;
        // handle success
    } else if (event instanceof DocumentDetectorEvent.Error) {
        var errorEvent = (DocumentDetectorEvent.Error) event;
        // handle error
    }
});
```

{% endtab %}
{% endtabs %}

### `DocumentDetectorUiConfiguration` Parameters

| Parameter                 | Default                                   | Description                                                                                |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `documentSelectionScreen` | *None*                                    | Configures the screen where users select the document type to capture. (Required)          |
| `layoutId`                | `null`                                    | Optional custom layout resource ID (`@LayoutRes`) used to override the default SDK layout. |
| `instructionsScreen`      | `CafDocumentDetectorInstructionsScreen()` | Configures the screen that displays instructions to the user before scanning begins.       |
| `uploadSettings`          | `UploadSettings(false)`                   | Settings for uploading the captured document images.                                       |
| `showPreview`             | `true`                                    | When true, displays a preview screen for the user to confirm the captured document.        |
| `requestTimeout`          | `60`                                      | Maximum time (in seconds) allowed for network requests to complete.                        |
| `showPopup`               | `true`                                    | When true, displays a guidance popup or overlay during the capture process.                |
| `maxRetryAttempts`        | `3`                                       | Maximum number of retries allowed after a failed capture attempt.                          |
| `customization`           | `DocumentDetectorCustomization()`         | Defines visual customization and branding settings for the detector UI.                    |

### Deep Dive Into Customizations

To learn more about styling and configuring the Document Detector interface, explore our dedicated customization guide:

{% content-ref url="/pages/ATD0VCE3u8KXWEwcRV92" %}
[UI Customizations](/caf-sdk/android/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. |

## Understanding Document Detector Events & Results

To handle the outcome of the Document Detector flow, pass a callback to the `CerttaDocumentDetector.instance.open()` method to listen for **success** or **error** events.

### `DocumentDetectorEvent.Success`

Triggered when the document is captured and processed successfully.

* `response: String`: A JWT containing the result data returned by the Document Detector flow. This data may include information relevant to the process, such as captured images or validation results.

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

### `DocumentDetectorEvent.Error`

Triggered when the capture process fails for any reason (e.g., network issues, user cancellation, camera permission denials, or configuration errors).

* `error: CerttaError`: An object containing detailed information about the failure, such as the specific error code and message. This allows you to identify the exact cause of the failure and handle it appropriately.

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