> 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/captura-de-huellas.md).

# Captura de Impressão Digital - Phingers

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

A captura de impressão digital é realizada por meio do **Componente Phingers**.

Este componente é responsável por capturar as impressões digitais do usuário (*impressões digitais*) e extrair os templates biométricos associados. Seus principais processos são:

* Gerenciamento interno da câmera e das permissões.
* Diferentes modos de extração: mão completa (quatro dedos sem o polegar), polegar ou dedos individuais.
* Detecção de vivacidade integrada.
* Assistência guiada durante o processo de captura.
* Geração de templates biométricos, imagens e métricas de qualidade.

Na seção [Lançamento simplificado](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) são descritos os passos necessários para a integração básica do SDK. Nesta página é adicionada a informação específica para o uso deste componente.

***

## Dependência <a href="#id-2-dependencia" id="id-2-dependencia"></a>

A dependência específica do componente é:

```kotlin
implementation "com.facephi.androidsdk:phingers_tf_component:$version"
```

***

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

| **Controlador**       | **Descrição**                                                                    |
| --------------------- | -------------------------------------------------------------------------------- |
| PhingersTFController  | Controlador principal de captura de impressões digitais                          |
| FPhingersTFController | Controlador principal de captura de impressões digitais para integrações de flow |

## 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, o componente de captura de impressões digitais pode ser acionado usando seu controlador.

Inicialização da captura:

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

***

## Configuração básica

Para lançar o componente, é necessário criar um objeto `PhingersConfigurationData`, que define a configuração do processo de captura.

A configuração básica necessária é a seguinte:

```kotlin
PhingersConfigurationData(
    reticleOrientation = CaptureOrientation.LEFT,
    fingerFilter       = FingerFilter.SLAP,
    templateType       = TemplateType.NIST_TEMPLATE
)
```

**Orientação da captura**

Define a mão a ser capturada:

* `CaptureOrientation.LEFT`
* `CaptureOrientation.RIGHT`

**Filtros de dedos**

Permite definir quais dedos são capturados durante o processo:

* `FingerFilter.SLAP`
* `FingerFilter.ALL_4_FINGERS_ONE_BY_ONE`
* `FingerFilter.ALL_5_FINGERS_ONE_BY_ONE`
* `FingerFilter.INDEX_FINGER`
* `FingerFilter.MIDDLE_FINGER`
* `FingerFilter.RING_FINGER`
* `FingerFilter.LITTLE_FINGER`
* `FingerFilter.THUMB_FINGER`

**Opções de TemplateType**:

* `NIST_TEMPLATE`
* `ISO_TEMPLATE`
* `NIST_T5_TEMPLATE`

***

## Recebimento do resultado <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

O lançamento do componente retorna um resultado no formato `SdkResult`, que pode corresponder a uma execução bem-sucedida ou a um erro.

