Fingerprint Capture - Phingers

Introduction

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 the steps required for the basic SDK Integration are described. This page adds specific information for using this component.

---

Dependency

The component's specific dependency is:

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

---

Available controllers

Controller	Description
PhingersTFController	Main fingerprint capture controller
FPhingersTFController	Main fingerprint capture controller for flow integrations

Simplified Launch

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:

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:

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

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

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

---

Error handling

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

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

Advanced component configuration

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

Besides the changes that can be made at SDK level (which are explained in the document of SDK Customization), this specific component allows its interface to be modified.

Texts

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

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

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.

---