UI Customizations

Customize Document Detector for Android. Learn how to configure document selection, guidance screens, previews, uploads, retry states, and in-flow messages.

This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the legacy documentation.

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.

Installation Guide

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.

When using the document-detector-ui module, users see a list of allowed documents so they can choose which one to capture.

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.

DocumentDetector

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

DocumentDetectorUi

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

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.

The popup customization is only supported when using the document-detector module and is not available in document-detector-ui.

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

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.

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.

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

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.

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

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.

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

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.

Unlike the UI module, using document-detector with uploads enabled will hide the camera capture option.

The upload setting only applies to physical documents. For virtual documents, uploads are always enabled by default.

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.

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

Upload Customizations Parameters

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

Property	Description	Default (Localized)
image	Image displayed at the top of the popup.	Default SDK illustration
title	The title text displayed in the upload dialog.	The name of the selected document (e.g., ID Card - Front)
message	Message text within the upload popup.	"Select the file..."
uploadButton	Text for the "Upload" button.	"Upload"
cancelButton	Text for the "Cancel" button.	"Cancel"

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.

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

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

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

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.

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

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.

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.

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..."
    )
)

Launching a Customized Document Detector

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

DocumentDetector

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

DocumentDetectorUi

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