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

# Fingerprint Capture - Phingers

## Introduction <a href="#id-1-introduccion" id="id-1-introduccion"></a>

Fingerprint capture is performed using the **Phingers Component**.

This component captures the user's fingerprints (*fingerprints*) and extracts the associated biometric templates. Its main processes are:

* Internal camera and permissions management.
* Different extraction modes: full hand (four fingers excluding the thumb), thumb, or individual fingers.
* Integrated liveness detection.
* Guided assistance during the capture process.
* Generation of biometric templates, images, and quality metrics.

The [Simplified Launch](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) section describes the steps required for the basic integration of the SDK. This page provides additional information specific to using this component.

***

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

The component-specific dependency is:

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

***

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

| **Controller**        | **Description**                                           |
| --------------------- | --------------------------------------------------------- |
| PhingersTFController  | Main fingerprint capture controller                       |
| FPhingersTFController | Main fingerprint capture controller for flow integrations |

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

Once the SDK has been initialized and a new operation has been created, you can launch the fingerprint capture component using its controller.

Launching fingerprint capture:

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

***

## Basic Configuration

To launch the component, you need to create a `PhingersConfigurationData` object, which defines the capture process configuration.

The required basic configuration is as follows:

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

**Capture orientation**

Defines which hand to capture (`reticleOrientation`, of type `ReticleOrientation`):

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

**Finger filters**

Lets you define which fingers are captured during the process:

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

**TemplateType options**:

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

***

## Receiving the result <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

Launching the component returns a result in `SdkResult`, which may correspond to a successful execution or an error.

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

***

## Receiving errors <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as a `PhingersError`.

**Error list**

* `ACTIVITY_RESULT_ERROR` (`PHG_817`): The activity result is incorrect.
* `ACTIVITY_RESULT_MSG_ERROR` (`PHG_813`): The activity result message is incorrect.
* `APPLICATION_CONTEXT_ERROR` (`PHG_814`): The application context is null.
* `CANCEL_BY_USER` (`PHG_000`): The user canceled the process.
* `CANCEL_LAUNCH` (`PHG_007`): General SDK cancellation.
* `COMPONENT_LICENSE_ERROR` (`PHG_002`): The component license is invalid.
* `EMPTY_LICENSE` (`PHG_003`): The license string is empty.
* `FETCH_DATA_ERROR` (`PHG_815`): Error retrieving the result.
* `FLOW_ERROR` (`PHG_823`): Error in the flow process.
* `INITIALIZATION_ERROR` (`PHG_004`): Initialization error.
* `INTERNAL_ERROR` (`PHG_800`): Internal error.
* `LOW_QUALITY` (`PHG_801`): Low image quality.
* `MANAGER_NOT_INITIALIZED` (`PHG_816`): Managers are null or not initialized.
* `NO_DATA_ERROR` (`PHG_005`): No data was received from the capture.
* `OPERATION_NOT_CREATED` (`PHG_006`): No operation is in progress.
* `PERMISSION_DENIED` (`PHG_802`): The user has denied the permissions.
* `PHINGERS_AUTOFOCUS_FAILURE` (`PHG_803`): Autofocus failure.
* `PHINGERS_CAMERA_FAILURE` (`PHG_804`): Camera failure.
* `PHINGERS_CAPTURE_FAILURE` (`PHG_805`): Capture failure.
* `PHINGERS_CONFIGURATION_FAILURE` (`PHG_806`): Configuration error.
* `PHINGERS_FINGERPRINT_CAPTURE_FAILURE` (`PHG_807`): Fingerprint Capture failure.
* `PHINGERS_FINGERPRINT_TEMPLATE_IO_ERROR` (`PHG_808`): Template I/O failure.
* `PHINGERS_LICENSING_FAILURE` (`PHG_809`): License error.
* `PHINGERS_LIVENESS_FAILURE` (`PHG_810`): Liveness check error.
* `PHINGERS_NO_FINGERS_DETECTED` (`PHG_811`): No fingerprints detected.
* `PHINGERS_UNIQUE_USER_ID_NOT_SPECIFIED` (`PHG_812`): User not specified.
* `TIMEOUT` (`PHG_001`): Process timeout.
* `FLOW_VIDEO_RECORDING_ERROR` (`PHG_819`): Flow video recording error.
* `FLOW_TRACKING_ERROR` (`PHG_820`): Flow Tracking error.
* `TRACKING_STEP_ERROR` (`PHG_821`): Tracking step error.
* `WIDGET_INTERNAL_ERROR` (`PHG_822`): Internal Widget error.

