Fingerprint Capture - Phingers
Introduction
Fingerprint capture is performed using the Phingers Component.
This component captures the user's fingerprints (fingerprints) and extracts the associated biometric templates. Its main processes are:
Internal camera and permission management.
Different capture modes: full hand (four fingers without the thumb), thumb, or individual fingers.
Integrated liveness detection.
Guided assistance during the capture process.
Generation of biometric templates, images, and quality metrics.
The Simplified Launch section describes the steps required for basic SDK integration. This page provides additional information specific to using this component.
Dependency
The component-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 is initialized and a new operation is created, you can launch the fingerprint capture component using its controller.
Launching fingerprint capture:
Basic Configuration
To launch the component, you need to create a PhingersConfigurationData object, which defines the capture process configuration.
The required basic configuration is as follows:
Capture orientation
Specifies the hand to capture:
CaptureOrientation.LEFTCaptureOrientation.RIGHT
Finger filters
Lets you specify which fingers are captured during the process:
FingerFilter.SLAPFingerFilter.ALL_4_FINGERS_ONE_BY_ONEFingerFilter.ALL_5_FINGERS_ONE_BY_ONEFingerFilter.INDEX_FINGERFingerFilter.MIDDLE_FINGERFingerFilter.RING_FINGERFingerFilter.LITTLE_FINGERFingerFilter.THUMB_FINGER
TemplateType options:
NIST_TEMPLATEISO_TEMPLATENIST_T5_TEMPLATE
Receiving the result
Launching the component returns a result in SdkResult format, which can indicate either a successful execution or an error.
Receiving errors
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 incorrect.
PHG_EMPTY_LICENSE: The license string is empty.
PHG_FETCH_DATA_ERROR: Error 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 data was received from the capture.
PHG_OPERATION_NOT_CREATED: There is no operation in progress.
PHG_PERMISSION_DENIED: The user 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 were detected.
PHG_UNIQUE_USER_ID_NOT_SPECIFIED: User not specified.
PHG_TIMEOUT: Timeout during the process.
PHG_FLOW_VIDEO_RECORDING_ERROR: Error recording video in the flow.
PHG_FLOW_TRACKING_ERROR: Tracking error in the flow.
PHG_TRACKING_STEP_ERROR: Error in the Tracking step.
Receiving the successful result - data
In case of success, the field data contains a PhingersResult.
Images are returned as SdkImage. You can 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 where applicable)livenessScore: Average liveness score (nullable)
recording: Optional local recording metadata when
videoRecordingEnabled=trueand the widget generates an MP4 file. It can benull.
FingerResponse
position: Finger position index
wsq: WSQ image (
ByteArray)displayImage: Display image (
ByteArray, PNG)minutiaesNumber: Number of minutiae detected
quality: Quality score
nistQuality: NIST quality score
nist2Quality: NIST2 quality score
template: Fingerprint template (
ByteArray)proprietaryQuality: Vendor-specific 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 to the generated video file.
fileName: Video file name.
mimeType: File MIME type. Defaults to
video/mp4.sizeBytes: File size in bytes, when reported by the widget.
durationMs: Video duration in milliseconds, when reported by the widget.
Advanced information
Advanced component configuration
The object PhingersConfigurationData lets you customize the component's behavior.
Available parameters
reticleOrientation
Sets the fingerprint detection mode and specifies which fingers will be detected during the process. The allowed values are:
LEFT: Enables capture of the left hand.
RIGHT: Enables capture of the right hand.
fingerFilter
Filter for selecting 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 detector during the fingerprint capture process. By default, it is set to true.
extractionTimeout
Sets an extraction time.
showPreviousTip
Displays a screen before capture starts with information about the process to be performed and a button to start it.
showTutorial
Indicates whether the component displays the tutorial screen. This screen intuitively explains how to capture the document.
showDiagnostic
Show diagnostic screens at the end of the process.
threshold
The parameter configures a captureQualityThreshold to define a quality threshold for capturing. The SDK limits this value to the range 0.0-1.0.
showEllipses
Displays the ellipses during capture.
cropWidth
Specifies a width for cropping the capture.
cropHeight
Specifies 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
Displays the finger selector before capture.
fingerSelectorHandOrientation
Defines which hand(s) are displayed in the selector (LEFT, RIGHT, BOTH).
fingerSelectorOptions
Defines the list of filters displayed in the selector. If it is empty, the SDK uses: ALL_4_FINGERS_ONE_BY_ONE, SLAP, INDEX_FINGER.
licenseKey
Optional license key passed to the Phingers TF widget when using activation or specific licensing.
product
Optional product associated with widget activation or licensing.
operationId
Optional operation identifier sent to the widget for traceability and capture association.
videoRecordingEnabled
Enables optional local recording during fingerprint capture. Defaults to false.
videoRecordingDirectoryPath
Optional destination directory for the generated video file.
videoRecordingFileName
Optional file name for the generated recording.
videoRecordingQuality
Local recording quality. Allowed values are LOW, MEDIUM and HIGH. Defaults to MEDIUM.
Component customization
In addition to the changes that can be made at the SDK level (which are explained in the document on SDK Customization), this particular component also allows its interface to be modified.
Text
The text can be customized by adding an XML resource file to the client application and overriding the default values.
Animations
The component animations are Lottie (JSON).
To replace them, add files with the same names to the res/raw/ folder of the app:
If no custom animations are included, the default animations will be used.
Last updated