Fingerprint Capture - Phingers

This component requires a minimum iOS version of iOS13

Introduction

The Component covered in the current document is called Phingers Component. It is responsible for capturing the user's fingerprints and the subsequent extraction of the fingerprint templates. Its main functionalities are as follows:

• Two operating modes: extraction of the four fingers of the hand (except the thumb), or extraction of only the thumb.

• Internal camera management.

• Permission management.

• Built-in liveness detection.

• Assistant in the fingerprint capture processes.

• Generation of templates with fingerprint features, images, and scores.

In the section of Simplified Launch the steps necessary for the basic integration of the SDK are detailed. In this section, information is added for 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 the Facephi libraries (Widgets), these must be completely removed before installing the components of the SDKMobile.

CocoaPods

pod 'FPHISDKMainComponent', '~> $VERSION'

• To install the current component, the following entry must be included in the application's Podfile:

pod 'FPHISDKPhingersTFComponent', '~> $VERSION'

• Once the dependencies are installed, the different functionalities of the component can be used.

SPM

• The mandatory dependencies that must have been installed previously are:

//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
[email protected]:facephi-clienters/SDK-SdkPackage-SPM.git

• To install the Selphid component, the following must be included in the project's modules:

//HTTPS
https://github.com/facephi-clienters/SDK-PhingersTF_Component-SPM.git
//SSH
[email protected]:facephi-clienters/SDK-PhingersTF_Component-SPM.git

Permissions

In the client application where the components are to be integrated, it is necessary to include the following item in the file Info.plist:

It is necessary to allow use of the camera (Privacy - Camera Usage Description)

Available controllers

Controller	Description
PhingersController	Main fingerprint capture controller

Simplified Launch

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

Basic configuration

To launch the current component, an object must be created PhingersConfigurationData which will be the configuration of the component controller.

The basic configuration required for it is as follows:

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

The different orientations are:

• LEFT

• RIGHT

The different 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

The controllers will return the necessary information in SdkResult format.

Receiving errors

In the error section, we will have the common class ErrorType:

• PHG_CANCEL_BY_USER: The user has canceled the process.

• PHG_COMPONENT_LICENSE_ERROR: The component license is not correct.

• 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 has denied the permissions.

• PHG_CAMERA_FAILURE: Camera failure.

• PHG_FINGERPRINT_TEMPLATE_IO_ERROR: IO failure

• PHG_NO_FINGERS_DETECTED: Fingerprint detection error

• PHG_TIMEOUT: Timeout in the process.

Successful execution response - data

In the part of data, we will have the class PhingersResult.

The field data is variable and will depend on which component returned the result. In the case of this component, the returned fields are as follows:

Fingers

position

Returns an integer that represents the captured item. This value is set according to the instructions of NIST_POS_CODE.

displayImage

Contains the processed image.

wsq

The fingerprint in WSQ format.

minutiaesNumber

Returns the number of minutiae found in the biometric capture.

quality

Integer representing the quality of the processed item.

nistQuality

Integer representing the quality of the processed item using NIST standards.

nist2Quality

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

livenessScore

Contains a value of the confidence indicator in the capture.

template

Contains the generated template.

SlapImages

position

Returns an integer that represents the captured item. This value is set according to the instructions of NIST_POS_CODE.

image

Contains the processed image.

livenessScore

Contains a value of the confidence indicator in the capture.

Advanced information

This section expands the component information.

Advanced component configuration

To launch the current component, an object must be created PhingersConfigurationData which will be the configuration of the component controller.

Below are all the fields that are part of this class.

reticleOrientation

Configures which hand will be captured. Allowed values are:

• LEFT: Activates capture of the fingers of the left.

• RIGHT: Activates capture of the fingers of the right.

fingerFilter

Configures the fingerprint detection mode that will be used during capture. Allowed values are:

• INDEX_FINGER: Configures capture with the index.

• MIDDLE_FINGER: Configures capture with the middle.

• RING_FINGER: Configures capture with the ring.

• LITTLE_FINGER: Configures capture with the little.

• THUMB_FINGER: Configures capture with the thumb.

• SLAP: Configures the capture of the four fingers in a single photo.

• ALL_4_FINGERS_ONE_BY_ONE: Configures the capture of the four fingers taking one photo for each of them.

• ALL_5_FINGERS_ONE_BY_ONE: Configures the capture of the five fingers taking one photo for each of them.

templateType

Specifies the template with which the fingerprint will be returned in the result. The enumerated TemplateType has the following possible values:

• ISO_TEMPLATE: This template refers to the standard 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 processing and evaluation of the sample.

extractionTimeout

Sets the maximum time allowed for reading.

showPreviousTip

Shows a screen before capture launch with information about the process to be carried out and a button to launch it.

showTutorial

Indicates whether the component enables the tutorial screen. In this view, how capture is performed is explained intuitively.

vibrationEnabled

If set to true, vibration is activated on errors and if the widget response is OK.

showDiagnostic

Show diagnostic screens at the end of the process.

livenessThreshold

Configures the liveness threshold of the fingerprint detector. Replaces the old single parameter threshold (from 2.8.1). Default value: 0.9.

detectorThreshold

Configures the threshold of the detector of fingerprints. Replaces the old single parameter threshold (from 2.8.1). Default value: 0.9.

In versions 2.8.0 and earlier there was a single parameter threshold (default 0.7). When updating to 2.8.1, replace it with livenessThreshold and detectorThreshold (default 0.9).

enableFlash

Activates the flash during capture. Default value: false. From 2.8.1, the flash can also be activated 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

Indicates a width and height to perform a crop of the capture.

showPreviousFingerSelector

Indicates whether the "showPreviousFingerSelector" screen is shown or not.

fingerSelectorHandOrientation

Indicates which hand options will be shown on the screen PreviousFingerSelectorView.

fingerSelectorOptions

Indicates which finger options will be shown on the screen PreviousFingerSelectorView.

Component customization

Apart from the changes that can be made at the SDK level (which are explained in the document of SDK Customization), this particular component allows modification of its interface.

Texts

The texts can be customized by overriding the value of the following keys in a Localizable.strings. The keys containing the suffix _alt are the literals used in the accessibility labels necessary for the functionality of VoiceOver.

<!-- 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">See 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">Put your fingers together. Move your hand closer or farther 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">Put your fingers together. Move your hand closer or farther 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 box. Move the finger closer or farther 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 box. Move the finger closer or farther 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 box. Move the finger closer or farther 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 any element covering your face.</string>
    <string name="phingers_widget_tutorial_message_3">Find 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 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 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 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">Place your finger vertically</string>
    <string name="phingers_widget_camera_status_too_few">The finger has not been 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 left-hand finger</string>
    <string name="phingers_widget_camera_status_wrong_hand_right">You must place the right-hand finger</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 exceeded the time limit. 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>

Thus, if you want to modify for example the text “Start” of the key phingers_widget_tip_button for the language es, you must go to the file Localizable.strings of the folder es.lproj if it exists (if not, it must be created) and there, add:

"phingers_widget_tip_button"="Start";

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

Animations

If you want to modify the SDK animations (lottie), you must include the animations with the same name 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