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

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.LEFT

  • CaptureOrientation.RIGHT

Finger filters

Lets you specify 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


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