Personalizações de UI

Personalize o Detector de Documentos para Android. Saiba como configurar a seleção de documentos, telas de orientação, prévias, uploads, estados de tentativa novamente e mensagens no fluxo.

Este guia abrange a versão 7.14.0 e superior. Para versões anteriores à 7.14.0, consulte a documentação legada.

Visão geral

Detector de Documentos oferece opções para personalizar sua interface, incluindo cores, layout e texto. A personalização é opcional porque valores padrão são fornecidos. Modifique apenas os elementos que você deseja alterar.

Há duas configurações de personalização, dependendo do módulo que você adicionar ao seu projeto: document-detector ou document-detector-ui. Para instruções detalhadas sobre como configurar o módulo, consulte o guia de instalação.

Guia de Instalação

Selecionando documentos para captura

Configure os documentos específicos que os usuários têm permissão para processar. Documentos físicos podem ser capturados pela câmera ou enviados (se habilitado), enquanto documentos virtuais devem sempre ser enviados.

Ao usar o document-detector-ui módulo, os usuários veem uma lista de documentos permitidos para que possam escolher qual capturar.

Para configurar os documentos permitidos, atualize o o fluxo parâmetro em DocumentDetectorConfiguration. Se você estiver usando o document-detector-ui módulo, defina a documentSelectionScreen propriedade diretamente na sua DocumentDetectorUiConfiguration.

DocumentDetector

val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(Document.RG_FRONT), 
        DocumentDetectorStep(Document.RG_BACK)
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}

DocumentDetectorUi

val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront(), CafDocument.RGBack()),
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) {  }

Personalização do popup de orientação

Um popup de orientação é exibido ao usuário antes que a câmera ou a galeria de arquivos seja aberta. Para personalizar esse popup, defina um texto específico para cada tipo de documento usando o DocumentDetectorStep objeto.

A personalização do popup só é compatível ao usar o document-detector módulo e não está disponível em document-detector-ui.

val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "Frente do cartão de identidade",
            "https://picsum.photos/400",
            "Coloque o documento sobre uma mesa",
            "Ok"
        )
    ),
    showPopup = true,
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}

Se showPopup is true, os detalhes da personalização são exibidos em um popup de orientação. Se os envios estiverem habilitados ou showPopup is false, esse popup é ignorado e os detalhes são aplicados ao popup de envio em vez disso.

Personalização da tela de seleção de documentos

Ao usar o document-detector-ui módulo, você pode personalizar a Tela de Seleção de Documentos modificando o título e a descrição principais, तसे como os títulos e descrições individuais de cada documento na lista.

val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(
            CafDocument.RGFront(
                stepLabel = "Frente do cartão de identidade",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Coloque o documento sobre uma mesa",
                stepOkButton = "Confirmar"
            ),
        ),
        title = "Escolha um documento",
        description = "Selecione o documento que deseja usar",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "Cartão de identidade",
                description = "Carteira de identidade"
            ),
        )
    ),
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) { }

Personalização da tela de instruções

O document-detector-ui módulo apresenta uma tela de instruções que aparece logo antes de a câmera ou a galeria de arquivos ser aberta. Tanto o texto quanto as imagens dessa tela são totalmente personalizáveis.

Você pode personalizar as telas de captura e envio individualmente passando uma instância de CafDocumentDetectorInstructionsScreen para a propriedade instructionsScreen .

val config = DocumentDetectorUiConfiguration(
     documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
          documents = listOf(CafDocument.RGFront()),
     ),
     instructionsScreen = CafDocumentDetectorInstructionsScreen(
          captureImage = "https://yourdomain.com/images/capture-guide.png",
          captureTitle = "Prepare-se para digitalizar",
          captureSteps = listOf("Encontre uma boa iluminação", "Posicione o documento dentro do enquadramento", "Evite reflexos"),

          uploadImage = "https://yourdomain.com/images/upload-guide.png",
          uploadTitle = "Envie seu documento",
          uploadSteps = listOf("Certifique-se de que o arquivo esteja nítido", "Deve ser JPG ou PNG", "Tamanho máximo de 5 MB"),

          buttonText = "Estou pronto"
     ),
    // ... outros parâmetros
)
CerttaDocumentDetectorUi.instance.open(config) {  }

