Skip to main content
Version: 2.6.X

Facial Capture with IAD

Differences with Selphi Component

The Selphi IAD Component is functionally equivalent to the standard Selphi Component, incorporating additional security controls aimed at detecting 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 iad field in the result (SelphiResult), which contains the anti-fraud analysis information prepared for server verification.

To use it, a new licence is required and the standard component dependency must be replaced with:

implementation ‘com.facephi.androidsdk:selphi_iad_component:$version’

This component requires a new licence and has two important restrictions:

  • Devices with a minimum of 3 GB of RAM.
  • Front camera with 1920x1080 or higher preview.

1. Introduction​

Facial capture with video injection attack detection is performed with the Selphi IAD Component.

This component is responsible for capturing a selfie of the user and extracting their most relevant facial features, incorporating a set of preventive security controls aimed at detecting untrustworthy environments. Its main processes are:

  • Internal camera and permission management.
  • Detection of impersonation attempts using manipulated videos or camera feeds.
  • Guided assistance during the user’s facial capture process.
  • Generation of facial templates and the user image.

Refer to the Quickstart section for the basic SDK integration steps. This guide adds information specific to launching this component.

2. Dependency​

The component-specific dependency is:

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

3. Available Controllers​

ControllerDescription
SelphiControllerMain facial recognition controller
RawTemplateControllerController to generate a RawTemplate from an image
SignatureSelphiControllerController to create a signature file in the platform

4. Quick Launch​

Once the SDK is initialized and a new operation has been created, launch the component by using any of its controllers.

Facial capture launch:

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

5. Basic Configuration​

To launch the component, create a SelphiConfigurationData object with the following fields:

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

Available livenessMode values:

  • SelphiFaceLivenessMode.NONE
  • SelphiFaceLivenessMode.PASSIVE
  • SelphiFaceLivenessMode.MOVE

6. Receiving the Result​

The launch returns an SdkResult. Differentiate between success and error (the result data will include the “iad” field with the information obtained; see section 6.2.):

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

6.1 Handling Errors​

Errors are returned as a SelphiError object. Possible values include:

  • SPI_ACTIVITY_RESULT_ERROR: The result of the activity is incorrect.
  • SPI_ACTIVITY_RESULT_MSG_ERROR: The result of the activity received in the 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: User has rejected permissions.
  • SPI_CANCEL_BY_USER: The user has cancelled the process.
  • SPI_CANCEL_LAUNCH: A general cancellation of the SDK has been done.
  • SPI_COMPONENT_LICENSE_ERROR: The component license is not correct.
  • SPI_CONTROL_NOT_INITIALIZATED_ERROR: Widget: Initialisation error.
  • SPI_EMPTY_LICENSE: The license string is empty.
  • SPI_EXTRACTION_LICENSE_ERROR: Widget: License error.
  • SPI_FETCH_DATA_ERROR: Error in the collection of the result.
  • SPI_FLOW_ERROR: Error in the flow process.
  • SPI_HARDWARE_ERROR: Widget: Hardware error.
  • SPI_INITIALIZATION_ERROR: Initialisation error.
  • SPI_MANAGER_NOT_INITIALIZED: Managers are null.
  • SPI_NO_DATA_ERROR: Input data is null.
  • SPI_OPERATION_NOT_CREATED: No operation is in progress.
  • SPI_RESOURCES_NOT_FOUND: Resource zip not found.
  • SPI_SETTINGS_PERMISSION_ERROR: Widget: Permission error.
  • SPI_TEMPLATE_ERROR:
  • SPI_TIMEOUT: Timeout in process.
  • SPI_UNEXPECTED_CAPTURE_ERROR: Widget: Capture error.
  • SPI_UNKNOWN_ERROR: Unknown error.
  • SPI_WIDGET_RESULT_DATA_ERROR: Error in widget output data.

6.2 Handling Success – data​

On success (SdkResult.Success), you receive a SelphiResult object. Images are returned as SdkImage; extract the bitmap via image.bitmap. To convert to Base64:

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

Returned fields in SelphiResult:

6.2.1 templateRaw​

Raw template generated after extraction, valid for matching.

6.2.2 template​

Processed template generated after extraction, valid for matching.

6.2.3 bestImage​

Best full-size image from the authentication process, valid for liveness checks.

6.2.4 bestImageCropped​

Cropped image centered on the user’s face, derived from bestImage.

6.2.5 logImages​

List of the top 5 captured images (returned if logImages flag is enabled).

6.2.6 bestImageTokenized​

Encrypted best image from the liveness process.

6.2.7 livenessDiagnostic​

Information about the verification process that confirms that the person is physically present and real.

6.2.8 iad​

Information obtained from the analysis of video injection attacks prepared for submission to the verification service.

7. Advanced Information​

This section provides extended details for this component.

7.1 Additional Controllers​

7.1.1 SignatureSelphiController​