```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 são retornados como um objeto `PhingersError`.

**Lista de erros**

* PHG\_ACTIVITY\_RESULT\_ERROR: O resultado da atividade está incorreto.
* PHG\_ACTIVITY\_RESULT\_MSG\_ERROR: A mensagem do resultado da atividade está incorreta.
* PHG\_APPLICATION\_CONTEXT\_ERROR: O contexto da aplicação é nulo.
* PHG\_CANCEL\_BY\_USER: O usuário cancelou o processo.
* PHG\_CANCEL\_LAUNCH: Cancelamento geral do SDK.
* PHG\_COMPONENT\_LICENSE\_ERROR: A licença do componente não está correta.
* PHG\_EMPTY\_LICENSE: A string de licença está vazia.
* PHG\_FETCH\_DATA\_ERROR: Erro na coleta do resultado.
* FLOW\_ERROR: Erro no processo de flow.
* PHG\_INITIALIZATION\_ERROR: Erro de inicialização.
* PHG\_INTERNAL\_ERROR: Erro interno.
* PHG\_LOW\_QUALITY: Baixa qualidade da imagem.
* PHG\_MANAGER\_NOT\_INITIALIZED: Os managers são nulos ou não estão inicializados.
* PHG\_NO\_DATA\_ERROR: Nenhum dado da captura foi recebido.
* PHG\_OPERATION\_NOT\_CREATED: Não há nenhuma operação em andamento.
* PHG\_PERMISSION\_DENIED: O usuário recusou as permissões.
* PHG\_AUTOFOCUS\_FAILURE: Falha no autofocus.
* PHG\_CAMERA\_FAILURE: Falha na câmera.
* PHG\_CAPTURE\_FAILURE: Falha na captura.
* PHG\_CONFIGURATION\_FAILURE: Erro de configuração.
* PHG\_FINGERPRINT\_CAPTURE\_FAILURE: Falha na captura de impressões digitais.
* PHG\_FINGERPRINT\_TEMPLATE\_IO\_ERROR: Falha de IO do template.
* PHG\_LICENSING\_FAILURE: Erro de licença.
* PHG\_LIVENESS\_FAILURE: Erro no teste de vida.
* PHG\_NO\_FINGERS\_DETECTED: Nenhuma impressão digital foi detectada.
* PHG\_UNIQUE\_USER\_ID\_NOT\_SPECIFIED: Usuário não especificado.
* PHG\_TIMEOUT: Timeout no processo.
* PHG\_FLOW\_VIDEO\_RECORDING\_ERROR: Erro na gravação de vídeo do flow.
* PHG\_FLOW\_TRACKING\_ERROR: Erro de tracking no flow.
* PHG\_TRACKING\_STEP\_ERROR: Erro na etapa de tracking.

***

## Recepção do resultado correto - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

Em caso de sucesso, o campo `data` contém um objeto `PhingersResult`.

As imagens são retornadas como `SdkImage`. É possível obter o `Bitmap` por meio de `image.bitmap`. Para converter uma imagem em Base64, pode-se utilizar:

```
Base64.encodeToString(byteArray, Base64.NO_WRAP)
```

**Campos retornados**

* **fingers**: Lista de `FingerResponse` (uma entrada por dedo capturado)
* **slapImages**: Lista de `SlapResponse` (capturas slap quando aplicável)
* **livenessScore**: Média da pontuação de vivacidade (nullable)
* **recording**: Metadados da gravação local opcional quando `videoRecordingEnabled=true` e o widget gera um arquivo MP4. Pode ser `null`.

**FingerResponse**

* **position**: Índice de posição do dedo
* **wsq**: Imagem WSQ (`ByteArray`)
* **displayImage**: Imagem de exibição (`ByteArray`, PNG)
* **minutiaesNumber**: Número de minutiae detectadas
* **quality**: Pontuação de qualidade
* **nistQuality**: Pontuação de qualidade NIST
* **nist2Quality**: Pontuação de qualidade NIST2
* **template**: Template de impressão digital (`ByteArray`)
* **proprietaryQuality**: Qualidade proprietária do fornecedor
* **templateType**: Identificador do tipo de template
* **imageWidth**: Largura da imagem em pixels
* **imageHeight**: Altura da imagem em pixels

**SlapResponse**

* **position**: Índice da posição do slap
* **image**: Imagem slap (`ByteArray`)

**VideoRecordingResult**

* **path**: Caminho completo do arquivo de vídeo gerado.
* **fileName**: Nome do arquivo de vídeo.
* **mimeType**: Tipo MIME do arquivo. Por padrão `video/mp4`.
* **sizeBytes**: Tamanho do arquivo em bytes, quando o widget informa.
* **durationMs**: Duração do vídeo em milissegundos, quando o widget informa.

***

## Informações avançadas <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

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

O objeto `PhingersConfigurationData` permite personalizar o comportamento do componente.

**Parâmetros disponíveis**

**reticleOrientation**

Define o modo de detecção de impressões digitais e indica quais dedos serão detectados durante o processo. Os valores permitidos são:

* **LEFT**: A captura é ativada **da mão esquerda**.
* **RIGHT**: A captura é ativada **da mão direita**.

**fingerFilter**

Filtro para escolher a mão inteira ou um dedo específico: SLAP, INDEX\_FINGER, MIDDLE\_FINGER, RING\_FINGER, LITTLE\_FINGER, THUMB\_FINGER.

**templateType**

Define o formato do template a ser gerado (variantes NIST/ISO).

**useLiveness**

Ativa ou desativa o detector de vivacidade durante o processo de captura de impressões digitais. Por padrão ele está em **true**.

**extractionTimeout**

Define um tempo de extração.

**showPreviousTip**

Mostra uma tela anterior ao lançamento da captura com informações sobre o processo a ser realizado e um botão para o lançamento.

**showTutorial**

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

**showDiagnostic**

Exibir telas de diagnóstico ao final do processo.

**threshold**

O parâmetro configura um captureQualityThreshold, para definir um threshold de qualidade para realizar a captura. O SDK limita esse valor ao intervalo `0.0-1.0`.

**showEllipses**

Mostra as elipses durante a captura.

**cropWidth**

Indica uma largura para realizar um recorte da captura.

**cropHeight**

Indica uma altura para realizar um recorte da captura.

**vibrationEnabled**

Ativa a vibração. Por padrão `true`.

**enableFlash**

Ativa ou desativa o flash da câmera durante o processo de captura de impressões digitais. Por padrão ele está em **true**.

**reticle**

Identificador opcional do retículo. Por padrão `"R_S"`.

**showPreviousFingerSelector**

Mostra o seletor de dedos antes da captura.

**fingerSelectorHandOrientation**

Define qual(is) mão(s) são exibidas no seletor (`LEFT`, `RIGHT`, `BOTH`).

**fingerSelectorOptions**

Define a lista de filtros que são exibidos no seletor. Se estiver vazia, o SDK usa: `ALL_4_FINGERS_ONE_BY_ONE`, `SLAP`, `INDEX_FINGER`.

**licenseKey**

Chave de licença opcional que é passada ao widget Phingers TF quando são usadas ativação ou licenciamento específico.

**product**

Produto opcional associado à ativação ou ao licenciamento do widget.

**operationId**

Identificador opcional de operação que é enviado ao widget para rastreabilidade e associação da captura.

**videoRecordingEnabled**

Ativa a gravação local opcional durante a captura de impressões digitais. Por padrão `false`.

**videoRecordingDirectoryPath**

Diretório de destino opcional para o arquivo de vídeo gerado.

**videoRecordingFileName**

Nome de arquivo opcional para a gravação gerada.

**videoRecordingQuality**

Qualidade da gravação local. Os valores permitidos são `LOW`, `MEDIUM` e `HIGH`. Por padrão `MEDIUM`.

***

## Personalização do componente <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Além das alterações que podem ser feitas no nível do 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>

Os textos podem ser personalizados adicionando um arquivo XML de recursos na aplicação cliente e sobrescrevendo os valores padrão.

```kotlin
<!-- Dica anterior -->
    <string name="phingers_widget_tip_title">Captura de Impressão Digital</string>
    <string name="phingers_widget_tip_message">Coloque seu dedo dentro da marca</string>
    <string name="phingers_widget_tip_message_alt">Coloque seu dedo dentro da marca</string>
    <string name="phingers_widget_tip_button">Começar</string>
    <string name="phingers_widget_tip_button_alt">Começar captura de impressão digital</string>
    <string name="phingers_widget_tip_close_button_alt">Voltar</string>
    <string name="phingers_widget_tip_info_button_alt">Ver dicas</string>
    <string name="phingers_widget_tip_anim_desc">Animação de instruções para a captura de impressão digital</string>
    <!-- Dica anterior (tipos específicos) -->
    <string name="phingers_widget_tip_title_left_slap">Impressões digitais da mão esquerda</string>
    <string name="phingers_widget_tip_message_left_slap">Junte os dedos. Aproxime ou afaste a mão até que suas impressões digitais fiquem em foco.</string>
    <string name="phingers_widget_tip_title_right_slap">Impressões digitais da mão direita</string>
    <string name="phingers_widget_tip_message_right_slap">Junte os dedos. Aproxime ou afaste a mão até que suas impressões digitais fiquem em foco.</string>
    <string name="phingers_widget_tip_title_left_finger">Impressões digitais da mão esquerda</string>
    <string name="phingers_widget_tip_message_left_finger">Foque o dedo indicador no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <string name="phingers_widget_tip_title_right_finger">Impressões digitais da mão direita</string>
    <string name="phingers_widget_tip_message_right_finger">Foque o dedo indicador no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <string name="phingers_widget_tip_title_thumb">Impressão digital do polegar</string>
    <string name="phingers_widget_tip_message_thumb">Foque o dedo polegar no quadro. Aproxime ou afaste o dedo até que sua impressão digital fique em foco.</string>
    <!-- Seletor de dedos -->
    <string name="phingers_widget_selector_hand_question">Qual mão você usará?</string>
    <string name="phingers_widget_selector_hand_left">Esquerda</string>
    <string name="phingers_widget_selector_hand_right">Direita</string>
    <string name="phingers_widget_selector_secondary_question">Quais impressões digitais você quer escanear?</string>
    <string name="phingers_widget_selector_option_index">Dedo indicador</string>
    <string name="phingers_widget_selector_option_middle">Dedo médio</string>
    <string name="phingers_widget_selector_option_ring">Dedo anelar</string>
    <string name="phingers_widget_selector_option_little">Dedo mindinho</string>
    <string name="phingers_widget_selector_option_thumb">Dedo polegar</string>
    <string name="phingers_widget_selector_option_all4">4 dedos (indicador, médio, anelar e mindinho)</string>
    <string name="phingers_widget_selector_option_all4_sequence">4 dedos (um a um)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 dedos (um a um)</string>
    <string name="phingers_widget_selector_primary_button">Continuar</string>
    <!-- Captura -->
    <string name="phingers_widget_capture_close_button_alt">Voltar</string>
    <!-- Tutorial -->
    <string name="phingers_widget_tutorial_message_1">Posicione seu rosto no centro e olhe diretamente para a câmera.</string>
    <string name="phingers_widget_tutorial_message_2">Remova qualquer item que cubra seu rosto.</string>
    <string name="phingers_widget_tutorial_message_3">Procure um ambiente bem iluminado, sem sombras sobre o rosto.</string>
    <string name="phingers_widget_tutorial_message_1_anim_desc">A foto é tirada quando a pessoa está no centro.</string>
    <string name="phingers_widget_tutorial_message_2_anim_desc">Uma pessoa tira os óculos escuros e afasta o cabelo dos olhos.</string>
    <string name="phingers_widget_tutorial_message_3_anim_desc">A imagem aparece escura e uma pessoa acende a luz.</string>
    <string name="phingers_widget_tutorial_close_button_alt">Voltar ao tutorial anterior</string>
    <!-- Confirmação -->
    <string name="phingers_widget_image_captured">Imagem capturada</string>
    <string name="phingers_widget_confirmation_message">Sua foto parece clara e nítida?</string>
    <string name="phingers_widget_confirmation_retry">Tentar novamente</string>
    <string name="phingers_widget_confirmation_continue">Continuar</string>

    <!-- Status da câmera (ES) -->
    <string name="phingers_widget_camera_status_position_fingers">Coloque seus dedos dentro da marca</string>
    <string name="phingers_widget_camera_status_processing">Processando…</string>
    <string name="phingers_widget_camera_status_too_far">Aproxime a mão</string>
    <string name="phingers_widget_camera_status_too_close">Afaste a mão</string>
    <string name="phingers_widget_camera_status_low_focus">Mova o dedo para focar</string>
    <string name="phingers_widget_camera_status_good_focus">Mantenha o dedo parado</string>
    <string name="phingers_widget_camera_status_wrong_angle">Posicione o dedo na vertical</string>
    <string name="phingers_widget_camera_status_too_few">O dedo não foi detectado</string>
    <string name="phingers_widget_camera_status_too_many">Vários dedos detectados</string>
    <string name="phingers_widget_camera_status_wrong_hand_left">Você deve colocar o dedo da mão esquerda</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">Você deve colocar o dedo da mão direita</string>
    <string name="phingers_widget_camera_status_error">Erro na captura</string>
    <string name="phingers_widget_camera_status_timeout">Tempo de captura esgotado</string>
    <string name="phingers_widget_camera_status_success">Impressão digital capturada!</string>
    <string name="phingers_widget_camera_status_keep_hand_steady">Mantenha a mão firme</string>
    <string name="phingers_widget_timeout_desc">A captura excedeu o tempo limite. Tente novamente.</string>

    <!-- Dica dinâmica do dedo (ES) -->
    <!-- %1$s = lado (esquerdo/direito), %2$s = dedo (indicador/médio/anelar/mindinho/polegar) -->
    <string name="phingers_widget_hint_place_finger_mark">Coloque seu %2$s %1$s dentro da marca</string>
    <string name="phingers_widget_side_left">esquerdo</string>
    <string name="phingers_widget_side_right">direito</string>
    <string name="phingers_widget_finger_index">indicador</string>
    <string name="phingers_widget_finger_middle">médio</string>
    <string name="phingers_widget_finger_ring">anelar</string>
    <string name="phingers_widget_finger_little">mindinho</string>
    <string name="phingers_widget_finger_thumb">polegar</string>
```

### Animações <a href="#id-82-animaciones" id="id-82-animaciones"></a>

As animações do componente são **Lottie (JSON)**.

Para substituí-las, adicione os arquivos com o mesmo nome na pasta `res/raw/` da aplicação:

```
phingers_anim_left.json
phingers_anim_left_finger.json
phingers_anim_right.json
phingers_anim_right_finger.json
phingers_anim_success.json
phingers_anim_thumb.json
phingers_anim_thumb_left.json
phingers_anim_thumb_right.json
phingers_anim_thumbs.json
```

Se não forem incluídas animações personalizadas, as animações padrão serão usadas.

***