Skip to main content
Version: SNAPSHOT 🚧

Selphi Component

0. SDK Mobile baseline requirements​

SDK Mobile is a set of libraries (Components) that offer a series of functionalities and services, allowing their integration into a Mobile application in a simple and fully scalable way. Certain components must be installed depending on the use case required. Its high level of modularity allows other new components to be added in the future without affecting those already integrated into the project.

For more information on the base configuration, go to the Getting Started section.

1. Introduction​

The Component discussed in the current document is called Selphi Component. It is responsible for capturing a selfie of the user and then extracting the most important facial features. Its main functionalities are the following:

  • Internal camera management.

  • Permission management.

  • Assistant in the process of capturing the user's face.

  • Generation of the templates with the facial characteristics and the image of the user's face for the liveness detection process.

2. Integration of the component​

Before integrating this component, it is recommended to read the documentation related to

Getting Started and follow the instructions in that document.

This section will explain step by step how to integrate the current component into an existing project.

2.1. Dependencies required for integration​

To avoid conflicts and compatibility problems, if you want to install the component in a project containing an old Facephi libraries (Widgets) version, these must be removed entirely before installing the SDKMobile components. Currently, FacePhi libraries are distributed remotely through different dependency managers. Mandatory dependencies that must be installed beforehand:

  • implementation "com.facephi.androidsdk:selphi_component:$sdk_selphi_component_version"

2.1. Resources zip file​

Table of sdk versions and associated resource versions (Found in the Resources section):

SDK versionSelphi resources version
2.0.25.13.1
2.0.35.13.4
2.1.05.14.1
2.1.15.14.2
2.1.25.15.0
2.2.05.16.1
2.2.15.16.2

3. Start a new operation​

When you want to perform a specific operation, in order to generate the associated information correctly in the platform, the newOperation command must first be executed.

ℹ️ This command must have been executed before launch. To learn more about how to start a new operation, it is recommended to consult the Start a new operation documentation, which details and explains what this process consists of.

4. Available controllers​

ControllerDescription
SelphiControllerFacial recognition main controller
RawTemplateControllerDriver to generate a RawTemplate from an image
SignatureSelphiControllerDriver to sign a process with a Capture

5. Component configuration​

To configure the current component, once it has been initialized, a SelphiConfigurationData object must be created and passed as a parameter to the SDKController when the component is launched.

The following section will show the fields that are part of this class and what each is used for.

5.1. Class SelphiConfigurationData​

5.1.0. debug​

Activation of the component's debugging mode.

5.1.1. resourcesPath​

Indicates the name of the resources in zip format. Example: "resources-selphi-2-0.zip".

This name will fetch the file from the assets path.

Image

5.1.2. cropPercent​

Allows you to change the percentage of cropping of the face. The higher the number, the more the rectangle is cropped concerning the face.

5.1.3. cropImageDebug​

Allows debug mode to check the percentage of cropping of the face.

5.1.4. showResultAfterCapture​

Indicates whether or not to display a screen with the captured image after the analysis process. This screen allows the user to repeat the capture process if the image obtained is incorrect.

5.1.5. showTutorial​

Indicates whether the widget activates the tutorial screen. This view intuitively explains how the capture is performed.

5.1.6. livenessMode​

Sets the liveness mode of the widget. Allowed values are:

  • SelphiFaceLivenessMode.NONE: Indicates that the photodetection mode should not be enabled in the authentication processes.

  • SelphiFaceLivenessMode.PASSIVE: Indicates that the passive liveness test is performed in the server, sending the corresponding "BestImage" or "TemplateRaw" for this purpose.

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

5.1.7. stabilizationMode​

Sets a stabilization mode before any authentication process in the widget. This mode forces the widget not to start any process if the user is not facing forward and not moving his head.

5.1.8. cameraFlashEnabled​

Indicates whether the device's camera flash is activated.

5.1.9 locale​

Forces the widget to use the language setting indicated by the locale parameter. This parameter accepts a language code (e.g. 'en') and a regional identification code (e.g. 'en_US'). If the widget resource file does not have a locale for the selected 'locale', its configuration will fall back to the default language.

5.1.10 fullscreen​

Indicates whether the view will prioritize for full-screen display if the system allows it.

5.1.11. templateRawOptimized​

Indicates whether the template (templateRaw) generated after the selfie should be optimized or not.

5.1.12. qrMode​

Sets whether or not to activate QR reading before the authentication process.

5.1.13 videoFilename​

Sets the absolute path to the filename where a video of the capture process will be recorded. The application is responsible for requesting the necessary permissions from the phone if that path requires additional permissions. The widget, by default, will not perform any recording process unless a file path is specified using this method.

5.1.14 viewsContent​

This advanced property allows, through a string in XML format, to configure the widget views.

Note: This property does not alter the content of the resource file.

5.1.15. showDiagnostic​

Display diagnostic screens at the end of the process

5.1.16. logImages​

When activated, a list of the 5 best images taken of the user is returned.