***

## Receiving the successful result - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

In case of success, the field `data` contains an object `PhingersResult`.

Images are returned as `ByteArray`. To convert an image to Base64, you can use:

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

**Returned fields**

* **fingers**: List of `FingerResponse` (one entry per captured finger). Nullable; defaults to an empty list.
* **slapImages**: List of `SlapResponse` (slap captures, when applicable). Nullable; defaults to an empty list.
* **livenessScore**: Average liveness score (`Float`, nullable)
* **recording**: Optional local recording metadata when `videoRecordingEnabled=true` and the widget generates an MP4 file. It may be `null`.

**FingerResponse**

All fields except `position`are nullable.

* **position**: Finger position index (`Int`)
* **wsq**: WSQ image (`ByteArray`)
* **displayImage**: Display image (`ByteArray`, PNG)
* **minutiaesNumber**: Number of detected minutiae (`Int`)
* **quality**: Quality score (`Int`)
* **nistQuality**: NIST quality score (`Int`)
* **nist2Quality**: NIST2 quality score (`Int`)
* **template**: Fingerprint template (`ByteArray`)
* **proprietaryQuality**: Provider proprietary quality (`Int`)
* **templateType**: Template type identifier (`Int`)
* **imageWidth**: Image width in pixels (`Int`)
* **imageHeight**: Image height in pixels (`Int`)

**SlapResponse**

* **position**: Slap position index (`Int`)
* **image**: Slap image (`ByteArray`, nullable)

**VideoRecordingResult**

* **path**: Full path to the generated video file.
* **fileName**: Video file name.
* **mimeType**: File MIME type. Defaults to `video/mp4`.
* **sizeBytes**: File size in bytes (`Long`, nullable), when reported by the widget.
* **durationMs**: Video duration in milliseconds (`Long`, nullable), when reported by the widget.

***

## Advanced information <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

### Advanced component configuration <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

The `PhingersConfigurationData` object lets you customize the component's behavior.

**Available parameters**

**reticleOrientation**

Sets the fingerprint detection mode and indicates which fingers will be detected during the process. Allowed values are:

* **LEFT**: Captures **the left hand**.
* **RIGHT**: Captures **the right hand**.

It is of type `ReticleOrientation`By default `LEFT`.

**fingerFilter**

Filter for selecting the entire hand or a specific finger: SLAP, ALL\_4\_FINGERS\_ONE\_BY\_ONE, ALL\_5\_FINGERS\_ONE\_BY\_ONE, INDEX\_FINGER, MIDDLE\_FINGER, RING\_FINGER, LITTLE\_FINGER, THUMB\_FINGER. By default `SLAP`.

**templateType**

Defines the template format to generate: `NIST_TEMPLATE`, `ISO_TEMPLATE`, `NIST_T5_TEMPLATE` or `NONE`. By default `NIST_TEMPLATE`.

**useLiveness**

Enables or disables the liveness detector during the fingerprint capture process. By default, it is set to **true**.

**extractionTimeout**

Sets an extraction time in milliseconds (`Int`). By default `50000`.

**showPreviousTip**

Displays a screen before starting the capture, with information about the process to be performed and a button to start it. By default `true`.

**showTutorial**

Indicates whether the component displays the tutorial screen. This view intuitively explains how to capture fingerprints. By default `true`.

**showDiagnostic**

Show diagnostic screens at the end of the process. By default `true`.

**threshold**

This parameter sets a captureQualityThreshold to define the quality threshold for capturing. The SDK limits this value to the range `0.0-1.0`. By default `0.9` (`Float`).

**showEllipses**

Displays the ellipses during capture. By default `true`.

**cropWidth**

