> 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 through the **Phingers Component**.

This component is responsible for capturing the user's fingerprints (*fingerprints*) and extracting the associated biometric templates. Its main processes are:

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

In the section [Simplified Launch](/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) the steps required for the basic SDK Integration are described. This page adds specific information for using this component.

***

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

The component's 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 started and a new operation has been created, the fingerprint capture component can be launched using its controller.

Capture launch:

```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 it is necessary to create an object `PhingersConfigurationData`, which defines the capture process configuration.

The basic configuration required is as follows:

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

**Capture orientation**

Defines which hand to capture:

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

**Finger filters**

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

***

## Result reception <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

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

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

***

## Error handling <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as a `PhingersError`.

**List of errors**

* PHG\_ACTIVITY\_RESULT\_ERROR: The activity result is incorrect.
* PHG\_ACTIVITY\_RESULT\_MSG\_ERROR: The activity result message is incorrect.
* PHG\_APPLICATION\_CONTEXT\_ERROR: The application context is null.
* PHG\_CANCEL\_BY\_USER: The user has canceled the process.
* PHG\_CANCEL\_LAUNCH: General SDK cancellation.
* PHG\_COMPONENT\_LICENSE\_ERROR: The component license is not correct.
* PHG\_EMPTY\_LICENSE: The license string is empty.
* PHG\_FETCH\_DATA\_ERROR: Error while retrieving the result.
* FLOW\_ERROR: Error in the flow process.
* PHG\_INITIALIZATION\_ERROR: Initialization error.
* PHG\_INTERNAL\_ERROR: Internal error.
* PHG\_LOW\_QUALITY: Low image quality.
* PHG\_MANAGER\_NOT\_INITIALIZED: The managers are null or not initialized.
* PHG\_NO\_DATA\_ERROR: No capture data received.
* PHG\_OPERATION\_NOT\_CREATED: There is no operation in progress.
* PHG\_PERMISSION\_DENIED: The user has denied the permissions.
* PHG\_AUTOFOCUS\_FAILURE: Autofocus failure.
* PHG\_CAMERA\_FAILURE: Camera failure.
* PHG\_CAPTURE\_FAILURE: Capture failure.
* PHG\_CONFIGURATION\_FAILURE: Configuration error.
* PHG\_FINGERPRINT\_CAPTURE\_FAILURE: Fingerprint Capture failure.
* PHG\_FINGERPRINT\_TEMPLATE\_IO\_ERROR: Template I/O failure.
* PHG\_LICENSING\_FAILURE: License error.
* PHG\_LIVENESS\_FAILURE: liveness check error.
* PHG\_NO\_FINGERS\_DETECTED: No fingerprints detected.
* PHG\_UNIQUE\_USER\_ID\_NOT\_SPECIFIED: User not specified.
* PHG\_TIMEOUT: Timeout in the process.
* PHG\_FLOW\_VIDEO\_RECORDING\_ERROR: flow Video Recording error.
* PHG\_FLOW\_TRACKING\_ERROR: flow Tracking error.
* PHG\_TRACKING\_STEP\_ERROR: Tracking step error.

***

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

If successful, the field `data` contains an object `PhingersResult`.

Images are returned as `SdkImage`. It is possible to obtain the `Bitmap` using `image.bitmap`. 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)
* **slapImages**: List of `SlapResponse` (slap captures when applicable)
* **livenessScore**: Average liveness score (nullable)
* **recording**: Metadata of the optional local recording when `videoRecordingEnabled=true` and the Widget generates an MP4 file. It can be `null`.

**FingerResponse**

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

**SlapResponse**

* **position**: Slap position index
* **image**: Slap image (`ByteArray`)

**VideoRecordingResult**

* **path**: Full path of the generated video file.
* **fileName**: Video file name.
* **mimeType**: File MIME type. Default `video/mp4`.
* **sizeBytes**: File size in bytes, when the Widget reports it.
* **durationMs**: Video duration in milliseconds, when the Widget reports it.

***

## 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 object `PhingersConfigurationData` allows customizing the component's behavior.

**Available parameters**

**reticleOrientation**

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

* **LEFT**: Capture is enabled **of the left hand**.
* **RIGHT**: Capture is enabled **of the right hand**.

**fingerFilter**

Filter to choose the whole hand or a specific finger: SLAP, INDEX\_FINGER, MIDDLE\_FINGER, RING\_FINGER, LITTLE\_FINGER, THUMB\_FINGER.

**templateType**

Defines the template format to generate (NIST/ISO variants).

**useLiveness**

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

**extractionTimeout**

Sets an extraction time.

**showPreviousTip**

Displays a screen before starting the capture with information about the process to be carried out and a button to start it.

**showTutorial**

Indicates whether the component activates the tutorial screen. In this view, it intuitively explains how the capture is performed.

**showDiagnostic**

Show diagnostic screens at the end of the process.

**threshold**

The parameter configures a captureQualityThreshold, to define a quality threshold for performing the capture. The SDK limits this value to the range `0.0-1.0`.

**showEllipses**

Shows the ellipses during capture.

**cropWidth**

Indicates a width for cropping the capture.

**cropHeight**

Indicates a height for cropping the capture.

**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 reticle identifier. By default `"R_S"`.

**showPreviousFingerSelector**

Shows the finger selector before capture.

**fingerSelectorHandOrientation**

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

**fingerSelectorOptions**

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

**licenseKey**

Optional license key that is passed to the Phingers TF Widget when specific activation or licensing is used.

**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. By default `false`.

**videoRecordingDirectoryPath**

Optional destination directory for the generated video file.

**videoRecordingFileName**

Optional file name for the generated recording.

**videoRecordingQuality**

Local recording quality. The allowed values are `LOW`, `MEDIUM` and `HIGH`. By default `MEDIUM`.

***

## Component Customization <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Besides the changes that can be made at SDK level (which are explained in the document of [SDK Customization](/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this specific component allows its interface to be modified.

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

The texts can be customized by adding an XML resource file in 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 the hand closer to or farther from the camera 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 the hand closer to or farther from the camera 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">Focus the index finger in the frame. Move the finger closer to or farther from the camera 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">Focus the index finger in the frame. Move the finger closer to or farther from the camera until your fingerprint is in focus.</string>
    <string name="phingers_widget_tip_title_thumb">Thumb fingerprint</string>
    <string name="phingers_widget_tip_message_thumb">Focus the thumb in the frame. Move the finger closer to or farther from the camera 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 finger</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 by one)</string>
    <string name="phingers_widget_selector_option_all5_sequence">5 fingers (one by one)</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">Place your face in the center 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">Look for a well-lit environment, without shadows on your face.</string>
    <string name="phingers_widget_tutorial_message_1_anim_desc">The photo is taken when the person is in the center.</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 (ES) -->
    <string name="phingers_widget_camera_status_position_fingers">Place your fingers inside the mark</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 away</string>
    <string name="phingers_widget_camera_status_low_focus">Move the finger to focus</string>
    <string name="phingers_widget_camera_status_good_focus">Keep the finger still</string>
    <string name="phingers_widget_camera_status_wrong_angle">Hold the finger vertically</string>
    <string name="phingers_widget_camera_status_too_few">Finger not 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 the finger of the left hand</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">You must place the finger of the right hand</string>
    <string name="phingers_widget_camera_status_error">Capture error</string>
    <string name="phingers_widget_camera_status_timeout">Capture time 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">The capture has timed out. 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 the files with the same name in the application's folder: `res/raw/` of the application:

```
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 custom animations are not included, the default animations will be used.

***