5.1.17. showPreviousTip​

Displays a pre-launch screen with information about the process to be performed and a launch button.

5.1.18. extractionDuration​

Duration of facial extraction process

5.1.19. cameraPreferred​

Selection of camera used for the process: FRONT, BACK

6. Component use​

Once the component has been started and a new operation has been created (section 3), the SDK components can be launched. There are two ways to launch the component:

  • [WITH TRACKING] This call allows to launch the functionality of the component, but internal events will be tracked to the tracking server:
val response = SDKController.launch(
    SelphiController(SelphiConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("Selphi: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
  • [WITHOUT TRACKING] This call allows to launch the functionality of the component, but no event will be tracked to the tracking server:
val response = SDKController.launchMethod(
    SelphiController(SelphiConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("Selphi: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

The launch method must be used by default. This method allows tracking if your component is enabled and will not be used when it is disabled (or the component is not installed).

On the other hand, the launchMethod method covers a particular case in which the integrator has tracking installed and activated but, in a certain flow within the application does not want to track information. In this case, this method is used to prevent this information from being sent to the platform.

7. Receipt of the result​

The controllers will return the required information in SdkResult format. -more details in the Android Mobile SDK's 6. Result return section-.

7.1. Receipt of errors​

On the error side, we will have the SelphiError class.

Error list:

  • ACTIVITY_RESULT_ERROR: The result of the activity is incorrect.
  • ACTIVITY_RESULT_MSG_ERROR: The result of the activity received in the msg is incorrect.
  • APPLICATION_CONTEXT_ERROR: The required application context is null.
  • BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Incorrect extractor configuration.
  • CAMERA_PERMISSION_DENIED: User has rejected permissions.
  • CANCEL_BY_USER: The user has cancelled the process.
  • CANCEL_LAUNCH: A general cancellation of the SDK has been done.
  • COMPONENT_LICENSE_ERROR: The component license is not correct.
  • CONTROL_NOT_INITIALIZATED_ERROR: Widget: Initialisation error.
  • EMPTY_LICENSE: The license string is empty.
  • EXTRACTION_LICENSE_ERROR: Widget: License error.
  • FETCH_DATA_ERROR: Error in the collection of the result.
  • FLOW_ERROR: Error in the flow process.
  • HARDWARE_ERROR: Widget: Hardware error.
  • INITIALIZATION_ERROR: Initialisation error.
  • MANAGER_NOT_INITIALIZED: Managers are null.
  • NO_DATA_ERROR: Input data is null.
  • OPERATION_NOT_CREATED: No operation is in progress.
  • RESOURCES_NOT_FOUND: Resource zip not found.
  • SETTINGS_PERMISSION_ERROR: Widget: Permission error.
  • TEMPLATE_ERROR:
  • TIMEOUT: Timeout in process.
  • UNEXPECTED_CAPTURE_ERROR: Widget: Capture error.
  • UNKNOWN_ERROR: Unknown error.
  • WIDGET_RESULT_DATA_ERROR: Error in widget output data.

7.2. Receipt of correct execution - data​

In the data part, we have the SelphiResult class.

The result returns the images in Bitmap format. It is possible to convert the images to Base64 as follows:

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

The data field is variable and will depend on which component has returned the result. In the case of this component, the fields returned are the following:

7.2.1 templateRaw​

Returns the raw template generated after the extraction process. Valid for the matching process.

7.2.2 template​

Returns the template that is generated after the extraction process. Valid for the matching process.

7.2.3 bestImage​

Returns the best image extracted from the authentication process in SdkImage format. This image is the original size image extracted from the camera. Valid for the liveness process.

7.2.4 bestImageCropped​

Returns a cropped image centred on the user's face in SdkImage format. This image is obtained from the bestImage. This image will be used as the characteristic image of the user who carried out the process as an avatar.

7.2.5 logImages​

List of the top 5 captured images returned if the "logImages" flag is set in the configuration.

7.2.6 bestImageTokenized​

Returns the best image tokenized. Valid for the liveness process.

8. Additional Controllers​

8.1. RawTemplateController​

Controller to generate a RawTemplate from an image (bitmap).

Example of use:

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

9. Customizing the component​

Apart from the changes that can be made at the SDK level (explained in the Getting Started document), this particular component allows the modification of specific texts.

9.1 Texts​

If you want to modify the SDK texts, you would have to include the following XML file in the client application and change the value of each String to the desired one.

    <string name="selphi_component_timeout_title">Time exceeded</string>
    <string name="selphi_component_timeout_desc">We apologize. The capture could not be made</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>
    <string name="selphi_component_tutorial_message">Stay still,\nwith your face\nin the center of the circle</string>
    <string name="selphi_component_tutorial_title">Take a selfie</string>
    <string name="selphi_component_tutorial_button">Continue</string>

9.2. Animations​

If you want to modify the animations (lottie) of the SDK you would have to include the animations with the same name in the res/raw/ folder of the application.

selphi_anim_tuto.json