> 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/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-de-huellas.md).

# Captura de huellas - Phingers

## Introducción <a href="#id-1-introduccion" id="id-1-introduccion"></a>

La captura de huellas se realiza mediante el **Phingers Component**.

Este componente se encarga de capturar las huellas dactilares del usuario (*fingerprints*) y extraer las plantillas biométricas asociadas. Sus principales procesos son:

* Gestión interna de cámara y permisos.
* Diferentes modos de extracción: mano completa (cuatro dedos sin pulgar), pulgar, o dedos individuales.
* Detección de vivacidad integrada.
* Asistencia guiada durante el proceso de captura.
* Generación de plantillas biométricas, imágenes y métricas de calidad.

En el apartado [Lanzamiento simplificado](/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) se describen los pasos necesarios para la integración básica del SDK. En esta página se añade la información específica para el uso de este componente.

***

## Dependencia <a href="#id-2-dependencia" id="id-2-dependencia"></a>

La dependencia específica del componente es:

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

***

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

| **Controlador**       | **Descripción**                                                        |
| --------------------- | ---------------------------------------------------------------------- |
| PhingersTFController  | Controlador principal de captura de huellas                            |
| FPhingersTFController | Controlador principal de captura de huellas para integraciones de flow |

## Lanzamiento simplificado <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

Una vez iniciado el SDK y creada una nueva operación, se puede lanzar el componente de captura de huellas utilizando su controlador.

Lanzamiento de la captura:

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

***

## Configuración básica

Para lanzar el componente es necesario crear un objeto `PhingersConfigurationData`, que define la configuración del proceso de captura.

La configuración básica necesaria es la siguiente:

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

**Orientación de captura**

Define la mano a capturar:

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

**Filtros de dedos**

Permite definir qué dedos se capturan durante el proceso:

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

**Opciones de TemplateType**:

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

***

## Recepción del resultado <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

El lanzamiento del componente devuelve un resultado en formato `SdkResult`, que puede corresponder a una ejecución correcta o a un error.

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

***

## Recepción de errores <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Los errores se devuelven como un objeto `PhingersError`.

**Listado de errores**

* PHG\_ACTIVITY\_RESULT\_ERROR: El resultado de la actividad es incorrecto.
* PHG\_ACTIVITY\_RESULT\_MSG\_ERROR: El mensaje del resultado de la actividad es incorrecto.
* PHG\_APPLICATION\_CONTEXT\_ERROR: El contexto de aplicación es nulo.
* PHG\_CANCEL\_BY\_USER: El usuario ha cancelado el proceso.
* PHG\_CANCEL\_LAUNCH: Cancelación general del SDK.
* PHG\_COMPONENT\_LICENSE\_ERROR: La licencia del componente no es correcta.
* PHG\_EMPTY\_LICENSE: El string de licencia está vacío.
* PHG\_FETCH\_DATA\_ERROR: Error en la recogida del resultado.
* FLOW\_ERROR: Error en el proceso de flow.
* PHG\_INITIALIZATION\_ERROR: Error de inicialización.
* PHG\_INTERNAL\_ERROR: Error interno.
* PHG\_LOW\_QUALITY: Baja calidad de la imagen.
* PHG\_MANAGER\_NOT\_INITIALIZED: Los managers son nulos o no están inicializados.
* PHG\_NO\_DATA\_ERROR: No se han recibido datos de la captura.
* PHG\_OPERATION\_NOT\_CREATED: No hay ninguna operación en curso.
* PHG\_PERMISSION\_DENIED: El usuario ha rechazado los permisos.
* PHG\_AUTOFOCUS\_FAILURE: Fallo del autofocus.
* PHG\_CAMERA\_FAILURE: Fallo de la cámara.
* PHG\_CAPTURE\_FAILURE: Fallo en la captura.
* PHG\_CONFIGURATION\_FAILURE: Error de configuración.
* PHG\_FINGERPRINT\_CAPTURE\_FAILURE: Fallo en la captura de huellas.
* PHG\_FINGERPRINT\_TEMPLATE\_IO\_ERROR: Fallo IO de plantilla.
* PHG\_LICENSING\_FAILURE: Error de licencia.
* PHG\_LIVENESS\_FAILURE: Error en la prueba de vida.
* PHG\_NO\_FINGERS\_DETECTED: No se han detectado huellas.
* PHG\_UNIQUE\_USER\_ID\_NOT\_SPECIFIED: Usuario no especificado.
* PHG\_TIMEOUT: Timeout en el proceso.
* PHG\_FLOW\_VIDEO\_RECORDING\_ERROR: Error en la grabación de vídeo del flow.
* PHG\_FLOW\_TRACKING\_ERROR: Error de tracking en el flow.
* PHG\_TRACKING\_STEP\_ERROR: Error en el paso de tracking.