Specifies a width in pixels for cropping the capture (`Int`). By default `512`. The SDK limits it to the range `64-2048`; a value less than or equal to 0 disables cropping.

**cropHeight**

Specifies a height in pixels for cropping the capture (`Int`). By default `512`. The SDK limits it to the range `64-2048`; a value less than or equal to 0 disables cropping.

**vibrationEnabled**

Enables vibration. By default `true`.

**enableFlash**

Enables or disables the camera flash during the fingerprint capture process. By default, it is set to **true**.

**reticle**

Optional grid identifier. Defaults to `"R_S"`.

**showPreviousFingerSelector**

Shows the finger selector before capture. Defaults to `false`.

**fingerSelectorHandOrientation**

Defines which hand(s) are shown in the selector (`CaptureOrientation`: `LEFT`, `RIGHT`, `BOTH`). Defaults to `BOTH`.

**fingerSelectorOptions**

Defines the list of filters shown in the selector. If empty, the SDK uses: `ALL_4_FINGERS_ONE_BY_ONE`, `SLAP`, `INDEX_FINGER`.

**licenseKey**

Optional license key passed to the Phingers TF widget when using specific activation or licensing.

**product**

Optional product associated with the widget's activation or licensing.

**operationId**

Optional operation identifier sent to the widget for traceability and capture association.

**videoRecordingEnabled**

Enables optional local recording during fingerprint capture. Defaults to `false`.

**videoRecordingDirectoryPath**

Optional destination directory for the generated video file.

**videoRecordingFileName**

Optional file name for the generated recording.

**videoRecordingQuality**

Local recording quality. Allowed values are `LOW`, `MEDIUM` and `HIGH`. Defaults to `MEDIUM`.

***

## Customization of the component <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Apart from the changes that can be made at the SDK level (explained in the document [SDK Customization](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this particular component also allows its interface to be modified.

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

The text can be customized by adding an XML resource file to the client application and overriding the default values.