Parâmetros da tela de instruções

Todas as propriedades na CafDocumentDetectorInstructionsScreen classe são opcionais. Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição
captureImage	A URL ou caminho do recurso da imagem exibida na tela de instruções de captura pela câmera.
captureTitle	O texto do título principal exibido antes de o usuário abrir a câmera.
captureSteps	Uma lista de etapas ou dicas de instrução para orientar o usuário sobre como tirar uma boa foto.
uploadImage	A URL ou caminho do recurso da imagem exibida na tela de instruções de envio de arquivo.
uploadTitle	O texto do título principal exibido antes de o usuário selecionar um arquivo para enviar.
uploadSteps	Uma lista de etapas ou dicas de instrução para orientar o usuário na escolha de um arquivo válido.
buttonText	O texto exibido no botão que o usuário toca para prosseguir para a câmera ou para a galeria de arquivos.

Pré-visualização da foto

Permite que os usuários visualizem a imagem durante a captura do documento, possibilitando confirmar ou refazer a foto conforme necessário.

Para exibir a pré-visualização, defina showPreview = true em qualquer um dos DocumentDetectorConfiguration ou DocumentDetectorUiConfiguration.

Personalização da tela de pré-visualização

Para personalizar a tela de pré-visualização, inclua previewCustomization no customização parâmetros.

val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    previewCustomization = CafPreviewCustomization(
        title = "Confirmar qualidade da foto",
        message = "Certifique-se de que todos os detalhes estejam claros e não haja reflexos.",
        okButton = "Confirmar",
        tryAgainButton = "Capturar novamente"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    showPreview = true,
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) {}

Parâmetros das personalizações da pré-visualização

Todas as propriedades na CafPreviewCustomization classe são opcionais. Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição	Padrão (localizado)
título	Texto do título na tela de pré-visualização.	"A foto está boa?"
message	Texto do subtítulo/mensagem na tela de pré-visualização.	"Verifique se todas as informações estão legíveis..."
okButton	Texto para o botão de confirmação ("aceitar").	"Sim, está boa!"
tryAgainButton	Texto para o botão de tentar novamente ("tirar de novo").	"Tirar novamente"

Envio de documento

Permite que os usuários enviem um arquivo de imagem diretamente do dispositivo. Ao usar o document-detector-ui módulo, os usuários podem tirar uma nova foto ou enviar uma imagem existente.

Ao contrário do módulo de UI, usar document-detector com os envios habilitados ocultará a opção de captura pela câmera.

A configuração de envio se aplica apenas a documentos físicos. Para documentos virtuais, os envios estão sempre habilitados por padrão.

Para habilitar a opção de envio, passe true para as configurações de upload em qualquer um dos DocumentDetectorConfiguration ou DocumentDetectorUiConfiguration.

Personalização da tela de envio

Para personalizar o texto e a aparência da interface de envio, passe o objeto uploadCustomization em seu customização parâmetro.

val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    uploadCustomization = CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Escolha um arquivo para enviar",
        message = "Escolha o arquivo de documento que deseja enviar.",
        uploadButton = "Enviar arquivo",
        cancelButton = "Cancelar",
    ),
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }

Parâmetros das personalizações de envio

Todas as propriedades na CafDDUploadCustomization classe são opcionais. Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição	Padrão (localizado)
imagem	Imagem exibida no topo do popup.	Ilustração padrão do SDK
título	O texto do título exibido na caixa de diálogo de envio.	O nome do documento selecionado (por exemplo, RG - Frente)
message	Texto da mensagem dentro do popup de envio.	"Selecione o arquivo..."
uploadButton	Texto para o botão "Enviar".	"Enviar"
cancelButton	Texto para o botão "Cancelar".	"Cancelar"

Tentativas de repetição

Configure o número máximo de tentativas de repetição que um usuário tem antes de o processo ser interrompido e uma mensagem de erro ser exibida.

