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

# Fingerprint Capture - Phingers

This component requires iOS 13 or later.

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

The *Component* covered in this document is called the ***Phingers Component***. It captures the user's fingerprints and then extracts fingerprint templates. Its main features are as follows:

* Two operating modes: capturing four fingers on the hand (excluding the thumb), or capturing only the thumb.
* Internal camera management.
* Permission management.
* Built-in liveness detection.
* Guidance during fingerprint capture.
* Generation of templates containing fingerprint features, images, and scores.

The [Simplified Launch](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) section describes the steps required for basic SDK integration. This section provides information on launching this component.

## **Dependencies**

To avoid conflicts and compatibility issues, if you want to install the component in a project that contains an old version of Facephi libraries (*Widgets*), they must be completely removed before installing the **SDKMobile**.

### CocoaPods

```sh
pod 'FPHISDKMainComponent', '~> $VERSION'
```

* To install this component, add the following entry to the application's Podfile:

```sh
pod 'FPHISDKPhingersTFComponent', '~> $VERSION'
```

* Once the dependencies are installed, you can use the component's various features.

### **SPM**

* The required dependencies that must be installed beforehand are:

```swift
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```

* To install the SelphID component, add the following to the project's modules:

<pre class="language-swift"><code class="lang-swift"><strong>//HTTPS
</strong>https://github.com/facephi-clienters/SDK-PhingersTF_Component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-PhingersTF_Component-SPM.git
</code></pre>

## Permissions

In the client application where the components will be integrated, the following item must be added to the **Info.plist**:

```
Camera access must be allowed (Privacy - Camera Usage Description)
```

## Info.plist Configuration (KMP widget)

{% hint style="warning" %}
**IMPORTANT:** The **Phingers** component uses a **KMP** widget with resource files. You must add the following key to the application's **Info.plist** to avoid a runtime crash (**EXC\_BAD\_ACCESS**).
{% endhint %}

```xml
<key>CADisableMinimumFrameDurationOnPhone</key>
<true/>
```

## Available controllers

<table data-header-hidden><thead><tr><th width="184.63671875"></th><th></th></tr></thead><tbody><tr><td><strong>Controller</strong></td><td><strong>Description</strong></td></tr><tr><td>PhingersController</td><td>Main fingerprint capture controller</td></tr></tbody></table>

## Simplified Launch

```swift
let controller = PhingersController(data: phingersConfigurationData, output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)

```

## Basic configuration <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

To launch the current component, create an object *PhingersConfigurationData* which will serve as the component controller's configuration.

The basic configuration required is as follows:

```swift
static var phingersConfiguration: PhingersConfigurationData{
   var configPhingers = PhingersConfigurationData()
   configPhingers.reticleOrientation = .LEFT
   configPhingers.fingerFilter = .SLAP
   return configPhingers
}
```

The available orientations are:

* LEFT
* RIGHT

The available filters are:

* SLAP
* ALL\_4\_FINGERS\_ONE\_BY\_ONE
* ALL\_5\_FINGERS\_ONE\_BY\_ONE
* INDEX\_FINGER
* MIDDLE\_FINGER
* RING\_FINGER
* LITTLE\_FINGER
* THUMB\_FINGER

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

The controllers return the required information in SdkResult format.

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

For errors, we have the common class *ErrorType:*

* PHG\_CANCEL\_BY\_USER: The user canceled the process.
* PHG\_COMPONENT\_LICENSE\_ERROR: The component license is invalid.
* PHG\_EMPTY\_LICENSE: The license String is empty.
* PHG\_INITIALIZATION\_ERROR: Initialization error.
* PHG\_INTERNAL\_ERROR: Internal error.
* PHG\_LOW\_QUALITY: Low image quality.
* PHG\_OPERATION\_NOT\_CREATED: There is no operation in progress.
* PHG\_CAMERA\_PERMISSION\_DENIED: The user denied permissions.
* PHG\_CAMERA\_FAILURE: Camera failure.
* PHG\_FINGERPRINT\_TEMPLATE\_IO\_ERROR: I/O failure
* PHG\_NO\_FINGERS\_DETECTED: Fingerprint detection error
* PHG\_TIMEOUT: Process timeout.

### Successful execution response - *data* <a href="#id-72-recepcion-de-ejecucion-correcta-data" id="id-72-recepcion-de-ejecucion-correcta-data"></a>

In the *data*part, we will have the *PhingersResult*.

The *data* field is variable and depends on which component returned the result. For this component, the returned fields are as follows:

#### **Fingers**

**position**

Returns an integer representing the captured item. This value is set according to the NIST\_POS\_CODE instructions.

**displayImage**

Contains the processed image.

**wsq**

The fingerprint in WSQ format.

**minutiaesNumber**

Returns the number of minutiae found in the biometric capture.

**quality**

An integer representing the quality of the processed item.

**nistQuality**

An integer representing the quality of the processed item using NIST standards.

**nist2Quality**

An integer representing the quality of the processed item using an alternative version of NIST standards.

**livenessScore**

Contains a confidence indicator value for the capture.

