> 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/ui-customizations.md).

# UI Customizations

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

## Overview

**Document Detector** provides options to customize its interface, including colors, layout, and text. Customization is optional because default values are provided. Only modify the elements you want to change.

There are two customization setups, depending on the module you add to your project: `document-detector` or `document-detector-ui`. For detailed instructions on configuring the module, consult the installation guide.

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

## Selecting Documents to Capture

Configure the specific documents that users are allowed to process. Physical documents can be captured via the camera or uploaded (if enabled), while virtual documents must always be uploaded.

{% hint style="info" %}
When using the `document-detector-ui` module, users see a list of allowed documents so they can choose which one to capture.
{% endhint %}

To configure the allowed documents, update the `flow` parameter in `DocumentDetectorConfiguration`. If you are using the `document-detector-ui` module, set the `documentSelectionScreen` property directly on your `DocumentDetectorUiConfiguration`.

{% tabs fullWidth="false" %}
{% tab title="DocumentDetector" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(Document.RG_FRONT), 
        DocumentDetectorStep(Document.RG_BACK)
    ),
    showPopup = true,
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endtab %}

{% tab title="DocumentDetectorUi" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront(), CafDocument.RGBack()),
    ),
    showPopup = true,
    // ... other parameters
)
CerttaDocumentDetectorUi.instance.open(config) {  }
```

{% endtab %}
{% endtabs %}

### Guidance Popup Customization

A guidance popup is displayed to the user before the camera or file gallery opens. To customize this popup, define specific text for each document type using the `DocumentDetectorStep` object.

{% hint style="warning" %}
The popup customization is only supported when using the `document-detector` module and is not available in `document-detector-ui`.
{% endhint %}

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "ID Card Front",
            "https://picsum.photos/400",
            "Place the document on a table",
            "Ok"
        )
    ),
    showPopup = true,
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endcode %}

{% hint style="info" %}
If `showPopup` is `true`, the customization details are shown in a guidance popup. If uploads are enabled or `showPopup` is `false`, this popup is skipped, and the details are applied to the upload popup instead.
{% endhint %}

### Document Selection Screen Customization

When using the `document-detector-ui` module, you can customize the Document Selection Screen by modifying the main title and description, as well as the individual titles and descriptions for each document in the list.

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(
            CafDocument.RGFront(
                stepLabel = "ID Card Front",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Place the document on a table",
                stepOkButton = "Confirm"
            ),
        ),
        title = "Choose a document",
        description = "Select the document you want to use",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "ID card",
                description = "Identity Card"
            ),
        )
    ),
    // ... other parameters
)
CerttaDocumentDetectorUi.instance.open(config) { }
```

{% endcode %}

## Instructions Screen Customization

The `document-detector-ui` module features an instructions screen that appears just before the camera or file gallery opens. Both the text and images on this screen are fully customizable.

You can customize the capture and upload screens individually by passing an instance of `CafDocumentDetectorInstructionsScreen` to the `instructionsScreen` property.

