> 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ões digitais é realizada por meio do **Phingers Component**.

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

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

Na seção [Lançamento simplificado](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) são descritas as etapas necessárias para a integração básica do SDK. Nesta página, são adicionadas as informações específicas 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>

Depois que o SDK é iniciado e uma nova operação é criada, é possível iniciar o componente de captura de impressões digitais usando seu controlador.

Lançamento 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 iniciar 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 = ReticleOrientation.LEFT,
    fingerFilter       = FingerFilter.SLAP,
    templateType       = TemplateType.NIST_TEMPLATE
)
```

**Orientação da captura**

Define a mão a ser capturada (`reticleOrientation`, do tipo `ReticleOrientation`):

* `ReticleOrientation.LEFT`
* `ReticleOrientation.RIGHT`

**Filtros de dedos**

Permite definir quais dedos serã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`
* `NONE`

***

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

A inicialização 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**

* `ACTIVITY_RESULT_ERROR` (`PHG_817`): O resultado da atividade está incorreto.
* `ACTIVITY_RESULT_MSG_ERROR` (`PHG_813`): A mensagem do resultado da atividade está incorreta.
* `APPLICATION_CONTEXT_ERROR` (`PHG_814`): O contexto do aplicativo é nulo.
* `CANCEL_BY_USER` (`PHG_000`): O usuário cancelou o processo.
* `CANCEL_LAUNCH` (`PHG_007`): Cancelamento geral do SDK.
* `COMPONENT_LICENSE_ERROR` (`PHG_002`): A licença do componente está incorreta.
* `EMPTY_LICENSE` (`PHG_003`): A string da licença está vazia.
* `FETCH_DATA_ERROR` (`PHG_815`): Erro ao coletar o resultado.
* `FLOW_ERROR` (`PHG_823`): Erro no processo do flow.
* `INITIALIZATION_ERROR` (`PHG_004`): Erro de inicialização.
* `INTERNAL_ERROR` (`PHG_800`): Erro interno.
* `LOW_QUALITY` (`PHG_801`): Baixa qualidade da imagem.
* `MANAGER_NOT_INITIALIZED` (`PHG_816`): Os managers são nulos ou não estão inicializados.
* `NO_DATA_ERROR` (`PHG_005`): Nenhum dado foi recebido da captura.
* `OPERATION_NOT_CREATED` (`PHG_006`): Não há nenhuma operação em andamento.
* `PERMISSION_DENIED` (`PHG_802`): O usuário recusou as permissões.
* `PHINGERS_AUTOFOCUS_FAILURE` (`PHG_803` ): Falha no foco automático.
* `PHINGERS_CAMERA_FAILURE` (`PHG_804` ): Falha na câmera.
* `PHINGERS_CAPTURE_FAILURE` (`PHG_805` ): Falha na captura.
* `PHINGERS_CONFIGURATION_FAILURE` (`PHG_806` ): Erro de configuração.
* `PHINGERS_FINGERPRINT_CAPTURE_FAILURE` (`PHG_807` ): Falha na Captura de Impressão Digital.
* `PHINGERS_FINGERPRINT_TEMPLATE_IO_ERROR` (`PHG_808` ): Falha de E/S do modelo.
* `PHINGERS_LICENSING_FAILURE` (`PHG_809` ): Erro de licença.
* `PHINGERS_LIVENESS_FAILURE` (`PHG_810` ): Erro no teste de vida.
* `PHINGERS_NO_FINGERS_DETECTED` (`PHG_811` ): Nenhuma impressão digital foi detectada.
* `PHINGERS_UNIQUE_USER_ID_NOT_SPECIFIED` (`PHG_812` ): Usuário não especificado.
* `TIMEOUT` (`PHG_001` ): Timeout no processo.
* `FLOW_VIDEO_RECORDING_ERROR` (`PHG_819` ): Erro na Gravação de Vídeo do flow.
* `FLOW_TRACKING_ERROR` (`PHG_820` ): Erro de Tracking no flow.
* `TRACKING_STEP_ERROR` (`PHG_821` ): Erro na etapa de Tracking.
* `WIDGET_INTERNAL_ERROR` (`PHG_822` ): Erro interno do Widget.

***

## Recebimento 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 `ByteArray`. Para converter uma imagem para Base64, pode-se usar:

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

**Campos retornados**

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

**FingerResponse**

Todos os campos, exceto `position`, são nullable.

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

**SlapResponse**

* **position**: Índice de posição do slap (`Int`)
* **image**: Imagem slap (`ByteArray`, anulável)

