> 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 <a href="#id-1-introduccion" id="id-1-introduccion"></a>

Face capture is performed using the **Selphi Component**.

This component captures a selfie of the user and extracts their most relevant facial features. The process includes, among other things, the following steps:

* Internal management of cameras and permissions.
* Guided assistance during Face Capture.
* Generation of biometric templates and user images.

The [Simplified Launch](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) section describes the basic steps for integrating the SDK. This page details the specific information required to launch and configure this component.

***

## Dependency <a href="#id-2-dependencia" id="id-2-dependencia"></a>

The component-specific dependency is:

```kotlin
implementation "com.facephi.androidsdk:selphi_component:$version"
```

***

## Available Controllers

This component includes several controllers, each designed for a specific function.

| Controller                  | Description                                 |
| --------------------------- | ------------------------------------------- |
| `SelphiController`          | Main Facial Recognition controller          |
| `RawTemplateController`     | Generation of a `RawTemplate` from an image |
| `SignatureSelphiController` | Signing a process using a Face Capture      |

***

## Simplified Launch <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

Once the SDK has been initialized 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 <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

To launch the component, you must create an object `SelphiConfigurationData`, which defines the widget's behavior.

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

The component supports the following liveness detection modes:

* `SelphiFaceLivenessMode.NONE`
* `SelphiFaceLivenessMode.PASSIVE`
* `SelphiFaceLivenessMode.MOVE`

***

## Receiving the result <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

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
}
```

### Receiving errors <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as a `SelphiError`.

List of errors:

* `MOVE_FAIL` (`SPI_205`): Widget: The active liveness check (`MOVE`) failed. Includes `livenessDiagnostic`.
* `ACTIVITY_RESULT_ERROR` (`SPI_212`): The activity result is incorrect.
* `ACTIVITY_RESULT_MSG_ERROR` (`SPI_213`): The activity result received in the msg is incorrect.
* `APPLICATION_CONTEXT_ERROR` (`SPI_214`): The required application context is null.
* `BAD_CONFIGURATION_ERROR` (`SPI_210`): Widget: Incorrect configuration.
* `BAD_EXTRACTOR_CONFIGURATION_ERROR` (`SPI_200`): Widget: Incorrect extractor configuration.
* `CAMERA_PERMISSION_DENIED` (`SPI_201`): The user denied the permissions.
* `CANCEL_BY_USER` (`SPI_000`): The user canceled the process. Includes `livenessDiagnostic`.
* `CANCEL_LAUNCH` (`SPI_007`): The SDK was canceled globally.
* `COMPONENT_LICENSE_ERROR` (`SPI_002`): The component license is incorrect.
* `CONTROL_NOT_INITIALIZED_ERROR` (`SPI_202`): Widget: Initialization error.
* `EMPTY_LICENSE` (`SPI_003`): The license string is empty.
* `EXTRACTION_LICENSE_ERROR` (`SPI_203`): Widget: License error.
* `FETCH_DATA_ERROR` (`SPI_216`): Error collecting the result.
* `FLOW_ERROR` (`SPI_250`): Error in the flow process.
* `FLOW_TRACKING_ERROR` (`SPI_241`): Error tracking the flow.
* `FLOW_VIDEO_RECORDING_ERROR` (`SPI_239`): Error recording video in the flow.
* `HARDWARE_ERROR` (`SPI_204`): Widget: Hardware error.
* `INITIALIZATION_ERROR` (`SPI_004`): Initialization error.
* `INTERNAL_ERROR` (`SPI_235`): Internal error.
* `MANAGER_NOT_INITIALIZED` (`SPI_217`): The managers are null.
* `NO_DATA_ERROR` (`SPI_005`): The input data is null.
* `OPERATION_NOT_CREATED` (`SPI_006`): No operation is in progress.
* `RESOURCES_FILE_NOT_FOUND` (`SPI_206`): The resources ZIP file was not found.
* `SETTINGS_PERMISSION_ERROR` (`SPI_207`): Widget: Permission error.
* `TEMPLATE_ERROR` (`SPI_208`): Error generating the template.
* `SELPHI_TIMEOUT` (`SPI_001`): Timeout during the process. Includes `livenessDiagnostic`.
* `TRACKING_STEP_ERROR` (`SPI_240`): Error during the tracking step.
* `UNEXPECTED_CAPTURE_ERROR` (`SPI_209`): Widget: Capture error.
* `UNKNOWN_ERROR` (`SPI_215`): Unknown error.
* `WIDGET_RESULT_DATA_ERROR` (`SPI_211`): Error in the widget output data.

### Receiving the successful result - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

When the result is successful (`SdkResult.Success`), a `SelphiResult`.

Images are returned in `SdkImage` format. You can access the bitmap using `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 generated after extraction. Valid for Matching processes.
* `bestImage`\
  Best image captured at the original resolution. This image has the original size captured by the camera. Valid for the Liveness process.
* `bestImageCropped`\
  Image cropped and centered on the user's face. Obtained from *bestImage*.
* `logImages`\
  List of the 5 best images (requires `logImages = true`).
* `bestImageTokenized`\
  Best encrypted image from the process. Valid for the Liveness process.
* `livenessDiagnostic`\
  Liveness check diagnostic (`LivenessDiagnostic`).
