For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:


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:

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.


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:

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.

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:

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


Last updated