Personalizações da UI

Personalize o Document Detector para Flutter. Aprenda como configurar a seleção de documento, telas de orientação, pré-visualizações, uploads, estados de tentativa novamente e mensagens no fluxo.

Este guia aborda caf_sdk 2.4.0 e superiores (Certta DevX). Para a versão anterior CafSdk fluxo sequencial, consulte a documentação legada.

Visão geral

O Document Detector pode personalizar os textos da interface, ilustrações e mensagens no fluxo. A personalização é opcional; defina apenas os campos que você quer alterar.

Existem duas configurações, dependendo do módulo que você habilitar em caf-modules-config.json: documentDetector ou documentDetectorUI.

Guia de Instalação

Selecionando documentos para capturar

Configure os documentos que os usuários podem processar com flow. Documentos físicos podem ser capturados pela câmera ou enviados (se habilitado). Documentos virtuais devem ser enviados.

Com o módulo UI, os usuários veem uma lista de documentos permitidos derivada de flow.

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

// Módulo UI — os documentos ainda vêm de flow
final uiConfig = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  showPopup: true,
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Escolha um documento',
    description: 'Selecione o documento que você quer usar',
  ),
);

Personalização do pop-up de orientação

Um pop-up de orientação é exibido antes de abrir a câmera ou a galeria de arquivos. Personalize-o por etapa em CafDocumentDetectorFlow.

A personalização do pop-up se aplica ao módulo sem interface documentDetector module. Não está disponível em documentDetectorUI.

final config = CerttaDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'Frente do RG',
      illustration: 'https://picsum.photos/400',
      message: 'Coloque o documento sobre uma mesa',
      okButtonTitle: 'Ok',
    ),
  ],
  showPopup: true,
);

Se showPopup é true, esses detalhes aparecem em um pop-up de orientação. Se os envios estiverem ativados ou showPopup é false, o pop-up é ignorado e os detalhes se aplicam ao pop-up de envio em vez disso.

Tela de seleção de documento

Com o módulo UI, personalize o título e a descrição do seletor. A lista de documentos em si é construída a partir de flow.

final config = CerttaDocumentDetectorUiConfiguration(
  flow: [
    CafDocumentDetectorFlow(
      document: CafDocument.rgFront,
      stepLabel: 'Frente do RG',
      illustration: 'https://picsum.photos/400',
      message: 'Coloque o documento sobre uma mesa',
      okButtonTitle: 'Confirmar',
    ),
  ],
  documentSelectionScreen:
      const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: 'Escolha um documento',
    description: 'Selecione o documento que você quer usar',
  ),
);

Personalização da tela de instruções

O módulo UI pode exibir uma tela de instruções antes da câmera ou da galeria de arquivos. Personalize separadamente os textos de captura e envio.

final config = CerttaDocumentDetectorUiConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  instructionScreen: const CafDocumentDetectorUIInstructionScreenConfiguration(
    enable: true,
    captureImage: 'https://yourdomain.com/images/capture-guide.png',
    captureTitle: 'Prepare-se para digitalizar',
    captureSteps: [
      'Encontre uma boa iluminação',
      'Posicione o documento dentro da moldura',
      'Evite reflexos',
    ],
    uploadImage: 'https://yourdomain.com/images/upload-guide.png',
    uploadTitle: 'Envie seu documento',
    uploadSteps: [
      'Certifique-se de que o arquivo esteja nítido',
      'Deve ser JPG ou PNG',
      'Tamanho máximo de 5 MB',
    ],
    buttonText: "Estou pronto",
  ),
);

Todos os campos são opcionais. Se omitidos, o SDK usa os padrões.

Propriedade	Descrição
enable	Mostra ou oculta a tela de instruções. Padrão true.
captureImage	URL ou recurso local para a tela de instruções da câmera.
captureTitle	Título exibido antes de a câmera abrir.
captureSteps	Dicas para tirar uma boa foto.
uploadImage	URL ou recurso local para a tela de instruções de envio.
uploadTitle	Título exibido antes de o usuário escolher um arquivo.
uploadSteps	Dicas para escolher um arquivo válido.
buttonText	Rótulo do botão que continua para a câmera ou a galeria.

Pré-visualização da foto

Defina showPreview: true para permitir que os usuários confirmem ou tirem a foto novamente.

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  showPreview: true,
  previewCustomization: const CafDocumentDetectorPreviewCustomization(
    title: 'Confirme a qualidade da foto',
    message: 'Certifique-se de que todos os detalhes estejam nítidos e não haja reflexos.',
    okButton: 'Confirmar',
    tryAgainButton: 'Capturar novamente',
  ),
);

Propriedade	Descrição
title	Texto do título na tela de pré-visualização.
message	Subtítulo na tela de pré-visualização.
okButton	Rótulo do botão de confirmação.
tryAgainButton	Rótulo do botão de tentar novamente.

Envio de documento

Ative o envio com CafDocumentDetectorUploadSettings.

Ao contrário do módulo UI, usar o módulo sem interface documentDetector com envios ativados oculta a opção de captura pela câmera.

As configurações de envio se aplicam a documentos físicos. Documentos virtuais sempre permitem envio.

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: 'Escolha o arquivo do documento que você quer enviar.',
    uploadButton: 'Enviar arquivo',
    cancelButton: 'Cancelar',
  ),
);

Propriedade	Descrição
image	Imagem no topo do pop-up de envio.
message	Mensagem dentro do pop-up de envio.
uploadButton	Rótulo do botão de envio.
cancelButton	Rótulo do botão de cancelamento.