* `qrData`\
  Contents of the scanned QR Code (requires `qrMode = true`).
* `statistics`\
  Capture process statistics generated by the widget.

***

## Advanced information <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

### Additional Controllers <a href="#id-71-controladores-adicionales" id="id-71-controladores-adicionales"></a>

**SignatureSelphiController**

Works in the same way as `SelphiController`, except that it generates a signature file on the platform.

**RawTemplateController**

Allows you to generate 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's behavior is defined by `SelphiConfigurationData`.

#### Available parameters

* `resourcesPath`\
  Name of the resource ZIP file (located in `assets`). Example: “resources-selphi-2-0.zip“.

<div align="center"><figure><img src="https://865101184-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUo71Qbj6jZQDavjc0U5X%2Fuploads%2Fgit-blob-15ce71837bf3d4cff1f1509e00d49ef3c005ef31%2Fassets.png?alt=media" alt=""><figcaption></figcaption></figure></div>

* `cropPercent`\
  Face crop percentage. The higher the value, the more the rectangle is cropped around the face.
* `cropImageDebug`\
  Displays crop debugging information.
* `showResultAfterCapture`\
  Displays a confirmation screen after capture. The user can repeat the capture process if the image obtained is not correct.
* `showTutorial`\
  Enables the tutorial screen. It intuitively explains how to capture an image (enabled by default `true`).
* `livenessMode`\
  Liveness detection mode (`NONE`, `PASSIVE`, `MOVE`).
  * SelphiFaceLivenessMode.NONE: Indicates that photo detection mode should not be enabled during authentication processes.
  * SelphiFaceLivenessMode.PASSIVE: Indicates that the passive liveness check is performed on the server by sending the corresponding “BestImage” or “TemplateRaw”.
  * SelphiFaceLivenessMode.MOVE: Indicates that the liveness test is active, displaying instructions during capture and returning the corresponding process result.
* `stabilizationMode`\
  Requires the user to keep their head steady before capture, facing forward and without moving their head.
* `cameraFlashEnabled`\
  Enables the camera flash.
* `fullscreen`\
  Prioritizes full-screen display.
* `templateRawOptimized`\
  Optimizes the `templateRaw` generated.
* `qrMode`\
  Enables QR scanning before the authentication process.
* `cameraId`\
  Identifier of the camera to use (`Int`).
* `videoFilename`\
  Absolute path for recording video of the process. The application is responsible for requesting any necessary permissions from the phone, if required.
* `viewsContent`\
  Advanced view configuration using XML. This property does not alter the contents of the resource file.
* `translationsContent`\
  Advanced translation configuration.
* `showDiagnostic`\
  Displays diagnostic screens (default `true`).
* `logImages`\
  Returns the 5 best captured images.
* `showPreviousTip`\
  Displays an informational screen before capture (default `true`).
* `extractionDuration`\
  Duration of the extraction process (`SHORT`, `MEDIUM`, `LONG`).
* `cameraPreferred`\
  Preferred camera (`FRONT`, `BACK`). Default `FRONT`.
* `vibrationEnabled`\
  Vibration feedback upon completion (default `false`).
* `moveSuccessfulAttempts`\
  Allowed retries for successful captures (default 1).
* `moveFailedAttempts`\
  Allowed retries for unsuccessful captures (default 2).
* `params`\
  Map (`HashMap<String, String>`) of additional parameters passed directly to the widget.

***

## Customization of the component <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

In addition to the changes that can be made at the SDK level (explained in [SDK Customization](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this component can also be customized.

### Text <a href="#id-81-textos" id="id-81-textos"></a>

You can customize the text by overriding the values in an XML strings file.

| **Name**                                        | **Value**                                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| selphi\_component\_timeout\_title               | Timeout                                                                                                    |
| selphi\_component\_timeout\_desc                | We couldn't identify you. Please try again                                                                 |
| selphi\_component\_internal\_error\_title       | A technical problem occurred                                                                               |
| selphi\_component\_internal\_error\_desc        | We apologize. The capture couldn't be completed                                                            |
| selphi\_component\_tip\_message                 | Position your face in the center of the circle                                                             |
| selphi\_component\_tip\_message\_alt            | Position your face in the center of the circle                                                             |
| selphi\_component\_tip\_anim\_alt               | A person positions 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           | Position your face in the center of the circle and follow the instructions                                 |
| selphi\_component\_tip\_move\_message\_alt      | Position your face in the center of the circle and follow the instructions                                 |
| selphi\_component\_tip\_move\_anim\_alt         | A person positions 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             | Position the QR Code inside the frame                                                                      |
| selphi\_component\_qr\_tip\_anim\_alt           | Position 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       | View tips                                                                                                  |
| selphi\_component\_tutorial\_message\_1         | Position your face in the center and look straight at the camera.                                          |
| selphi\_component\_tutorial\_message\_2         | Remove anything covering your face.                                                                        |
| selphi\_component\_tutorial\_message\_3         | Find a well-lit place with no shadows on your face.                                                        |
| selphi\_component\_tutorial\_1\_anim\_alt       | The photo is taken when the person is centered.                                                            |
| 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 | Return to the previous tutorial                                                                            |

### Animations <a href="#id-82-animaciones" id="id-82-animaciones"></a>

Lottie animations can be overridden by adding files with the same name to `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
```
