> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-facial.md). # Face Capture - Selphi ## Introduction Face Capture is performed via the **Selphi Component**. This component is responsible for capturing a selfie from the user and extracting their most relevant facial features. During the process, the following steps are performed, among others: * Internal management of cameras and permissions. * Guided assistance during Face Capture. * Generation of biometric templates and user images. In the section [Simplified Launch](/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) 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: ```kotlin implementation "com.facephi.androidsdk:selphi_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. ```kotlin 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. ```kotlin 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 can indicate a successful result or an error. ```kotlin 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: ```kotlin 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. *** ## 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: ```kotlin 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](/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), 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 ```