***

## Recepción del resultado correcto - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

En caso de éxito, el campo `data` contiene un objeto `PhingersResult`.

Las imágenes se devuelven como `SdkImage`. Es posible obtener el `Bitmap` mediante `image.bitmap`. Para convertir una imagen a Base64 se puede utilizar:

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

**Campos devueltos**

* **fingers**: Lista de `FingerResponse` (una entrada por dedo capturado)
* **slapImages**: Lista de `SlapResponse` (capturas slap cuando aplique)
* **livenessScore**: Media del score de vivacidad (nullable)
* **recording**: Metadatos de la grabación local opcional cuando `videoRecordingEnabled=true` y el widget genera un fichero MP4. Puede ser `null`.

**FingerResponse**

* **position**: Índice de posición del dedo
* **wsq**: Imagen WSQ (`ByteArray`)
* **displayImage**: Imagen de visualización (`ByteArray`, PNG)
* **minutiaesNumber**: Número de minutias detectadas
* **quality**: Puntuación de calidad
* **nistQuality**: Puntuación de calidad NIST
* **nist2Quality**: Puntuación de calidad NIST2
* **template**: Plantilla de huella (`ByteArray`)
* **proprietaryQuality**: Calidad propietaria del proveedor
* **templateType**: Identificador del tipo de plantilla
* **imageWidth**: Ancho de la imagen en píxeles
* **imageHeight**: Alto de la imagen en píxeles

**SlapResponse**

* **position**: Índice de posición del slap
* **image**: Imagen slap (`ByteArray`)

**VideoRecordingResult**

* **path**: Ruta completa del fichero de vídeo generado.
* **fileName**: Nombre del fichero de vídeo.
* **mimeType**: Tipo MIME del fichero. Por defecto `video/mp4`.
* **sizeBytes**: Tamaño del fichero en bytes, cuando el widget lo informa.
* **durationMs**: Duración del vídeo en milisegundos, cuando el widget la informa.

***

## Información avanzada <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

### Configuración avanzada del componente <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

El objeto `PhingersConfigurationData` permite personalizar el comportamiento del componente.

**Parámetros disponibles**

**reticleOrientation**

Establece el modo de detección de huellas e indica qué dedos se van a detectar durante el proceso. Los valores permitidos son:

* **LEFT**: Se activa la captura **de la mano izquierda**.
* **RIGHT**: Se activa la captura **de la mano derecha**.

**fingerFilter**

Filtro para elegir la mano entera o un dedo en concreto: SLAP, INDEX\_FINGER, MIDDLE\_FINGER, RING\_FINGER, LITTLE\_FINGER, THUMB\_FINGER.

**templateType**

Define el formato de plantilla a generar (variantes NIST/ISO).

**useLiveness**

Activa o desactiva el detector de vivacidad durante el proceso de captura de huellas. Por defecto se encuentra a **true**.

**extractionTimeout**

Establece un tiempo de extracción.

**showPreviousTip**

Muestra una pantalla previa al lanzamiento de la captura con información sobre el proceso a realizar y un botón para el lanzamiento.

**showTutorial**

Indica si el componente activa la pantalla de tutorial. En esta vista se explica de forma intuitiva cómo se realiza la captura.

**showDiagnostic**

Mostrar pantallas de diagnóstico al final del proceso.

**threshold**

El parámetro configura un captureQualityThreshold, para definir un threshold de calidad para realizar la captura. El SDK limita este valor al rango `0.0-1.0`.

**showEllipses**

Muestra las elipses durante la captura.

**cropWidth**

Indica un ancho para realizar un recorte de la captura.

**cropHeight**

Indica una altura para realizar un recorte de la captura.

**vibrationEnabled**

Activa la vibración. Por defecto `true`.

**enableFlash**

Activa o desactiva el flash de la cámara durante el proceso de captura de huellas. Por defecto se encuentra a **true**.

**reticle**

