> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/componentes-modulos/subida-de-ficheros-y-gestion-de-qr.md).

# Envio de arquivos e gestão de QR - Capture

## Introdução <a href="#id-1-introduccion" id="id-1-introduccion"></a>

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 href="#id-2-dependencia" id="id-2-dependencia"></a>

A dependência específica do componente é:

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

***

## Controladores disponíveis <a href="#id-3-controladores-disponibles" id="id-3-controladores-disponibles"></a>

| **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 <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

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:

```kotlin
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:

```kotlin
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:

```kotlin
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 <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

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 href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

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

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

### Recebimento de erros <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

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* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

#### **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:

```kotlin
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 <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

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

### Configuração avançada do componente <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

#### **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 <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

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](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente em específico permite a modificação de sua interface.

### Textos <a href="#id-81-textos" id="id-81-textos"></a>

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 <a href="#id-82-animaciones" id="id-82-animaciones"></a>

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
```