Para configurar o número de tentativas de repetição, defina maxRetryAttempts em qualquer um dos DocumentDetectorConfiguration ou DocumentDetectorUiConfiguration. O valor padrão é 3; defini-lo como -1 permite tentativas ilimitadas.

Personalização da tela de tentativas de repetição

Para personalizar o texto e a aparência da interface de repetição, passe o retryCustomization em seu customização parâmetro.

val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    retryCustomization = CafDDRetryCustomization(
        title = "Ocorreu um erro",
        description = "Verifique sua conexão com a internet e tente novamente",
        textButton = "Tentar novamente"
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }

Parâmetros de tentativas de repetição

Todas as propriedades na CafDDRetryCustomization classe são opcionais. Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição	Padrão (localizado)
título	Texto do título na tela de repetição.	"Foto não enviada"
descrição	Texto do subtítulo ou da mensagem na tela de repetição.	"Verifique sua conexão com a internet e tente novamente"
textButton	Texto para o botão de repetição.	"Tentar novamente"

Personalização de mensagens de feedback

Você pode personalizar as mensagens exibidas no fluxo durante o processo de captura do documento (por exemplo, mensagens do sensor, feedback da IA).

val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Por favor, aguarde...",
        fitTheDocumentMessage = "Alinhe seu documento dentro do enquadramento.",
        // outras mensagens
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }

Parâmetros de personalização de mensagens

Todas as propriedades na CafMessageCustomization classe são opcionais (String?). Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição
waitMessage	Mensagem exibida ao iniciar a câmera.
fitTheDocumentMessage	Mensagem que solicita ao usuário que ajuste o documento dentro do enquadramento.
holdItMessage	Mensagem exibida durante o processo de captura.
verifyingQualityMessage	Mensagem exibida durante a solicitação de verificação de qualidade.
lowQualityDocumentMessage	Mensagem exibida quando a captura do documento falha devido à baixa qualidade.
uploadingImageMessage	Mensagem exibida ao salvar a imagem capturada no servidor.
openDocumentWrongMessage	Mensagem exibida se um documento aberto for detectado.
unsupportedDocumentMessage	Mensagem para documentos não suportados.
documentNotFoundMessage	Mensagem exibida quando nenhum documento é detectado.
sensorLuminosityMessage	Mensagem exibida quando o nível de brilho está muito baixo.
sensorOrientationMessage	Mensagem exibida quando o limite de orientação não é atendido.
sensorStabilityMessage	Mensagem exibida quando o dispositivo não está estável o suficiente.
popupDocumentSubtitleMessage	Mensagem de subtítulo exibida no popup que apresenta a ilustração do documento.
positiveButtonMessage	Mensagem exibida no botão de confirmação.
aiScanDocumentMessage	Mensagem que solicita ao usuário que digitalize um documento.
aiGetCloserMessage	Mensagem que solicita ao usuário que se aproxime do documento.
aiCentralizeMessage	Mensagem que solicita ao usuário que centralize o documento na tela.
aiMoveAwayMessage	Mensagem que solicita ao usuário que se afaste do documento.
aiAlignMessage	Mensagem que solicita ao usuário que alinhe o documento.
aiTurnDocumentMessage	Mensagem que solicita ao usuário que gire o documento em 90 graus.
aiCapturedMessage	Mensagem que confirma que o documento foi capturado.
wrongDocumentMessage	Mensagem exibida quando o tipo de documento está incorreto.

Personalização de mensagens de envio

Personalize as mensagens exibidas ao usuário enquanto a imagem está sendo enviada ao servidor.

val customization = DocumentDetectorCustomization(
    // ... outras personalizações
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Enviando seu documento...",
        documentVerifyingIntegrity = "Verificando a qualidade da imagem...",
        documentProcessingData = "Extraindo dados...",
        documentAlmostDone = "Finalizando..."
    )
)
val config = DocumentDetectorConfiguration(
    flow = listOf(DocumentDetectorStep(Document.RG_FRONT)),
    uploadSettings = UploadSettings(true),
    customization = customization
    // ... outros parâmetros
)
CerttaDocumentDetector.instance.open(config) { }

