Face Capture with IAD - Selphi

Differences with standard face capture

The Selphi IAD Component is functionally equivalent to the Selphi Component standard one, incorporating additional security controls aimed at the detection of video injection attacks and untrusted capture environments.

The integration, configuration, and usage flow of the component are the same. The main functional difference is the inclusion of the field iad in the result (SelphiResult), which contains the anti-fraud analysis information prepared for server-side verification.

To use it, a new license is required and the dependency of the standard component must be replaced by:

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

This component has two important restrictions:

• Devices with minimum 3 GB of RAM.

• Front camera with a preview of 1920x1080 or higher.

Introduction

Face Capture with Injection Attack Detection for video injection attacks is performed through the Selphi IAD Component.

This component is responsible for capturing a user's selfie and extracting its most relevant facial features, incorporating a set of preventive security controls designed to detect untrusted environments. During the process, the following steps are performed, among others:

• Internal management of cameras and permissions.

• Detection of impersonation attempts using videos or manipulated camera sources.

• Guided assistance during Face Capture.

• Generation of biometric templates and user images.

In the section Simplified Launch the basic steps for SDK integration are described. This page details the specific information needed to launch and configure this component.

---

Dependency

The component's specific dependency is:

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

---

Available controllers

This component includes several controllers, each aimed at a specific functionality.

Controller	Description
SelphiController	Main controller of Facial Recognition
RawTemplateController	Generation of a RawTemplate from an image
SignatureSelphiController	Signing of a process using a face capture

---

Simplified Launch

Once the SDK has been started and a new operation created, the component can be launched using any of its controllers.