**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 (`Long`, anulável), quando informado pelo widget.
* **durationMs**: Duração do vídeo em milissegundos (`Long`, anulável), quando informada pelo widget.

***

## 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 **da mão esquerda**.
* **RIGHT**: A captura **da mão direita**.

É do tipo `ReticleOrientation`. Por padrão `LEFT`.

**fingerFilter**

Filtro para selecionar a mão inteira ou um dedo específico: SLAP, ALL\_4\_FINGERS\_ONE\_BY\_ONE, ALL\_5\_FINGERS\_ONE\_BY\_ONE, INDEX\_FINGER, MIDDLE\_FINGER, RING\_FINGER, LITTLE\_FINGER, THUMB\_FINGER. O padrão é `SLAP`.

**templateType**

Define o formato do template a ser gerado: `NIST_TEMPLATE`, `ISO_TEMPLATE`, `NIST_T5_TEMPLATE` ou `NONE`. O padrão é `NIST_TEMPLATE`.

**useLiveness**

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

**extractionTimeout**

Define um tempo de extração em milissegundos (`Int`). O padrão é `50000`.

**showPreviousTip**

Exibe uma tela antes de iniciar a captura, com informações sobre o processo a ser realizado e um botão para iniciá-la. O padrão é `true`.

**showTutorial**

Indica se o componente ativa a tela de tutorial. Nessa tela, é explicado de forma intuitiva como realizar a captura. O padrão é `true`.

**showDiagnostic**

Exibe telas de diagnóstico ao final do processo. O padrão é `true`.

**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`. O padrão é `0.9` (`Float`).

**showEllipses**

Exibe as elipses durante a captura. O padrão é `true`.

**cropWidth**

Indica uma largura em pixels para realizar um recorte da captura (`Int`). O padrão é `512`. O SDK limita esse valor ao intervalo `64-2048`; com um valor menor ou igual a 0, o recorte não é aplicado.

**cropHeight**

Indica uma altura em pixels para realizar um recorte da captura (`Int`). O padrão é `512`. O SDK limita esse valor ao intervalo `64-2048`; com um valor menor ou igual a 0, o recorte não é aplicado.

**vibrationEnabled**

Ativa a vibração. O padrão é `true`.

**enableFlash**

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

**reticle**

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

**showPreviousFingerSelector**

Exibe o seletor de dedos antes da captura. O padrão é `false`.

**fingerSelectorHandOrientation**

Define qual(is) mão(s) são exibidas no seletor (`CaptureOrientation`: `LEFT`, `RIGHT`, `BOTH`). O padrão é `BOTH`.

**fingerSelectorOptions**

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

**licenseKey**

Chave de licença opcional repassada ao widget Phingers TF quando se usa ativação ou licenciamento específico.

**product**

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

**operationId**

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

**videoRecordingEnabled**

Ativa a gravação local opcional durante a captura de impressões digitais. O 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`. O 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 (explicadas no documento de [Personalização do SDK](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente permite especificamente modificar sua interface.

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

Os textos podem ser personalizados adicionando um arquivo XML de recursos ao aplicativo cliente e substituindo os valores padrão.

```kotlin
<!-- Previous Tip -->
    <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ões digitais</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>
    <!-- Previous Tip (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 estejam 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 estejam 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">Enquadre o dedo indicador na moldura. 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">Enquadre o dedo indicador na moldura. 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">Enquadre o polegar na moldura. 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ê vai 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 mínimo</string>
    <string name="phingers_widget_selector_option_thumb">Polegar</string>
    <string name="phingers_widget_selector_option_all4">4 dedos (indicador, médio, anelar e mínimo)</string>
    <string name="phingers_widget_selector_option_all4_sequence">4 dedos (um de cada vez)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 dedos (um de cada vez)</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 o rosto no centro e olhe diretamente para a câmera.</string>
    <string name="phingers_widget_tutorial_message_2">Retire qualquer objeto que cubra o 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 de sol 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 está 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 os dedos dentro da marcação</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">Nenhum dedo 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 sua mão firme</string>
    <string name="phingers_widget_timeout_desc">A captura excedeu o tempo limite. Tente novamente.</string>

    <!-- Dica dinâmica sobre o dedo (ES) -->
    <!-- %1$s = lado (esquerdo/direito), %2$s = dedo (indicador/médio/anelar/mínimo/polegar) -->
    <string name="phingers_widget_hint_place_finger_mark">Coloque seu dedo %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">mínimo</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 à pasta `res/raw/` do aplicativo:

```
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 nenhuma animação personalizada for incluída, serão usadas as animações padrão.

***