Parâmetros das mensagens de envio

Todas as propriedades na CafDDUploadMessageCustomization classe são opcionais (String?). Se deixadas como null, o SDK usará os valores padrão.

Propriedade	Descrição
documentSending	O texto exibido quando o envio do documento começa e ele está sendo transmitido ao servidor.
documentVerifyingIntegrity	O texto mostrado enquanto o sistema verifica a qualidade e a validade do documento enviado.
documentProcessingData	O texto exibido enquanto o backend está analisando ativamente o documento e extraindo seus dados.
documentAlmostDone	O texto mostrado nas etapas finais do processo de envio e verificação, informando ao usuário que está finalizando.

Exemplo completo de personalização

DocumentDetectorCustomization

Veja o exemplo abaixo para uma DocumentDetectorCustomization implementação completa com todas as personalizações disponíveis configuradas.

Todos os campos desta configuração são opcionais e têm valores padrão predefinidos. Você só precisa fornecer valores para os campos específicos que deseja personalizar.

private val customization = DocumentDetectorCustomization(
    previewCustomization = CafDDCustomization.CafPreviewCustomization(
        title = "Confirmar qualidade da foto",
        message = "Certifique-se de que todos os detalhes estejam claros e não haja reflexos.",
        okButton = "Confirmar",
        tryAgainButton = "Capturar novamente"
    ),
    uploadCustomization = CafDDCustomization.CafDDUploadCustomization(
        image = "https://picsum.photos/400",
        title = "Escolha um arquivo para enviar",
        message = "Escolha o arquivo de documento que deseja enviar.",
        uploadButton = "Enviar arquivo",
        cancelButton = "Cancelar",
    ),
    retryCustomization = CafDDCustomization.CafDDRetryCustomization(
        title = "Ocorreu um erro",
        description = "Verifique sua conexão com a internet e tente novamente",
        textButton = "Tentar novamente"
    ),
    messageCustomization = CafDDCustomization.CafMessageCustomization(
        waitMessage = "Por favor, aguarde...",
        fitTheDocumentMessage = "Alinhe seu documento dentro do enquadramento.",
    ),
    uploadMessageCustomization = CafDDCustomization.CafDDUploadMessageCustomization(
        documentSending = "Enviando seu documento...",
        documentVerifyingIntegrity = "Verificando a qualidade da imagem...",
        documentProcessingData = "Extraindo dados...",
        documentAlmostDone = "Finalizando..."
    )
)

Lançando um Detector de Documentos personalizado

O exemplo a seguir demonstra como inicializar e lançar o DocumentDetector com todas as personalizações disponíveis aplicadas.

DocumentDetector

val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(
            Document.RG_FRONT,
            "Frente do cartão de identidade",
            "https://picsum.photos/400",
            "Coloque o documento sobre uma mesa",
            "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 = "Frente do cartão de identidade",
                stepIllustration = "https://picsum.photos/400",
                stepMessage = "Coloque o documento sobre uma mesa",
                stepOkButton = "Confirmar"
            ),
        ),
        title = "Escolha um documento",
        description = "Selecione o documento que deseja usar",
        groupLabels = CafDocumentGroupLabels(
            rg = CafDocumentLabel(
                title = "Cartão de identidade",
                description = "Carteira de identidade"
            ),
        )
    ),
    instructionsScreen = CafDocumentDetectorInstructionsScreen(
        captureImage = "https://yourdomain.com/images/capture-guide.png",
        captureTitle = "Prepare-se para digitalizar",
        captureSteps = listOf("Encontre uma boa iluminação", "Posicione o documento dentro do enquadramento", "Evite reflexos"),

        uploadImage = "https://yourdomain.com/images/upload-guide.png",
        uploadTitle = "Envie seu documento",
        uploadSteps = listOf("Certifique-se de que o arquivo esteja nítido", "Deve ser JPG ou PNG", "Tamanho máximo de 5 MB"),

        buttonText = "Estou pronto"
    ),
    showPopup = true,
    customization = customization
)
CerttaDocumentDetectorUi.instance.open(config) { }