Document Detector

Install and launch Document Detector for Android. Learn configuration options, UI setup, customization paths, callback events, and result handling.

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

Prerequisites

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

Installation Guide

Starting Document Detector

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

This method accepts a callback to handle the results and events triggered during the Document Detector flow.

The DocumentDetectorConfiguration and CerttaDocumentDetector classes are components of the io.caf.sdk:document-detector module.

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

Java

var config = new DocumentDetectorConfiguration(
    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
    }
});

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.

The DocumentDetectorUiConfiguration and CerttaDocumentDetectorUi classes are components of the io.caf.sdk:document-detector-ui module.

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

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

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:

UI Customizations

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.

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.

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.