UI Customizations

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

This guide covers caf_sdk 2.4.0 and above (Certta DevX). For the previous CafSdk sequential flow, see the legacy documentation.

Overview

Document Detector can customize interface copy, illustrations, and in-flow messages. Customization is optional; only set the fields you want to change.

There are two setups, depending on the module you enable in caf-modules-config.json: documentDetector or documentDetectorUI.

Installation Guide

Selecting documents to capture

Configure the documents users are allowed to process with flow. Physical documents can be captured via the camera or uploaded (if enabled). Virtual documents must be uploaded.

With the UI module, users see a list of allowed documents derived from flow.

// Headless
final config = CerttaDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  showPopup: true,
);

// UI module — documents still come from flow
final uiConfig = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  showPopup: true,
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Choose a document',
    description: 'Select the document you want to use',
  ),
);

Guidance popup customization

A guidance popup is shown before the camera or file gallery opens. Customize it per step on CafDocumentDetectorFlow.

Popup customization applies to the headless documentDetector module. It is not available in documentDetectorUI.

final config = CerttaDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'ID Card Front',
      illustration: 'https://picsum.photos/400',
      message: 'Place the document on a table',
      okButtonTitle: 'Ok',
    ),
  ],
  showPopup: true,
);

If showPopup is true, these details appear in a guidance popup. If uploads are enabled or showPopup is false, the popup is skipped and the details apply to the upload popup instead.

Document selection screen

With the UI module, customize the picker title and description. The document list itself is built from flow.

final config = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'ID Card Front',
      illustration: 'https://picsum.photos/400',
      message: 'Place the document on a table',
      okButtonTitle: 'Confirm',
    ),
  ],
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Choose a document',
    description: 'Select the document you want to use',
  ),
);

Instructions screen customization

The UI module can show an instructions screen before the camera or file gallery. Customize capture and upload copy independently.

final config = CerttaDocumentDetectorUiConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  instructionScreen: const CafDocumentDetectorUIInstructionScreenConfiguration(
    enable: true,
    captureImage: 'https://yourdomain.com/images/capture-guide.png',
    captureTitle: 'Get Ready to Scan',
    captureSteps: [
      'Find good lighting',
      'Place document within the frame',
      'Avoid glare',
    ],
    uploadImage: 'https://yourdomain.com/images/upload-guide.png',
    uploadTitle: 'Upload Your Document',
    uploadSteps: [
      'Ensure the file is clear',
      'Must be JPG or PNG',
      'Max size 5MB',
    ],
    buttonText: "I'm Ready",
  ),
);

All properties are optional. If omitted, the SDK uses defaults.

Property	Description
enable	Shows or hides the instruction screen. Default true.
captureImage	URL or local asset for the camera instruction screen.
captureTitle	Heading shown before the camera opens.
captureSteps	Tips for taking a good photo.
uploadImage	URL or local asset for the upload instruction screen.
uploadTitle	Heading shown before the user picks a file.
uploadSteps	Tips for choosing a valid file.
buttonText	Label on the button that continues to camera or gallery.

Photo preview

Set showPreview: true to let users confirm or retake the photo.

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  showPreview: true,
  previewCustomization: const CafDocumentDetectorPreviewCustomization(
    title: 'Confirm Photo Quality',
    message: 'Ensure all details are clear and there are no reflections.',
    okButton: 'Confirm',
    tryAgainButton: 'Recapture',
  ),
);

Property	Description
title	Title text on the preview screen.
message	Subtitle on the preview screen.
okButton	Confirmation button label.
tryAgainButton	Retry button label.

Document upload

Enable upload with CafDocumentDetectorUploadSettings.

Unlike the UI module, using headless documentDetector with uploads enabled hides the camera capture option.

Upload settings apply to physical documents. Virtual documents always allow upload.

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  uploadSettings: const CafDocumentDetectorUploadSettings(
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.png, CafFileFormat.jpg],
    maxFileSize: 5,
  ),
  uploadCustomization: const CafDocumentDetectorUploadCustomization(
    image: 'https://picsum.photos/400',
    message: 'Please choose the document file you want to upload.',
    uploadButton: 'Upload file',
    cancelButton: 'Cancel',
  ),
);

Property	Description
image	Image at the top of the upload popup.
message	Message inside the upload popup.
uploadButton	Upload button label.
cancelButton	Cancel button label.

Retry attempts