{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
     documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
          documents = listOf(CafDocument.RGFront()),
     ),
     instructionsScreen = CafDocumentDetectorInstructionsScreen(
          captureImage = "https://yourdomain.com/images/capture-guide.png",
          captureTitle = "Get Ready to Scan",
          captureSteps = listOf("Find good lighting", "Place document within the frame", "Avoid glare"),

          uploadImage = "https://yourdomain.com/images/upload-guide.png",
          uploadTitle = "Upload Your Document",
          uploadSteps = listOf("Ensure the file is clear", "Must be JPG or PNG", "Max size 5MB"),

          buttonText = "I'm Ready"
     ),
    // ... other parameters
)
CerttaDocumentDetectorUi.instance.open(config) {  }
```

{% endcode %}

### Instructions Screen Parameters

All properties in the `CafDocumentDetectorInstructionsScreen` class are optional. If left as `null`, the SDK will use the default values.

| Property       | Description                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------- |
| `captureImage` | The URL or resource path for the image displayed on the camera capture instruction screen.    |
| `captureTitle` | The main heading text shown before the user opens the camera.                                 |
| `captureSteps` | A list of instructional steps or tips to guide the user on how to take a good photo.          |
| `uploadImage`  | The URL or resource path for the image displayed on the file upload instruction screen.       |
| `uploadTitle`  | The main heading text shown before the user selects a file to upload.                         |
| `uploadSteps`  | A list of instructional steps or tips to guide the user on choosing a valid file.             |
| `buttonText`   | The text displayed on the button that the user taps to proceed to the camera or file gallery. |

## Photo Preview

Allow users to preview the image during document capture, enabling them to confirm or retake the photo as needed.

To display the preview, set `showPreview = true` in either `DocumentDetectorConfiguration` or `DocumentDetectorUiConfiguration`.

### Preview Screen Customization

To customize the preview screen, include `previewCustomization` in the `customization` parameters.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... other customizations
    previewCustomization = CafPreviewCustomization(
        title = "Confirm Photo Quality",
        message = "Ensure all details are clear and there are no reflections.",
        okButton = "Confirm",
        tryAgainButton = "Recapture"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    showPreview = true,
    customization = customization
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endcode %}

### Preview Customizations Parameters

All properties in the `CafPreviewCustomization` class are optional. If left as `null`, the SDK will use the default values.

| Property         | Description                                  | Default (Localized)               |
| ---------------- | -------------------------------------------- | --------------------------------- |
| `title`          | Title text on the preview screen.            | "Is the photo good?"              |
| `message`        | Subtitle/message text on the preview screen. | "Check if all info is legible..." |
| `okButton`       | Text for the confirmation ("accept") button. | "Yes, it's good!"                 |
| `tryAgainButton` | Text for the retry ("take again") button.    | "Take again"                      |

## Document Upload

Enable users to upload an image file directly from their device. When using the `document-detector-ui` module, users can either take a new picture or upload an existing image.

{% hint style="info" %}
Unlike the UI module, using `document-detector` with uploads enabled will hide the camera capture option.
{% endhint %}

{% hint style="warning" %}
The upload setting only applies to physical documents. For virtual documents, uploads are always enabled by default.
{% endhint %}

To enable the upload option, pass `true` to `uploadSettings` in either `DocumentDetectorConfiguration` or `DocumentDetectorUiConfiguration`.

### Upload Screen Customization

To customize the text and appearance of the upload interface, pass the `uploadCustomization` object in your `customization` parameter.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... other customizations
    uploadCustomization = CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Choose a file to upload",
        message = "Please choose the document file you want to upload.",
        uploadButton = "Upload file",
        cancelButton = "Cancel",
    ),
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Upload Customizations Parameters

All properties in the `CafDDUploadCustomization` class are optional. If left as `null`, the SDK will use the default values.

<table><thead><tr><th width="187">Property</th><th>Description</th><th>Default (Localized)</th></tr></thead><tbody><tr><td><code>image</code></td><td>Image displayed at the top of the popup.</td><td>Default SDK illustration</td></tr><tr><td><code>title</code></td><td>The title text displayed in the upload dialog.</td><td>The name of the selected document (e.g., ID Card - Front)</td></tr><tr><td><code>message</code></td><td>Message text within the upload popup.</td><td>"Select the file..."</td></tr><tr><td><code>uploadButton</code></td><td>Text for the "Upload" button.</td><td>"Upload"</td></tr><tr><td><code>cancelButton</code></td><td>Text for the "Cancel" button.</td><td>"Cancel"</td></tr></tbody></table>

## Retry Attempts

Configure the maximum number of retry attempts a user has before the process is interrupted and an error message is displayed.

To configure the number of retry attempts, set `maxRetryAttempts` in either `DocumentDetectorConfiguration` or `DocumentDetectorUiConfiguration`. The default value is 3; setting it to -1 allows unlimited retries.

### Retry Attempts Screen Customization

To customize the text and appearance of the retry interface, pass the `retryCustomization` object in your `customization` parameter.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... other customizations
    retryCustomization = CafDDRetryCustomization(
        title = "An error happened",
        description = "Check your internet connection and try again",
        textButton = "Try Again"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    customization = customization
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Retry Attempts Parameters

All properties in the `CafDDRetryCustomization` class are optional. If left as `null`, the SDK will use the default values.

| Property      | Description                                   | Default (Localized)                            |
| ------------- | --------------------------------------------- | ---------------------------------------------- |
| `title`       | Title text on the retry screen.               | "Photo not sent"                               |
| `description` | Subtitle or message text on the retry screen. | "Check your internet connection and try again" |
| `textButton`  | Text for the retry button.                    | "Try Again"                                    |

## Feedback Messages Customization

You can customize the in-flow messages displayed during the document capture process (e.g., sensor messages, AI feedback).

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... other customizations
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Please wait...",
        fitTheDocumentMessage = "Align your document within the frame.",
        // other messages
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

### Message Customization Parameters

All properties in the `CafMessageCustomization` class are optional (`String?`). If left as `null`, the SDK will use the default values.

| Property                       | Description                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `waitMessage`                  | Message displayed when starting the camera.                                   |
| `fitTheDocumentMessage`        | Message prompting the user to fit the document within the frame.              |
| `holdItMessage`                | Message displayed during the capture process.                                 |
| `verifyingQualityMessage`      | Message displayed during the quality verification request.                    |
| `lowQualityDocumentMessage`    | Message displayed when document capture fails due to low quality.             |
| `uploadingImageMessage`        | Message displayed when saving the captured image to the server.               |
| `openDocumentWrongMessage`     | Message displayed if an open document is detected.                            |
| `unsupportedDocumentMessage`   | Message for unsupported documents.                                            |
| `documentNotFoundMessage`      | Message displayed when no document is detected.                               |
| `sensorLuminosityMessage`      | Message displayed when the brightness level is too low.                       |
| `sensorOrientationMessage`     | Message displayed when the orientation threshold is not met.                  |
| `sensorStabilityMessage`       | Message displayed when the device is not stable enough.                       |
| `popupDocumentSubtitleMessage` | Subtitle message displayed in the popup presenting the document illustration. |
| `positiveButtonMessage`        | Message displayed on the confirmation button.                                 |
| `aiScanDocumentMessage`        | Message prompting the user to scan a document.                                |
| `aiGetCloserMessage`           | Message prompting the user to get closer to the document.                     |
| `aiCentralizeMessage`          | Message prompting the user to center the document on the screen.              |
| `aiMoveAwayMessage`            | Message prompting the user to move away from the document.                    |
| `aiAlignMessage`               | Message prompting the user to align the document.                             |
| `aiTurnDocumentMessage`        | Message prompting the user to rotate the document 90 degrees.                 |
| `aiCapturedMessage`            | Message confirming that the document has been captured.                       |
| `wrongDocumentMessage`         | Message displayed when the document type is incorrect.                        |

## Upload Message Customization

Customize the messages displayed to the user while the image is being uploaded to the server.

{% code expandable="true" %}

```kotlin
val customization = DocumentDetectorCustomization(
    // ... other customizations
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Sending your document...",
        documentVerifyingIntegrity = "Checking image quality...",
        documentProcessingData = "Extracting data...",
        documentAlmostDone = "Wrapping things up..."
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... other parameters
)
CerttaDocumentDetector.instance.open(config) { }
```

{% endcode %}

#### Upload Message Parameters

All properties in the `CafDDUploadMessageCustomization` class are optional (`String?`). If left as `null`, the SDK will use the default values.

| Property                     | Description                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `documentSending`            | The text displayed when the document upload first begins and is being transmitted to the server.                    |
| `documentVerifyingIntegrity` | The text shown while the system is checking the uploaded document's quality and validity.                           |
| `documentProcessingData`     | The text displayed while the backend is actively analyzing the document and extracting its data.                    |
| `documentAlmostDone`         | The text shown in the final stages of the upload and verification process, letting the user know it is wrapping up. |

## Full customization example

### `DocumentDetectorCustomization`

See the example below for a complete `DocumentDetectorCustomization` implementation with all available customizations configured.

{% hint style="info" %}
All fields in this configuration are optional and have predefined default values. You only need to provide values for the specific fields you wish to customize.
{% endhint %}

{% code expandable="true" %}

```kotlin
private val customization = DocumentDetectorCustomization(
    previewCustomization = CafDDCustomization.CafPreviewCustomization(
        title = "Confirm Photo Quality",
        message = "Ensure all details are clear and there are no reflections.",
        okButton = "Confirm",
        tryAgainButton = "Recapture"
    ),
    uploadCustomization = CafDDCustomization.CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Choose a file to upload",
        message = "Please choose the document file you want to upload.",
        uploadButton = "Upload file",
        cancelButton = "Cancel",
    ),
    retryCustomization = CafDDCustomization.CafDDRetryCustomization(
        title = "An error happened",
        description = "Check your internet connection and try again",
        textButton = "Try Again"
    ),
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Please wait...",
        fitTheDocumentMessage = "Align your document within the frame.",
    ),
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Sending your document...",
        documentVerifyingIntegrity = "Checking image quality...",
        documentProcessingData = "Extracting data...",
        documentAlmostDone = "Wrapping things up..."
    )
)
```

{% endcode %}

### Launching a Customized Document Detector

The following example demonstrates how to initialize and launch the `DocumentDetector` with all available customizations applied.

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

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "ID Card Front",
            "https://picsum.photos/400",
            "Place the document on a table",
            "Ok"
        )
    ),
    customization = customization,
    showPopup = true,
    showPreview = true,
    uploadSettings = UploadSettings(true),
    requestTimeout = 60,
    maxRetryAttempts = 3,
)
CerttaDocumentDetector.instance.open(config) {}
```

{% endtab %}

{% tab title="DocumentDetectorUi" %}
{% code expandable="true" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(
            CafDocument.RGFront(
                stepLabel = "ID Card Front",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Place the document on a table",
                stepOkButton = "Confirm"
            ),
        ),
        title = "Choose a document",
        description = "Select the document you want to use",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "ID card",
                description = "Identity Card"
            ),
        )
    ),
    instructionsScreen = CafDocumentDetectorInstructionsScreen(
        captureImage = "https://yourdomain.com/images/capture-guide.png",
        captureTitle = "Get Ready to Scan",
        captureSteps = listOf("Find good lighting", "Place document within the frame", "Avoid glare"),

        uploadImage = "https://yourdomain.com/images/upload-guide.png",
        uploadTitle = "Upload Your Document",
        uploadSteps = listOf("Ensure the file is clear", "Must be JPG or PNG", "Max size 5MB"),

        buttonText = "I'm Ready"
    ),
    showPopup = true,
    customization = customization
)
CerttaDocumentDetectorUi.instance.open(config) { }
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# 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/ui-customizations.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.