```kotlin
<!-- Previous Tip -->
    <string name="phingers_widget_tip_title">Fingerprint Capture</string>
    <string name="phingers_widget_tip_message">Place your finger inside the mark</string>
    <string name="phingers_widget_tip_message_alt">Place your finger inside the mark</string>
    <string name="phingers_widget_tip_button">Start</string>
    <string name="phingers_widget_tip_button_alt">Start fingerprint capture</string>
    <string name="phingers_widget_tip_close_button_alt">Back</string>
    <string name="phingers_widget_tip_info_button_alt">View tips</string>
    <string name="phingers_widget_tip_anim_desc">Instruction animation for fingerprint capture</string>
    <!-- Previous Tip (specific types) -->
    <string name="phingers_widget_tip_title_left_slap">Left-hand fingerprints</string>
    <string name="phingers_widget_tip_message_left_slap">Bring your fingers together. Move your hand closer or farther away until your fingerprints are in focus.</string>
    <string name="phingers_widget_tip_title_right_slap">Right-hand fingerprints</string>
    <string name="phingers_widget_tip_message_right_slap">Bring your fingers together. Move your hand closer or farther away until your fingerprints are in focus.</string>
    <string name="phingers_widget_tip_title_left_finger">Left-hand fingerprints</string>
    <string name="phingers_widget_tip_message_left_finger">Center your index finger in the frame. Move your finger closer or farther away until your fingerprint is in focus.</string>
    <string name="phingers_widget_tip_title_right_finger">Right-hand fingerprints</string>
    <string name="phingers_widget_tip_message_right_finger">Center your index finger in the frame. Move your finger closer or farther away until your fingerprint is in focus.</string>
    <string name="phingers_widget_tip_title_thumb">Thumbprint</string>
    <string name="phingers_widget_tip_message_thumb">Center your thumb in the frame. Move your finger closer or farther away until your fingerprint is in focus.</string>
    <!-- Finger selector -->
    <string name="phingers_widget_selector_hand_question">Which hand will you use?</string>
    <string name="phingers_widget_selector_hand_left">Left</string>
    <string name="phingers_widget_selector_hand_right">Right</string>
    <string name="phingers_widget_selector_secondary_question">Which fingerprints do you want to scan?</string>
    <string name="phingers_widget_selector_option_index">Index finger</string>
    <string name="phingers_widget_selector_option_middle">Middle finger</string>
    <string name="phingers_widget_selector_option_ring">Ring finger</string>
    <string name="phingers_widget_selector_option_little">Little finger</string>
    <string name="phingers_widget_selector_option_thumb">Thumb</string>
    <string name="phingers_widget_selector_option_all4">4 fingers (index, middle, ring, and little)</string>
    <string name="phingers_widget_selector_option_all4_sequence">4 fingers (one at a time)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 fingers (one at a time)</string>
    <string name="phingers_widget_selector_primary_button">Continue</string>
    <!-- Capture -->
    <string name="phingers_widget_capture_close_button_alt">Back</string>
    <!-- Tutorial -->
    <string name="phingers_widget_tutorial_message_1">Center your face and look straight at the camera.</string>
    <string name="phingers_widget_tutorial_message_2">Remove anything covering your face.</string>
    <string name="phingers_widget_tutorial_message_3">Find a well-lit area with no shadows on your face.</string>
    <string name="phingers_widget_tutorial_message_1_anim_desc">The photo is taken when the person is centered.</string>
    <string name="phingers_widget_tutorial_message_2_anim_desc">A person takes off their sunglasses and moves their hair away from their eyes.</string>
    <string name="phingers_widget_tutorial_message_3_anim_desc">The image appears dark, and a person turns on the light.</string>
    <string name="phingers_widget_tutorial_close_button_alt">Back to the previous tutorial</string>
    <!-- Confirmation -->
    <string name="phingers_widget_image_captured">Image captured</string>
    <string name="phingers_widget_confirmation_message">Does your photo look clear and sharp?</string>
    <string name="phingers_widget_confirmation_retry">Retry</string>
    <string name="phingers_widget_confirmation_continue">Continue</string>

    <!-- Camera status (EN) -->
    <string name="phingers_widget_camera_status_position_fingers">Place your fingers inside the outline</string>
    <string name="phingers_widget_camera_status_processing">Processing…</string>
    <string name="phingers_widget_camera_status_too_far">Move your hand closer</string>
    <string name="phingers_widget_camera_status_too_close">Move your hand farther away</string>
    <string name="phingers_widget_camera_status_low_focus">Move your finger to focus</string>
    <string name="phingers_widget_camera_status_good_focus">Keep your finger still</string>
    <string name="phingers_widget_camera_status_wrong_angle">Hold your finger vertically</string>
    <string name="phingers_widget_camera_status_too_few">No finger detected</string>
    <string name="phingers_widget_camera_status_too_many">Multiple fingers detected</string>
    <string name="phingers_widget_camera_status_wrong_hand_left">You must place a finger from your left hand</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">You must place a finger from your right hand</string>
    <string name="phingers_widget_camera_status_error">Capture error</string>
    <string name="phingers_widget_camera_status_timeout">Capture timed out</string>
    <string name="phingers_widget_camera_status_success">Fingerprint captured!</string>
    <string name="phingers_widget_camera_status_keep_hand_steady">Keep your hand steady</string>
    <string name="phingers_widget_timeout_desc">Capture timed out. Please try again.</string>

    <!-- Dynamic finger hint (ES) -->
    <!-- %1$s = side (left/right), %2$s = finger (index/middle/ring/little/thumb) -->
    <string name="phingers_widget_hint_place_finger_mark">Place your %2$s %1$s inside the mark</string>
    <string name="phingers_widget_side_left">left</string>
    <string name="phingers_widget_side_right">right</string>
    <string name="phingers_widget_finger_index">index</string>
    <string name="phingers_widget_finger_middle">middle</string>
    <string name="phingers_widget_finger_ring">ring</string>
    <string name="phingers_widget_finger_little">little</string>
    <string name="phingers_widget_finger_thumb">thumb</string>
```

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

The component animations are **Lottie (JSON)**.

To replace them, add files with the same name to the app's `res/raw/` folder:

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

If no custom animations are included, the default animations will be used.

***
