Document Detector

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

This guide covers caf_sdk 2.4.0 and above (Certta DevX). For the previous CafSdk sequential flow, 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

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.

CerttaDocumentDetectorConfiguration and CerttaDocumentDetector are the headless Document Detector module. The flow list is required.

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.

Enable documentDetectorUI in caf-modules-config.json. The native layer maps flow into the document selection screen.

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

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.

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

Full HEIC support is available on iOS only.

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.

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.

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.