> 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/ios-sdk/modulos/captura-facial.md).
# Face Capture - Selphi
## Introduction
Face Capture is performed through the **Selphi Component**.
This component is responsible for capturing a user's selfie and extracting their main facial features. It includes the following processes:
* Internal camera and permission management.
* Assistance during face capture.
* Generation of facial templates and the user's image.
In the section of [Simplified Launch](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) The steps required for the basic integration of the SDK are described. On this page, specific information for launching this component is detailed.
***
## Dependencies
To avoid conflicts and compatibility issues, if the project contains old versions of Facephi libraries (Widgets), they must be completely removed before installing the components of **SDKMobile**.
### CocoaPods
Facephi libraries are distributed remotely via dependency managers. On iOS, it is used **CocoaPods**. The dependencies **required** that must already have been installed beforehand (by adding them to the project's Podfile) are:
```swift
pod 'FPHISDKMainComponent', '~> $VERSION'
```
To install the component **Selphi**, add the corresponding dependency in the `Podfile` of the project, together with the mandatory dependencies of the SDK.
```swift
pod 'FPHISDKSelphiComponent', '~> $VERSION'
```
### Swift Package Manager (SPM)
If you use **SPM**, make sure the SDK's required dependencies are installed beforehand.
```sh
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```
To install the component **Selphi**, include it in the project's modules.
```swift
//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-Selphi_component-SPM.git
```
***
## Permissions
In the client application where the components are to be integrated, it is necessary to include the following item in the file **Info.plist**:
```
It is necessary to allow use of the camera (Privacy - Camera Usage Description)
```
## Available controllers
| **Controller** | **Description** |
| ------------------------- | ----------------------------------------------------- |
| SelphiController | Main Facial Recognition controller |
| RawTemplateController | Controller for generating a RawTemplate from an image |
| SignatureSelphiController | Controller for signing a process with a Capture |
***
## Simplified Launch
Once the SDK has been initialized and a new operation has been created, the component can be launched using any of its available controllers, depending on the required functionality.
```swift
let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
// Do whatever with the result
...
}, viewController: viewController)
SDKController.shared.launch(controller: controller)
```
***
## Receiving the result
The component launch returns a result in the format `SdkResult`, which includes:
* `selphiResult.finishStatus`
* `selphiResult.errorType`
* `selphiResult.data`
### Receiving errors
*finishStatus*: Indicates whether the operation completed successfully. Possible values:
FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR
*errorType*: Widget-specific errors.
In iOS, `errorType` is an `ErrorType` of the SDK. In a timeout, the Swift enum can be `.SDK_TIMEOUT`, `.SELPHI_TIMEOUT(LivenessDiagnostic?)` or, if interpolated directly, display names such as `SDK_TIMEOUT` or `SELPHI_TIMEOUT`. In iOS, there is no case `TIMEOUT` without a prefix.
To serialize the error, use:
```swift
sdkResult.errorType.toString(addComponentPrefix: "SPI_")
```
This returns `SPI_TIMEOUT` whether the enum is `SDK_TIMEOUT` and `SELPHI_TIMEOUT`.
#### Behavior on timeout
On a timeout, the result has:
* `finishStatus`: `STATUS_ERROR`
* `data`: `nil` (does not return a `SelphiResult`)
* `errorType`: `.SDK_TIMEOUT` or `.SELPHI_TIMEOUT(LivenessDiagnostic?)`
The case `SELPHI_TIMEOUT` retains, when available, the widget's liveness diagnostic. That information **do not** is part of `data`; it can only be read in iOS via pattern matching on `errorType`:
```swift
if case .SELPHI_TIMEOUT(let diagnostic) = sdkResult.errorType {
// diagnostic: LivenessDiagnostic? (puede ser nil)
}
```
If the timeout comes as `SDK_TIMEOUT`, it does not include liveness diagnostic. If it comes as `SELPHI_TIMEOUT`, the associated diagnostic can be `nil` when the timeout occurs through the Widget error path (`FWETimeout`) instead of the delegate `extractionTimeout()`.
For native iOS integrations, the serialized value should be treated as `SPI_TIMEOUT` (includes both `SDK_TIMEOUT` and `SELPHI_TIMEOUT` of the enum).
If `showDiagnostic` is active, the callback `output` is not invoked at the moment of the timeout: the diagnostic screen is shown first and the result is delivered when Close is pressed. With `showDiagnostic` disabled, the callback runs immediately.
The following list includes errors from the cross-platform contract; some do not occur in iOS.
* 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 rejected the permissions.
* SPI\_CANCEL\_BY\_USER: The user has canceled the process.
* SPI\_COMPONENT\_LICENSE\_ERROR: The component License is not correct.
* SPI\_EMPTY\_LICENSE: The License String is empty.
* SPI\_EXTRACTION\_LICENSE\_ERROR: Widget: License error.
* SPI\_ACTIVE\_LIVENESS\_ERROR: Widget: Error in the Active Liveness 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\_FILE\_NOT\_FOUND: The resource zip was not found.
* SPI\_SETTINGS\_PERMISSION\_ERROR: Widget: Permission error.
* SPI\_TEMPLATE\_ERROR:
* SPI\_TIMEOUT: Timeout in the process (`SDK_TIMEOUT` or `SELPHI_TIMEOUT` of the enum).
* SPI\_UNEXPECTED\_CAPTURE\_ERROR: Widget: Capture error.
* SPI\_UNKNOWN\_ERROR: Unknown error.
* SPI\_WIDGET\_RESULT\_DATA\_ERROR: Error in the widget output data.
### Successful execution response - data
The content of the field `data` depends on the launched component. In **Selphi**, it may include:
* `template`\
Facial template generated after extraction. Valid for **authentication**.
* `templateRaw`\
Raw facial template generated after the extraction process. Valid for **authentication**.
* `bestImageData`\
Best captured image, in byte array format and original size. Valid for **liveness**.
* `bestImageCroppedData`\
Cropped image centered on the face. Recommended as the user's avatar.
* `qrData`\
Information obtained from QR reading in format `String`.
* `bestImageTokenized`\
Encrypted image resulting from the process. Valid for **liveness**.
***
## Advanced information
### Additional controllers
**SignatureSelphiController**\
Works the same as `SelphiController`, but generates a process signature file.
**RawTemplateController**\
Allows generating a `RawTemplate` from an image (`bitmap`).
Usage example:
```swift
let controller = RawTemplateController(
base64: bestImageData.base64EncodedString(),
output: { sdkResult in
guard let result = sdkResult.data else {return}
print(result.base64EncodedString())
})
SDKController.shared.launchMethod(controller: controller)
```
or
```swift
let controller = RawTemplateController(
data: bestImageData,
output: { sdkResult in
guard let result = sdkResult.data else {return}
print(result.base64EncodedString())
})
SDKController.shared.launchMethod(controller: controller)
```
### Advanced configuration
To launch the component, an object must be created `SelphiConfigurationData`.\
This object defines the component's behavior and configuration.
#### Available parameters
* `resourcesPath`\
Relative path to the folder `Resources` where the resource file is located.
* `showTutorial`\
Shows the tutorial before capture.
* `showDiagnostic`\
Displays a diagnostic screen in case of error or insufficient permissions.
* `showResultAfterCapture`\
Shows the captured image and allows repeating the process.
* `debug`\
Enables debug mode.
* `fullscreen`\
Prioritizes full-screen display.
* `cropPercent`\
Face crop percentage.
* `livenessMode`\
Liveness detection mode:
* `NONE`
* `PASSIVE`
* `MOVE`
* `stabilizationMode`\
Forces the user to keep their head steady before starting the process.
* `templateRawOptimized`\
Indicates whether the `templateRaw` should be optimized.
* `qrMode`\
Enables or disables QR reading.
* `videoFilename`\
Absolute path to record the process video.
* `cameraFlashEnabled`\
Enables the camera flash.
* `translationsContent`\
Advanced text configuration via XML.
* `viewsContent`\
Advanced view configuration via XML.
* `vibrationEnabled`\
Enables vibration on errors and successful results.
* `animateDismiss`\
Indicates whether the SDK closing is animated when the process finishes. Available from **2.8.1**.
### Component customization
In addition to the changes that can be made at the SDK level (explained in *SDK Customization*), this component allows its own customization.
#### Texts
Texts are customized by overriding keys in `Localizable.strings`, within the folder `Resources`.
The keys with suffix `_alt` are used for accessibility (VoiceOver).
Text modification example **START** for `es`:
You need to go to the file **Localizable.strings** of the folder **es.lproj** (if this folder does not exist, it will need to be created).
```
"selphi_component_tip_button_message" = "EMPEZAR";
```
If a key is not defined, the default value will be used.
| **Name** | **Value** |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selphi\_component\_tutorial\_message\_1 | Place your face in the center and look straight at the camera. |
| selphi\_component\_tutorial\_message\_2 | Remove any object that covers your face. |
| selphi\_component\_tutorial\_message\_3 | Look for a well-lit environment, with no shadows on your face. |
| selphi\_component\_tip\_message | Place your face in the center of the circle |
| selphi\_component\_tip\_title | Facial Recognition |
| selphi\_component\_tip\_button | START |
| selphi\_component\_tip\_button\_alt | Start face capture |
| selphi\_component\_tip\_anim\_alt | A person shows their face inside the circle and the app takes a photo. |
| selphi\_component\_tip\_move\_anim\_alt | Animation of a mobile phone screen with the front camera activated. A circle appears in the center of the screen. A person shows their face inside the circle, moves it slightly to one side and the app takes a photo. |
| selphi\_component\_tutorial\_1\_anim\_alt | The photo is taken when the person is centered. |
| selphi\_component\_tutorial\_2\_anim\_alt | A person removes 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\_tip\_move\_message | Place your face in the center of the circle and follow the instructions. |
| selphi\_component\_timeout\_title | Time exceeded |
| selphi\_component\_timeout\_desc | We were unable to identify you. Try again |
#### Animations
The animations for the previous tip and tutorials are **Lottie (.json)**.
To replace them:
* Add the file to the folder `Resources`.
* Keep exactly the same file name.
If they are not replaced, the default animations will be shown.
| Name | Function |
|---|
| selphi_anim_tip | LivenessMode animation: None, Passive |
| selphi_anim_tip_move | LivenessMode animation: Move |
| selphi_anim_tuto_1 | First tutorial animation |
| selphi_anim_tuto_2 | Second tutorial animation |
| selphi_anim_tuto_3 | Third tutorial animation |