Tentativas de repetição

maxRetryAttempts padrão para 3. Use -1 para tentativas ilimitadas.

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  maxRetryAttempts: 3,
  retryCustomization: const CafDocumentDetectorRetryCustomization(
    title: 'Ocorreu um erro',
    description: 'Verifique sua conexão com a internet e tente novamente',
    textButton: 'Tentar novamente',
  ),
);

Propriedade	Descrição
title	Título na tela de nova tentativa.
description	Subtítulo na tela de nova tentativa.
textButton	Rótulo do botão de tentar novamente.

Mensagens de feedback

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  messageCustomization: const CafDocumentDetectorMessageCustomization(
    waitMessage: 'Aguarde...',
    fitTheDocumentMessage: 'Alinhe seu documento dentro da moldura.',
    holdItMessage: 'Mantenha firme...',
    verifyingQualityMessage: 'Verificando a qualidade do documento...',
    lowQualityDocumentMessage: 'A qualidade do documento está muito baixa. Tente novamente.',
    uploadingImageMessage: 'Enviando documento...',
    positiveButtonMessage: 'Continuar',
  ),
);

Propriedade	Descrição
waitMessage	Exibida ao iniciar a câmera.
fitTheDocumentMessage	Solicitação para encaixar o documento na moldura.
holdItMessage	Exibida durante a captura.
verifyingQualityMessage	Exibida durante a verificação de qualidade.
lowQualityDocumentMessage	Exibida quando a qualidade é muito baixa.
uploadingImageMessage	Exibida enquanto a imagem é salva.
openDocumentWrongMessage	Exibida se um documento aberto for detectado.
unsupportedDocumentMessage	Exibida para documentos não suportados.
documentNotFoundMessage	Exibida quando nenhum documento é detectado.
sensorLuminosityMessage	Exibida quando a luminosidade está muito baixa.
sensorOrientationMessage	Exibida quando a orientação está incorreta.
sensorStabilityMessage	Exibida quando o dispositivo não está estável.
popupDocumentSubtitleMessage	Subtítulo no pop-up de ilustração do documento.
positiveButtonMessage	Rótulo do botão de confirmação.
wrongDocumentMessage	Exibida quando o tipo de documento está incorreto.
predictorScanDocumentMessage	Solicitação para escanear um documento.
predictorGetCloserMessage	Solicitação para chegar mais perto.
predictorCentralizeMessage	Solicitação para centralizar o documento.
predictorMoveAwayMessage	Solicitação para se afastar.
predictorAlignDocumentMessage	Solicitação para alinhar o documento.
predictorTurnDocumentMessage	Solicitação para girar o documento.
predictorCapturedMessage	Confirmação de que o documento foi capturado.

Mensagens de progresso do envio

final config = CerttaDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
  uploadMessagesCustomization:
      const CafDocumentDetectorUploadMessagesCustomization(
    sending: 'Enviando seu documento...',
    verifyingIntegrity: 'Verificando a qualidade da imagem...',
    processingData: 'Extraindo dados...',
    almostDone: 'Finalizando...',
  ),
);

Propriedade	Descrição
sending	Exibida quando o envio começa.
verifyingIntegrity	Exibida enquanto a qualidade e a validade são verificadas.
processingData	Exibida enquanto o backend extrai os dados.
almostDone	Exibida na etapa final da verificação.

Exemplo completo de personalização

Todos os campos de personalização são opcionais.

final certta = CerttaSdk();

await certta.documentDetector.open(
  CerttaDocumentDetectorConfiguration(
    flow: [
      CafDocumentDetectorFlow(
        document: CafDocument.rgFront,
        stepLabel: 'Frente do RG',
        illustration: 'https://picsum.photos/400',
        message: 'Coloque o documento sobre uma mesa',
        okButtonTitle: 'Ok',
      ),
    ],
    showPopup: true,
    showPreview: true,
    maxRetryAttempts: 3,
    requestTimeout: 60,
    uploadSettings: const CafDocumentDetectorUploadSettings(enable: true),
    previewCustomization: const CafDocumentDetectorPreviewCustomization(
      title: 'Confirme a qualidade da foto',
      message: 'Certifique-se de que todos os detalhes estejam nítidos e não haja reflexos.',
      okButton: 'Confirmar',
      tryAgainButton: 'Capturar novamente',
    ),
    uploadCustomization: const CafDocumentDetectorUploadCustomization(
      image: 'https://picsum.photos/400',
      message: 'Escolha o arquivo do documento que você quer enviar.',
      uploadButton: 'Enviar arquivo',
      cancelButton: 'Cancelar',
    ),
    retryCustomization: const CafDocumentDetectorRetryCustomization(
      title: 'Ocorreu um erro',
      description: 'Verifique sua conexão com a internet e tente novamente',
      textButton: 'Tentar novamente',
    ),
    messageCustomization: const CafDocumentDetectorMessageCustomization(
      waitMessage: 'Aguarde...',
      fitTheDocumentMessage: 'Alinhe seu documento dentro da moldura.',
    ),
    uploadMessagesCustomization:
        const CafDocumentDetectorUploadMessagesCustomization(
      sending: 'Enviando seu documento...',
      verifyingIntegrity: 'Verificando a qualidade da imagem...',
      processingData: 'Extraindo dados...',
      almostDone: 'Finalizando...',
    ),
  ),
);