Envio de arquivos e gestão de QR - Capture

Introdução

A captura de documentos e a leitura e geração de QRs são realizadas com o CaptureComponent.

Este componente permitirá o envio de documentos tirando uma foto com a câmera do dispositivo ou da galeria.

---

Dependência

A dependência específica do componente é:

implementation "com.facephi.androidsdk:capture_component:$version"

---

Controladores disponíveis

Controlador	Descrição
FileUploaderController	Controlador para a captura de documentos
QrReaderController	Controlador para a captura de QRs
QrGeneratorController	Controlador para a geração de QRs

---

Lançamento simplificado

Uma vez iniciado o SDK e criada uma nova operação, será possível iniciar o componente. Será possível usar qualquer um de seus controladores para executar sua funcionalidade.

Lançamento da captura de documentos:

val response = SDKController.launch(
    FileUploaderController(FileUploaderConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

Lançamento da captura de QR:

val response = SDKController.launch(
    QrReaderController(QrCaptureConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

Lançamento da geração de QR:

val response = SDKController.launch(
    QrGeneratorController(QrGeneratorConfiguration(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

---

Configuração básica

Para os controladores de captura de componentes e captura de QR, a configuração pode ser gerada com os parâmetros padrão. No caso da geração do QR, será necessário o texto que será utilizado:

QrGeneratorConfiguration(source = "QR text")

---

Recebimento do resultado

A execução retornará as informações no formato SdkResult. Sendo possível diferenciar entre uma execução correta e uma incorreta:

when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}

Recebimento de erros

Os erros serão retornados como um objeto 'CaptureError'.

Lista de erros:

• CAP_ACTIVITY_RESULT_MSG_ERROR: O resultado retornado pela atividade é incorreto ou não contém as informações necessárias para continuar.

• CAP_APPLICATION_CONTEXT_ERROR: O contexto da aplicação necessário é nulo ou não válido, impedindo a inicialização correta do módulo de captura.

• CAP_CAMERA_ERROR: Ocorreu um erro interno relacionado à câmera do dispositivo (falha de abertura, inicialização ou captura).

• CAP_CAMERA_PERMISSION_DENIED: O usuário negou as permissões necessárias para acessar a câmera.

• CAP_CANCEL_BY_USER: O usuário cancelou manualmente o processo de captura.

• CAP_CANCEL_LAUNCH: O processo foi cancelado de forma geral pelo SDK ou por uma ação externa.

• CAP_COMPONENT_LICENSE_ERROR: A licença do componente não é válida, expirou ou não corresponde à configuração necessária.

• CAP_EMPTY_LICENSE: A string de licença está vazia ou não foi fornecida.

• CAP_FETCH_DATA_ERROR: Ocorreu um erro ao obter ou processar os dados necessários para executar o Fluxo. (Inclui informações adicionais no campo error.)

• CAP_FLOW_ERROR: Ocorreu um erro interno durante a execução do Fluxo de captura. (Inclui informações adicionais no campo error.)

• CAP_INITIALIZATION_ERROR: Erro ao inicializar os componentes necessários do SDK. (Inclui informações detalhadas no campo error.)

• CAP_FILE_UPLOADER_CAPTURE_ERROR: Erro durante o processo de envio dos arquivos gerados na captura.

• CAP_IMAGE_TOO_LARGE: A imagem selecionada na galeria excede o tamanho máximo configurado em maxGalleryImageSizeKb.

• CAP_MANAGER_NOT_INITIALIZED: Os managers necessários para executar o processo não foram inicializados corretamente.

• CAP_NO_DATA_ERROR: Os dados de entrada necessários são nulos, inexistentes ou insuficientes para continuar o processo.

• CAP_OPERATION_NOT_CREATED: Não foi possível criar ou recuperar uma operação ativa necessária para continuar. (Inclui informações detalhadas no campo error.)

• CAP_QR_CAPTURE_ERROR: Erro durante a captura ou leitura do código QR.

• CAP_QR_GENERATION_ERROR: Erro ao gerar o código QR solicitado.

• CAP_TIMEOUT: O tempo máximo permitido foi atingido em alguma das fases do processo.

• CAP_FLOW_VIDEO_RECORDING_ERROR: Erro durante a Gravação de Vídeo dentro do Fluxo estabelecido.

• CAP_FLOW_TRACKING_ERROR: Erro ao realizar o Tracking necessário para completar o Fluxo de captura.

Recepção do resultado correto - data

Recepção do resultado da captura de documentos

Na parte de SdkResult.Success - data, teremos a classe FileUploaderResult.

Os campos retornados no resultado são os seguintes:

capturedDocumentList

Lista de arquivos capturados. Podem ser imagens ou PDFs. Os campos retornados de cada um são:

• mimeType

• timestampMillis

• content: Conteúdo do documento. Será diferente se for uma imagem ou um documento PDF. Para diferenciá-lo:

capturedDocumentList.forEach { documentData ->
                            when (val content = documentData.content) {
                                is FileContent.UploaderImage -> {
                                    // Uploader: New image found
                                    // content.image
                                }

                                is FileContent.UploaderDocument -> {
                                    // Uploader: New document found
                                    // content.bytes
                                }
                            }
                        }

Recepção do resultado da captura de QR

Na parte de SdkResult.Success - data, teremos a classe QrResult.

Os campos retornados no resultado são os seguintes:

qrText

Texto obtido do QR

Recepção do resultado da geração de QR

Na parte de SdkResult.Success - data, teremos uma SdkImage com o QR criado.

---

Informações avançadas

Esta seção amplia as informações do componente.

Configuração avançada do componente

Configuração da captura de documentos

Para lançar o componente atual, deverá ser criado um objeto FileUploaderConfigurationData que será a configuração do controlador do componente.

A seguir, são detalhados todos os campos que fazem parte desta classe.

• vibrationEnabled: Indica a ativação da vibração quando o Widget terminar com sucesso.

• extractionTimeout: Define o tempo máximo durante o qual a captura pode ser realizada.

• showDiagnostic: Exibe telas de diagnóstico ao final do processo.

• showPreviousTip: Exibe uma tela antes do lançamento da captura com informações sobre o processo a ser realizado e um botão para iniciar.

• maxScannedDocs: Número máximo de documentos que poderão ser capturados

• allowGallery: O acesso à galeria é habilitado para a obtenção de imagens ou PDFs

• onlyGalleryMode: Se estiver ativo, o Fluxo é aberto diretamente no modo galeria e não mostra a captura com câmera. Por padrão true.

• maxGalleryImageSizeKb: Tamanho máximo permitido para imagens selecionadas da galeria, em KB. Por padrão 2048; se for excedido, é retornado CAP_IMAGE_TOO_LARGE.

Configuração da captura de QR

Para lançar o componente atual, deverá ser criado um objeto QrCaptureConfigurationData que será a configuração do controlador do componente.

A seguir, são detalhados todos os campos que fazem parte desta classe.

• vibrationEnabled: Indica a ativação da vibração quando o Widget terminar com sucesso.

• extractionTimeout: Define o tempo máximo durante o qual a captura pode ser realizada.

• showDiagnostic: Exibe telas de diagnóstico ao final do processo.

• showPreviousTip: Exibe uma tela antes do lançamento da captura com informações sobre o processo a ser realizado e um botão para iniciar.

• showTutorial: Indica se o componente ativa a tela de tutorial. Nessa visualização, é explicado de forma intuitiva como a captura é realizada.

• cameraShape: Permite escolher entre uma máscara quadrada e uma redonda.

---

Personalização do componente

Além das mudanças que podem ser realizadas no nível de SDK (as quais são explicadas no documento de (Personalização do SDK), este componente em específico permite a modificação de sua interface.

Textos

Se desejar modificar os textos do SDK, será necessário incluir o seguinte arquivo XML no aplicativo do cliente e modificar o valor de cada String pelo desejado.

<resources>
    <!-- Previous Tip -->
    <string name="capture_component_qr_tip_title">Escaneie o Código QR</string>
    <string name="capture_component_qr_tip_message">&lt;b&gt; Foque &lt;/b&gt; o Código QR &lt;b&gt; dentro do quadro &lt;/b&gt;</string>
    <string name="capture_component_qr_tip_button">Começar</string>
    <string name="capture_component_qr_tip_anim_desc">Animação de um celular tirando uma foto de um Código QR. Na tela do celular aparece um quadro. Quando o Código QR se encaixa dentro do quadro, o aplicativo tira uma foto.</string>
    <string name="capture_component_qr_tutorial_1_anim_desc">É exibido um Código QR sobre um fundo branco. As bordas do Código QR não se distinguem com clareza. Por meio de uma animação, o fundo muda de cor.</string>
    <string name="capture_component_qr_tutorial_2_anim_desc">Um celular tira uma foto de um Código QR. O Código QR aparece na horizontal, e o celular na posição vertical. Na tela do celular aparece um quadro. Quando o Código QR se encaixa dentro do quadro, o aplicativo tira uma foto.</string>
    <!-- Tutorial -->
    <string name="capture_component_qr_tutorial_1">Certifique-se de que o Código QR tenha &lt;b&gt; luz suficiente &lt;/b&gt; e &lt;b&gt; não haja reflexos &lt;/b&gt; ou brilhos sobre o Código QR.</string>
    <string name="capture_component_qr_tutorial_2">Encaixe as bordas do Código QR dentro do quadro.</string>
    <!-- Process -->
    <string name="capture_component_qr_camera_message">Mantenha o QR no centro</string>
    <string name="capture_component_button_message">Capturar</string>
    <!-- Diagnostic -->
    <string name="capture_component_timeout_title">Tempo esgotado</string>
    <string name="capture_component_timeout_desc">Pedimos desculpas. Não foi possível fazer a captura</string>
    <string name="capture_component_internal_error_title">Houve um problema técnico</string>
    <string name="capture_component_internal_error_desc">Pedimos desculpas. Não foi possível fazer a captura</string>

    <!-- WIDGET -->
    <!-- Previous Tip -->
    <string name="capture_widget_tip_title">Escanear documentos</string>
    <string name="capture_widget_tip_message">Tire uma foto do documento ou envie uma imagem.&lt;br&gt;&lt;br&gt; Você pode escanear vários documentos antes de finalizar.</string>
    <string name="capture_widget_tip_message_alt">Tire uma foto do documento ou envie uma imagem. Você pode escanear vários documentos antes de finalizar.</string>
    <string name="capture_widget_tip_button">Começar</string>
    <string name="capture_widget_tip_button_alt">Começar captura de documentos</string>
    <string name="capture_widget_tip_close_button_alt">Voltar</string>
    <string name="capture_widget_tip_info_button_alt">Ver dicas</string>
    <string name="capture_widget_tip_anim_desc">Animação de um celular tirando uma foto de um documento. Na tela do celular aparece um quadro. Quando o documento se encaixa dentro do quadro, o aplicativo tira uma foto.</string>
    <!-- Camera -->
    <string name="capture_widget_document_camera_button_gallery">Galeria</string>
    <string name="capture_widget_document_camera_button_capture">Capturar</string>
    <string name="capture_widget_document_camera_button_cancel">Cancelar captura</string>
    <string name="capture_widget_document_camera_button_finish">Finalizar</string>
    <!-- Gallery -->
    <string name="capture_widget_gallery_images">Imagens</string>
    <string name="capture_widget_gallery_pdf">Selecionar PDF</string>
    <string name="capture_widget_gallery_cancel">Cancelar</string>
    <!-- Confirmation -->
    <string name="capture_widget_image_captured">Imagem capturada</string>
    <string name="capture_widget_confirmation_message">Todos os dados são lidos de forma clara e nítida?</string>
    <string name="capture_widget_confirmation_retry">NÃO, QUERO REPETIR AS FOTOGRAFIAS</string>
    <string name="capture_widget_confirmation_continue">Sim, finalizar</string>
    <string name="capture_widget_confirmation_delete">Apagar foto</string>
    <string name="capture_widget_confirmation_image_unavailable">Pré-visualização indisponível</string>
    <string name="capture_widget_confirmation_no_images">Não há capturas disponíveis</string>
    <string name="capture_widget_confirmation_delete_dialog_title">Deseja excluir este documento?</string>
    <string name="capture_widget_confirmation_delete_dialog_message">Ao excluir este documento, você não poderá recuperá-lo. Será necessário tirar uma nova foto.</string>
    <string name="capture_widget_confirmation_delete_dialog_cancel">CANCELAR</string>
    <string name="capture_widget_confirmation_delete_dialog_confirm">EXCLUIR DOCUMENTO</string>
    <!-- Diagnostic -->
    <string name="capture_widget_timeout_title">Tempo esgotado</string>
    <string name="capture_widget_timeout_desc">Pedimos desculpas. Não foi possível fazer a captura</string>
    <string name="capture_widget_internal_error_title">Houve um problema técnico</string>
    <string name="capture_widget_internal_error_desc">Pedimos desculpas. Não foi possível fazer a captura</string>

</resources>

Animações

Se desejar modificar as animações (lottie) do SDK, será necessário incluir as animações com o mesmo nome na pasta res/raw/ da aplicação.

qr_anim_tip_1.json
qr_anim_tip_2.json
capture_anim_tip.json