maxRetryAttempts defaults to 3. Use -1 for unlimited retries.

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  maxRetryAttempts: 3,
  retryCustomization: const CafDocumentDetectorRetryCustomization(
    title: 'An error happened',
    description: 'Check your internet connection and try again',
    textButton: 'Try Again',
  ),
);

Property	Description
title	Title on the retry screen.
description	Subtitle on the retry screen.
textButton	Retry button label.

Feedback messages

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  messageCustomization: const CafDocumentDetectorMessageCustomization(
    waitMessage: 'Please wait...',
    fitTheDocumentMessage: 'Align your document within the frame.',
    holdItMessage: 'Hold steady...',
    verifyingQualityMessage: 'Verifying document quality...',
    lowQualityDocumentMessage: 'Document quality is too low. Please try again.',
    uploadingImageMessage: 'Uploading document...',
    positiveButtonMessage: 'Continue',
  ),
);

Property	Description
waitMessage	Shown when starting the camera.
fitTheDocumentMessage	Prompt to fit the document in the frame.
holdItMessage	Shown during capture.
verifyingQualityMessage	Shown during quality verification.
lowQualityDocumentMessage	Shown when quality is too low.
uploadingImageMessage	Shown while saving the image.
openDocumentWrongMessage	Shown if an open document is detected.
unsupportedDocumentMessage	Shown for unsupported documents.
documentNotFoundMessage	Shown when no document is detected.
sensorLuminosityMessage	Shown when brightness is too low.
sensorOrientationMessage	Shown when orientation is incorrect.
sensorStabilityMessage	Shown when the device is not stable.
popupDocumentSubtitleMessage	Subtitle in the document illustration popup.
positiveButtonMessage	Confirmation button label.
wrongDocumentMessage	Shown when the document type is incorrect.
predictorScanDocumentMessage	Prompt to scan a document.
predictorGetCloserMessage	Prompt to get closer.
predictorCentralizeMessage	Prompt to center the document.
predictorMoveAwayMessage	Prompt to move away.
predictorAlignDocumentMessage	Prompt to align the document.
predictorTurnDocumentMessage	Prompt to rotate the document.
predictorCapturedMessage	Confirmation that the document was captured.

Upload progress messages

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
  uploadMessagesCustomization:
      const CafDocumentDetectorUploadMessagesCustomization(
    sending: 'Sending your document...',
    verifyingIntegrity: 'Checking image quality...',
    processingData: 'Extracting data...',
    almostDone: 'Wrapping things up...',
  ),
);

Property	Description
sending	Shown when upload starts.
verifyingIntegrity	Shown while checking quality and validity.
processingData	Shown while the backend extracts data.
almostDone	Shown in the final stage of verification.

Full customization example

All customization fields are optional.

final certta = CerttaSdk();

await certta.documentDetector.open(
  CerttaDocumentDetectorConfiguration(
    flow: [
      CafDocumentDetectorFlow(
        document: CafDocument.rgFront,
        stepLabel: 'ID Card Front',
        illustration: 'https://picsum.photos/400',
        message: 'Place the document on a table',
        okButtonTitle: 'Ok',
      ),
    ],
    showPopup: true,
    showPreview: true,
    maxRetryAttempts: 3,
    requestTimeout: 60,
    uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
    previewCustomization: const CafDocumentDetectorPreviewCustomization(
      title: 'Confirm Photo Quality',
      message: 'Ensure all details are clear and there are no reflections.',
      okButton: 'Confirm',
      tryAgainButton: 'Recapture',
    ),
    uploadCustomization: const CafDocumentDetectorUploadCustomization(
      image: 'https://picsum.photos/400',
      message: 'Please choose the document file you want to upload.',
      uploadButton: 'Upload file',
      cancelButton: 'Cancel',
    ),
    retryCustomization: const CafDocumentDetectorRetryCustomization(
      title: 'An error happened',
      description: 'Check your internet connection and try again',
      textButton: 'Try Again',
    ),
    messageCustomization: const CafDocumentDetectorMessageCustomization(
      waitMessage: 'Please wait...',
      fitTheDocumentMessage: 'Align your document within the frame.',
    ),
    uploadMessagesCustomization:
        const CafDocumentDetectorUploadMessagesCustomization(
      sending: 'Sending your document...',
      verifyingIntegrity: 'Checking image quality...',
      processingData: 'Extracting data...',
      almostDone: 'Wrapping things up...',
    ),
  ),
);