**template**

Contains the generated template.

#### **SlapImages**

**position**

Returns an integer representing the captured item. This value is set according to the NIST\_POS\_CODE instructions.

**image**

Contains the processed image.

**livenessScore**

Contains a confidence indicator value for the capture.

## Advanced information

This section provides more information about the component.

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

To launch the current component, create an object *PhingersConfigurationData* which will serve as the component controller's configuration.

All the fields that make up this class are detailed below.

**reticleOrientation**

Configures which hand will be captured. The permitted values are:

* **LEFT**: Enables capture of the fingers on the **left**.
* **RIGHT**: Enables capture of the fingers on the **right**.

**fingerFilter**

Configures the fingerprint detection mode to be used during capture. The permitted values are:

* **INDEX\_FINGER**: Configures capture using the **index**.
* **MIDDLE\_FINGER**: Configures capture using the **middle**.
* **RING\_FINGER**: Configure capture using the **ring finger**.
* **LITTLE\_FINGER**: Configure capture using the **little finger**.
* **THUMB\_FINGER**: Configure capture using the **thumb**.
* **SLAP**: Configure capture of the **four** fingers in a single photo.
* **ALL\_4\_FINGERS\_ONE\_BY\_ONE**: Configure capture of the **four** fingers by taking one photo of each.
* **ALL\_5\_FINGERS\_ONE\_BY\_ONE**: Configure capture of the **five** fingers by taking one photo of each.

**templateType**

Specifies the template used to return the fingerprint in the result. The enumeration ***TemplateType*** has the following possible values:

* **ISO\_TEMPLATE**: This template refers to the **ISO/IEC 19794-4**.
* **NIST\_TEMPLATE**: This template refers to the NIST standard.
* **NIST\_TF\_TEMPLATE**: **This is the default value.** This template refers to a variant of the NIST standard that facilitates sample processing and evaluation.

**extractionTimeout**

Sets the maximum time allowed for reading.

**showPreviousTip**

Displays a screen before capture starts, with information about the process and a button to start it.

**showTutorial**

Indicates whether the component displays the tutorial screen. This screen intuitively explains how to perform the capture.

**vibrationEnabled**

If set to true, vibration is enabled for errors and when the Widget returns OK.

**showDiagnostic**

Show diagnostic screens at the end of the process.

**livenessThreshold**

Configures the **Liveness** threshold for the fingerprint detector. Replaces the former single parameter **`threshold`** (since **2.8.1**). **Default value: 0.9.**

**detectorThreshold**

Configures the **fingerprint detector** . Replaces the former single parameter **`threshold`** (since **2.8.1**). **Default value: 0.9.**

{% hint style="warning" %}
In versions **2.8.0** and earlier, there was a single parameter **`threshold`** (default **0.7**). When upgrading to **2.8.1**, replace it with **`livenessThreshold`** and **`detectorThreshold`** (default **0.9**).
{% endhint %}

**enableFlash**

Turns on the flash during capture. **Default value: `false`.** Since **2.8.1**, the flash can also be turned on automatically if the process detects **low light** in the image to improve the capture process, even if the parameter is set to `false`.

**showEllipses**

Draws an ellipse during capture when a possible fingerprint is detected.

**cropWidth & cropHeight**

Specifies a width and height for cropping the capture.

**showPreviousFingerSelector**

Specifies whether to display the "showPreviousFingerSelector" screen.

**fingerSelectorHandOrientation**

Specifies which hand options are displayed on the `PreviousFingerSelectorView`.

**fingerSelectorOptions**

Specifies which finger options are displayed on the `PreviousFingerSelectorView`.

## Component customization

In addition to the changes that can be made at the SDK level (explained in the document on *SDK Customization*), 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 overriding the values of the following keys in a **Localizable.strings**. Keys with the suffix ***\_alt*** contain the strings used in accessibility labels required for ***VoiceOver***.

```xml
<!-- Previous Tip -->
    <string name="phingers_widget_tip_title">Fingerprint Capture</string>
    <string name="phingers_widget_tip_message">Place your finger inside the marker</string>
    <string name="phingers_widget_tip_message_alt">Place your finger inside the outline</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">Instructional 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">Keep 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">Keep 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">Position your index finger in the frame. Move it 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">Position your index finger in the frame. Move it 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">Position your thumb in the frame. Move it 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 setting 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 removes 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 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">The capture timed out. Try again.</string>

    <!-- Dynamic finger hint (EN) -->
    <!-- %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 marker</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>
```

So, for example, to change the text “*Start*” for the key `phingers_widget_tip_button` for the language **es**, go to the file **Localizable.strings** in the folder **es.lproj** if it exists (otherwise, create it), and add:

`"phingers_widget_tip_button"="Start";`

If a message is not specified in the language file, it will be filled in with the default message.

## Animations

To modify the SDK's animations (Lottie), include animations with the same names in the application's Resources folder.

```
phingers_anim_left_finger
phingers_anim_left
phingers_anim_right_finger
phingers_anim_right
phingers_anim_thumb_right
phingers_anim_thumb_left
```