val response = SDKController.launch(
    SelphiController(SelphiConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("Selphi: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

---

Basic configuration

To launch the component it is necessary to create an object SelphiConfigurationData, which defines the widget behavior.

SelphiConfigurationData(
  resourcesPath = "resources_file.zip",
  livenessMode = SelphiFaceLivenessMode.NONE
)

The component allows the following liveness detection modes:

• SelphiFaceLivenessMode.NONE

• SelphiFaceLivenessMode.PASSIVE

• SelphiFaceLivenessMode.MOVE

---

Result reception

The launch result is returned as an object SdkResult, which may indicate a successful result or an error (the result data will contain the field carrying the information associated with the IAD Successful result received - data)

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

Error handling

Errors will be returned as a 'SelphiError' object.

List of errors:

• SPI_ACTIVITY_RESULT_ERROR: The activity result is incorrect.

• SPI_ACTIVITY_RESULT_MSG_ERROR: The activity result received in msg is incorrect.

• SPI_APPLICATION_CONTEXT_ERROR: The required application context is null.

• SPI_BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Incorrect extractor configuration.

• SPI_CAMERA_PERMISSION_DENIED: The user has denied the permissions.

• SPI_CANCEL_BY_USER: The user has canceled the process.

• SPI_CANCEL_LAUNCH: A general SDK cancellation has been performed.

• SPI_COMPONENT_LICENSE_ERROR: The component license is not correct.

• SPI_CONTROL_NOT_INITIALIZATED_ERROR: Widget: Initialization error.

• SPI_EMPTY_LICENSE: The license string is empty.

• SPI_EXTRACTION_LICENSE_ERROR: Widget: License error.

• SPI_FETCH_DATA_ERROR: Error in fetching the result.

• SPI_FLOW_ERROR: Error in the Flow process.

• SPI_HARDWARE_ERROR: Widget: Hardware error.

• SPI_INITIALIZATION_ERROR: Initialization error.

• SPI_MANAGER_NOT_INITIALIZED: The managers are null.

• SPI_NO_DATA_ERROR: The input data are null.

• SPI_OPERATION_NOT_CREATED: There is no operation in progress.

• SPI_RESOURCES_NOT_FOUND: The resources zip has not been found.

• SPI_SETTINGS_PERMISSION_ERROR: Widget: Permission error.

• SPI_TEMPLATE_ERROR:

• SPI_TIMEOUT: Timeout in the process.

• SPI_UNEXPECTED_CAPTURE_ERROR: Widget: Capture error.

• SPI_UNKNOWN_ERROR: Unknown error.

• SPI_WIDGET_RESULT_DATA_ERROR: Error in the widget output data.

Reception of the successful result - data

When the result is correct (SdkResult.Success), an object is obtained SelphiResult.

The images are returned in format SdkImage. It is possible to access the bitmap through image.bitmap. To convert an image to Base64:

Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)

Returned fields

• templateRaw Raw template generated after extraction. Valid for matching processes.

• template Processed template after extraction. Valid for matching processes.

• bestImage Best captured image in original resolution. This image has the original size extracted from the camera. Valid for the liveness process.

• bestImageCropped Cropped image centered on the user's face. It is obtained from the bestImage.

• logImages List with the 5 best images (requires logImages = true).

• bestImageTokenized Best encrypted image of the process. Valid for the liveness process.

• bestImageTokenized Best encrypted image of the process. Valid for the liveness process.

• iad Information obtained in the analysis of video injection attacks prepared for sending to the verification service.

• livenessDiagnostic Verification process information that confirms that the person is physically present and real.

---

Advanced information

Additional Controllers

SignatureSelphiController

Works equivalently to SelphiController, with the difference that it generates a signature file on the platform.

RawTemplateController

Allows generating a RawTemplate from an image (Bitmap).

Usage example:

val result = SDKController.launch(
    RawTemplateController(SdkImage(image))
)
when (result) {
    is SdkResult.Error -> Napier.d("GenerateRaw: KO - ${result.error}")
    is SdkResult.Success -> result.data
}

Advanced configuration

The component behavior is defined by SelphiConfigurationData.

Available parameters

• resourcesPath Resource ZIP file name (located in assets). Example: “resources-selphi-2-0.zip“.

• cropPercent Face crop percentage. The higher the number, the greater the rectangle crop with respect to the face.

• cropImageDebug Displays crop debugging information.

• showResultAfterCapture Displays a confirmation screen after capture. The user is given the option to repeat the capture process if the image obtained is not correct.

• showTutorial Enables the tutorial screen. It intuitively explains how the capture is performed.

• livenessMode Liveness detection mode (NONE, PASSIVE, MOVE).

  • SelphiFaceLivenessMode.NONE: Indicates that photo detection mode should not be activated in authentication processes.

  • SelphiFaceLivenessMode.PASSIVE: Indicates that the passive liveness check is performed on the server, sending the corresponding “BestImage” or “TemplateRaw” for this purpose.

  • SelphiFaceLivenessMode.MOVE: Indicates that the liveness test is active, showing some instructions during capture, and returning the corresponding result of the process.

• stabilizationMode Forces the user to keep their head still before capture, facing forward and without moving their head.

• cameraFlashEnabled Activates the camera flash.

• fullscreen Prioritizes full-screen display.

• templateRawOptimized Optimizes the templateRaw generated.

• qrMode Enables QR reading prior to the authentication process.

• videoFilename Absolute path to record process video. The application is responsible for requesting the necessary permissions from the phone if required.

• viewsContent Advanced view configuration through XML. This property does not alter the content of the resource file.

• showDiagnostic Displays diagnostic screens.

• logImages Returns the 5 best captured images.

• showPreviousTip Displays an informative screen prior to capture.

• extractionDuration Duration of the extraction process.

• cameraPreferred Preferred camera (FRONT, BACK).

• vibrationEnabled Haptic feedback upon completion.

• moveSuccessfulAttempts Allowed retries in correct captures (default 1).

• moveFailedAttempts Allowed retries in incorrect captures (default 2).

---

Component Customization

Besides the changes that can be made at the SDK level (explained in SDK Customization), this component allows its own customization.

Texts

The texts can be customized by overriding the values in a strings XML file.

Name	Value
selphi_component_timeout_title	Timeout exceeded
selphi_component_timeout_desc	We have not been able to identify you. Try again
selphi_component_internal_error_title	There was a technical problem
selphi_component_internal_error_desc	We are sorry. The capture could not be completed
selphi_component_tip_message	Place your face in the center of the circle
selphi_component_tip_message_alt	Place your face in the center of the circle
selphi_component_tip_anim_alt	A person shows their face inside the circle and the app takes a photo.
selphi_component_tip_title	Facial Recognition
selphi_component_tip_button	START
selphi_component_tip_button_alt	Start face capture
selphi_component_tip_move_message	Place your face in the center of the circle and follow the instructions
selphi_component_tip_move_message_alt	Place your face in the center of the circle and follow the instructions
selphi_component_tip_move_anim_alt	A person shows their face inside the circle, moves it slightly to one side, and the app takes a photo.
selphi_component_tip_move_title	Facial Recognition
selphi_component_tip_move_button	START
selphi_component_qr_tip_title	Scan the QR code
selphi_component_qr_tip_message	Focus the QR code inside the frame
selphi_component_qr_tip_anim_alt	Focus the QR code inside the frame
selphi_component_qr_tip_button	Start
selphi_component_tip_close_button_alt	Back
selphi_component_tip_info_button_alt	See tips
selphi_component_tutorial_message_1	Place your face in the center and look straight at the camera.
selphi_component_tutorial_message_2	Remove any element covering your face.
selphi_component_tutorial_message_3	Look for a well-lit environment, without shadows on your face.
selphi_component_tutorial_1_anim_alt	The photo is taken when the person is in the center.
selphi_component_tutorial_2_anim_alt	A person takes off their sunglasses and moves their hair away from their eyes.
selphi_component_tutorial_3_anim_alt	The image appears dark and a person turns on the light.
selphi_component_tutorial_close_button_alt	Back to previous tutorial

Animations

Lottie animations can be overridden by adding files with the same name in res/raw/.

selphi_anim_prev_tip.json
selphi_anim_prev_tip_move.json
selphi_anim_tuto_m_1.json
selphi_anim_tuto_m_2.json
selphi_anim_tuto_m_3.json