Identificador opcional del retículo. Por defecto `"R_S"`.

**showPreviousFingerSelector**

Muestra el selector de dedos antes de la captura.

**fingerSelectorHandOrientation**

Define qué mano(s) se muestran en el selector (`LEFT`, `RIGHT`, `BOTH`).

**fingerSelectorOptions**

Define la lista de filtros que se muestran en el selector. Si está vacía, el SDK usa: `ALL_4_FINGERS_ONE_BY_ONE`, `SLAP`, `INDEX_FINGER`.

**licenseKey**

Clave de licencia opcional que se traslada al widget Phingers TF cuando se usa activación o licenciamiento específico.

**product**

Producto opcional asociado a la activación o licenciamiento del widget.

**operationId**

Identificador de operación opcional que se envía al widget para trazabilidad y asociación de la captura.

**videoRecordingEnabled**

Activa la grabación local opcional durante la captura de huellas. Por defecto `false`.

**videoRecordingDirectoryPath**

Directorio de destino opcional para el fichero de vídeo generado.

**videoRecordingFileName**

Nombre de fichero opcional para la grabación generada.

**videoRecordingQuality**

Calidad de grabación local. Los valores permitidos son `LOW`, `MEDIUM` y `HIGH`. Por defecto `MEDIUM`.

***

## Personalización del componente <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Aparte de los cambios que se pueden realizar a nivel de SDK (los cuales se explican en el documento de [Personalización del SDK](/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente en concreto permite la modificación de su interfaz.

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

Los textos pueden personalizarse añadiendo un fichero XML de recursos en la aplicación cliente y sobrescribiendo los valores por defecto.