Used like SelphiController but generates a signature file on the platform.

7.1.2 RawTemplateController​

Generates a RawTemplate from a given image (SdkImage).

Example:

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

7.2 Advanced Component Configuration​

Create a SelphiConfigurationData object with all available fields:

7.2.0 debug​

Enables debug mode.

7.2.1 resourcesPath​

Name of the zip file in assets (ex. resources-selphi-2-0.zip).

7.2.2 cropPercent​

Percentage to crop around the face; higher values yield a tighter crop.

7.2.3 cropImageDebug​

Enables debug view for crop percentage.

7.2.4 showResultAfterCapture​

Whether to show a screen with the captured image for user review.

7.2.5 showTutorial​

Enables tutorial screen explaining the capture process.

7.2.6 livenessMode​

Sets the liveness detection mode:

  • NONE
  • PASSIVE
  • MOVE

7.2.7 stabilizationMode​

Requires the user to hold head steady and forward before starting.

7.2.8 cameraFlashEnabled​

Enables device camera flash.

7.2.9 locale​

Forces widget to use a specific locale (e.g. en, en_US).

7.2.10 fullscreen​

Displays the widget full-screen if supported.

7.2.11 templateRawOptimized​

Optimizes templateRaw if true.

7.2.12 qrMode​

Enables QR scanning before authentication.

7.2.13 videoFilename​

Absolute path for recording capture video; the app must handle permissions.

7.2.14 viewsContent​

Custom XML layout string for widget views.

7.2.15 showDiagnostic​

Shows diagnostic screens at the end.

7.2.16 logImages​

Returns top 5 images when enabled.

7.2.17 showPreviousTip​

Shows a pre-capture tip screen with launch info.

7.2.18 extractionDuration​

Duration of the facial extraction process.

7.2.19 cameraPreferred​

Preferred camera (FRONT or BACK).

7.2.20 vibrationEnabled​

Enables vibration feedback at process end.

7.2.21 moveSuccessfulAttempts​

Number of retries for successful MOVE liveness (default 1).

7.2.22 moveFailedAttempts​

Number of retries for failed MOVE liveness (default 2).

8. Component Customization​

Beyond SDK-wide settings (Advanced Settings), this component allows:

8.1 Texts​

Override default strings by providing an XML in your app:

    <!-- Diagnostic -->
    <string name="selphi_component_timeout_title">Time exceeded</string>
    <string name="selphi_component_timeout_desc">We were unable to identify you. Please try again.</string>
    <string name="selphi_component_internal_error_title">There was a technical problem</string>
    <string name="selphi_component_internal_error_desc">We apologize. The capture could not be made</string>
    <!-- Previous Tip -->
    <string name="selphi_component_tip_message">Place your face in the centre of the circle</string>
    <string name="selphi_component_tip_message_alt">Place your face in the centre of the circle</string>
    <string name="selphi_component_tip_anim_alt">A person shows their face inside the circle and the application takes a photo of them.</string>
    <string name="selphi_component_tip_title">Facial recognition</string>
    <string name="selphi_component_tip_button">Start</string>
    <string name="selphi_component_tip_button_alt">Start face capture</string>
    <string name="selphi_component_tip_move_message">Put your face in the center of the circle and follow the directions.</string>
    <string name="selphi_component_tip_move_message_alt">Put your face in the center of the circle and follow the directions.</string>
    <string name="selphi_component_tip_move_anim_alt">A person shows their face inside the circle, moves it slightly to the side and the application takes a photo.</string>
    <string name="selphi_component_tip_move_title">Facial recognition</string>
    <string name="selphi_component_tip_move_button">Start</string>
    <string name="selphi_component_qr_tip_title">Scan QR Code</string>
    <string name="selphi_component_qr_tip_message">Focus the QR code inside the box</string>
    <string name="selphi_component_qr_tip_anim_alt">Focus the QR code inside the box</string>
    <string name="selphi_component_qr_tip_button">Start</string>
    <string name="selphi_component_tip_close_button_alt">Back</string>
    <string name="selphi_component_tip_info_button_alt">Show advices</string>
    <!-- Tutorial -->
    <string name="selphi_component_tutorial_message_1">Place your face in the center and face the camera.</string>
    <string name="selphi_component_tutorial_message_2">Remove any items covering your face.</string>
    <string name="selphi_component_tutorial_message_3">Look for a well-lit environment with no shadows on your face.</string>
    <string name="selphi_component_tutorial_1_anim_alt">The photo is taken when the person is in the centre.</string>
    <string name="selphi_component_tutorial_2_anim_alt">A person takes off his sunglasses and removes his hair from his eyes.</string>
    <string name="selphi_component_tutorial_3_anim_alt">The image appears dark and a person switches on the light.</string>
    <string name="selphi_component_tutorial_close_button_alt">Back to previous tutorial</string>

8.2 Animations​

Override Lottie animations by placing JSON files 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