```kotlin
<!-- Previous Tip -->
    <string name="phingers_widget_tip_title">Captura de huellas</string>
    <string name="phingers_widget_tip_message">Coloca tu dedo dentro de la marca</string>
    <string name="phingers_widget_tip_message_alt">Coloca tu dedo dentro de la marca</string>
    <string name="phingers_widget_tip_button">Comenzar</string>
    <string name="phingers_widget_tip_button_alt">Comenzar captura de huellas</string>
    <string name="phingers_widget_tip_close_button_alt">Volver</string>
    <string name="phingers_widget_tip_info_button_alt">Ver consejos</string>
    <string name="phingers_widget_tip_anim_desc">Animación de instrucciones para la captura de huella</string>
    <!-- Previous Tip (tipos específicos) -->
    <string name="phingers_widget_tip_title_left_slap">Huellas mano izquierda</string>
    <string name="phingers_widget_tip_message_left_slap">Junta tus dedos. Acerca o aleja la mano hasta que se enfoquen tus huellas.</string>
    <string name="phingers_widget_tip_title_right_slap">Huellas mano derecha</string>
    <string name="phingers_widget_tip_message_right_slap">Junta tus dedos. Acerca o aleja la mano hasta que se enfoquen tus huellas.</string>
    <string name="phingers_widget_tip_title_left_finger">Huellas mano izquierda</string>
    <string name="phingers_widget_tip_message_left_finger">Enfoca el dedo índice en el recuadro. Acerca o aleja el dedo hasta que se enfoque tu huella.</string>
    <string name="phingers_widget_tip_title_right_finger">Huellas mano derecha</string>
    <string name="phingers_widget_tip_message_right_finger">Enfoca el dedo índice en el recuadro. Acerca o aleja el dedo hasta que se enfoque tu huella.</string>
    <string name="phingers_widget_tip_title_thumb">Huella dedo pulgar</string>
    <string name="phingers_widget_tip_message_thumb">Enfoca el dedo pulgar en el recuadro. Acerca o aleja el dedo hasta que se enfoque tu huella.</string>
    <!-- Selector de dedos -->
    <string name="phingers_widget_selector_hand_question">¿Qué mano utilizarás?</string>
    <string name="phingers_widget_selector_hand_left">Izquierda</string>
    <string name="phingers_widget_selector_hand_right">Derecha</string>
    <string name="phingers_widget_selector_secondary_question">¿Qué huellas quieres escanear?</string>
    <string name="phingers_widget_selector_option_index">Dedo índice</string>
    <string name="phingers_widget_selector_option_middle">Dedo corazón</string>
    <string name="phingers_widget_selector_option_ring">Dedo anular</string>
    <string name="phingers_widget_selector_option_little">Dedo meñique</string>
    <string name="phingers_widget_selector_option_thumb">Dedo pulgar</string>
    <string name="phingers_widget_selector_option_all4">4 dedos (índice, corazón, anular y meñique)</string>
    <string name="phingers_widget_selector_option_all4_sequence">4 dedos (uno a uno)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 dedos (uno a uno)</string>
    <string name="phingers_widget_selector_primary_button">Continuar</string>
    <!-- Capture -->
    <string name="phingers_widget_capture_close_button_alt">Volver</string>
    <!-- Tutorial -->
    <string name="phingers_widget_tutorial_message_1">Coloca tu cara en el centro y mira de frente a la cámara.</string>
    <string name="phingers_widget_tutorial_message_2">Retira cualquier elemento que cubra tu cara.</string>
    <string name="phingers_widget_tutorial_message_3">Busca un entorno bien iluminado, sin sombras sobre tu rostro.</string>
    <string name="phingers_widget_tutorial_message_1_anim_desc">La foto se realiza cuando la persona está en el centro.</string>
    <string name="phingers_widget_tutorial_message_2_anim_desc">Una persona se quita las gafas de sol y se retira el pelo de los ojos.</string>
    <string name="phingers_widget_tutorial_message_3_anim_desc">La imagen aparece oscura y una persona enciende la luz.</string>
    <string name="phingers_widget_tutorial_close_button_alt">Volver al tutorial previo</string>
    <!-- Confirmation -->
    <string name="phingers_widget_image_captured">Imagen capturada</string>
    <string name="phingers_widget_confirmation_message">¿Tu foto se ve de forma clara y nítida?</string>
    <string name="phingers_widget_confirmation_retry">Reintentar</string>
    <string name="phingers_widget_confirmation_continue">Continuar</string>

    <!-- Camera status (ES) -->
    <string name="phingers_widget_camera_status_position_fingers">Coloca tus dedos dentro de la marca</string>
    <string name="phingers_widget_camera_status_processing">Procesando…</string>
    <string name="phingers_widget_camera_status_too_far">Acerca la mano</string>
    <string name="phingers_widget_camera_status_too_close">Aleja la mano</string>
    <string name="phingers_widget_camera_status_low_focus">Mueve el dedo para enfocar</string>
    <string name="phingers_widget_camera_status_good_focus">Mantén el dedo quieto</string>
    <string name="phingers_widget_camera_status_wrong_angle">Coloca el dedo en vertical</string>
    <string name="phingers_widget_camera_status_too_few">No se ha detectado el dedo</string>
    <string name="phingers_widget_camera_status_too_many">Varios dedos detectados</string>
    <string name="phingers_widget_camera_status_wrong_hand_left">Debes poner el dedo de la mano izquierda</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">Debes poner el dedo de la mano derecha</string>
    <string name="phingers_widget_camera_status_error">Error en la captura</string>
    <string name="phingers_widget_camera_status_timeout">Tiempo de captura agotado</string>
    <string name="phingers_widget_camera_status_success">¡Huella capturada!</string>
    <string name="phingers_widget_camera_status_keep_hand_steady">Mantén tu mano firme</string>
    <string name="phingers_widget_timeout_desc">La captura ha superado el tiempo. Inténtalo de nuevo.</string>

    <!-- Dynamic finger hint (ES) -->
    <!-- %1$s = lado (izquierdo/derecho), %2$s = dedo (índice/medio/anular/meñique/pulgar) -->
    <string name="phingers_widget_hint_place_finger_mark">Coloca tu %2$s %1$s dentro de la marca</string>
    <string name="phingers_widget_side_left">izquierdo</string>
    <string name="phingers_widget_side_right">derecho</string>
    <string name="phingers_widget_finger_index">índice</string>
    <string name="phingers_widget_finger_middle">medio</string>
    <string name="phingers_widget_finger_ring">anular</string>
    <string name="phingers_widget_finger_little">meñique</string>
    <string name="phingers_widget_finger_thumb">pulgar</string>
```

### Animaciones <a href="#id-82-animaciones" id="id-82-animaciones"></a>

Las animaciones del componente son **Lottie (JSON)**.

Para sustituirlas, añade los archivos con el mismo nombre en la carpeta `res/raw/` de la aplicación:

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

Si no se incluyen animaciones personalizadas, se utilizarán las animaciones por defecto.

***