> 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/sdks/sdk-mobile/ios-sdk/modulos/captura-facial.md).
# Captura facial - Selphi
## Introducción
La captura facial se realiza mediante el **Selphi Component**.
Este componente se encarga de capturar un selfie del usuario y extraer sus principales características faciales. Incluye los siguientes procesos:
* Gestión interna de cámaras y permisos.
* Asistencia durante la captura del rostro.
* Generación de plantillas faciales y de la imagen del usuario.
En el apartado de [Lanzamiento simplificado](/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) se describen los pasos necesarios para la integración básica del SDK. En esta página se detalla la información específica para lanzar este componente.
***
## Dependencias
Para evitar conflictos y problemas de compatibilidad, si el proyecto contiene versiones antiguas de librerías Facephi (Widgets), deben eliminarse por completo antes de instalar los componentes de **SDKMobile**.
### Cocoapods
Las librerías de Facephi se distribuyen de forma remota mediante gestores de dependencias. En iOS, se utiliza **CocoaPods**. Las dependencias **obligatorias** que deberán haberse instalado previamente (añadiéndolas en el fichero Podfile del proyecto) son:
```swift
pod 'FPHISDKMainComponent', '~> $VERSION'
```
Para instalar el componente **Selphi**, añade la dependencia correspondiente en el `Podfile` del proyecto, junto con las dependencias obligatorias del SDK.
```swift
pod 'FPHISDKSelphiComponent', '~> $VERSION'
```
### Swift Package Manager (SPM)
Si utilizas **SPM**, asegúrate de que las dependencias obligatorias del SDK estén previamente instaladas.
```sh
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```
Para instalar el componente **Selphi**, inclúyelo en los módulos del proyecto.
```swift
//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-Selphi_component-SPM.git
```
***
## Permisos
En la aplicación cliente donde se vayan a integrar los componentes es necesario incorporar el siguiente elemento en el fichero **Info.plist**:
```
Es necesario permitir el uso de la cámara (Privacy - Camera Usage Description)
```
## Controladores disponibles
| **Controlador** | **Descripción** |
| ------------------------- | -------------------------------------------------------------- |
| SelphiController | Controlador principal de reconocimiento facial |
| RawTemplateController | Controlador para generar un RawTemplate a partir de una imagen |
| SignatureSelphiController | Controlador para firmar un proceso con una Captura |
***
## Lanzamiento simplificado
Una vez iniciado el SDK y creada una nueva operación, el componente puede lanzarse utilizando cualquiera de sus controladores disponibles, según la funcionalidad requerida.
```swift
let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
// Do whatever with the result
...
}, viewController: viewController)
SDKController.shared.launch(controller: controller)
```
***
## Recepción del resultado
El lanzamiento del componente devuelve un resultado en formato `SdkResult`, que incluye:
* `selphiResult.finishStatus`
* `selphiResult.errorType`
* `selphiResult.data`
### Recepción de errores
*finishStatus*: Indica si la operación ha finalizado correctamente. Posibles valores:
FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR
*errorType*: Errores propios del widget.
En iOS, `errorType` es un `ErrorType` del SDK. En un timeout, el enum Swift puede ser `.SDK_TIMEOUT`, `.SELPHI_TIMEOUT(LivenessDiagnostic?)` o, si se interpola directamente, mostrar nombres como `SDK_TIMEOUT` o `SELPHI_TIMEOUT`. En iOS no existe un caso `TIMEOUT` sin prefijo.
Para serializar el error debe utilizarse:
```swift
sdkResult.errorType.toString(addComponentPrefix: "SPI_")
```
Esto devuelve `SPI_TIMEOUT` tanto si el enum es `SDK_TIMEOUT` como `SELPHI_TIMEOUT`.
#### Comportamiento en timeout
En un timeout, el resultado tiene:
* `finishStatus`: `STATUS_ERROR`
* `data`: `nil` (no se devuelve un `SelphiResult`)
* `errorType`: `.SDK_TIMEOUT` o `.SELPHI_TIMEOUT(LivenessDiagnostic?)`
El caso `SELPHI_TIMEOUT` conserva, cuando está disponible, el diagnóstico de liveness del widget. Esa información **no** forma parte de `data`; solo puede leerse en iOS mediante pattern matching sobre `errorType`:
```swift
if case .SELPHI_TIMEOUT(let diagnostic) = sdkResult.errorType {
// diagnostic: LivenessDiagnostic? (puede ser nil)
}
```
Si el timeout llega como `SDK_TIMEOUT`, no incluye diagnóstico de liveness. Si llega como `SELPHI_TIMEOUT`, el diagnóstico asociado puede ser `nil` cuando el timeout se produce por la vía de error del widget (`FWETimeout`) en lugar del delegate `extractionTimeout()`.
Para integraciones iOS nativas, el valor serializado debe tratarse como `SPI_TIMEOUT` (incluye tanto `SDK_TIMEOUT` como `SELPHI_TIMEOUT` del enum).
Si `showDiagnostic` está activo, el callback `output` no se invoca en el instante del timeout: se muestra primero la pantalla de diagnóstico y el resultado se entrega al pulsar cerrar. Con `showDiagnostic` desactivado, el callback se ejecuta de forma inmediata.
La lista siguiente incluye errores del contrato multiplataforma; algunos no se producen en iOS.
* SPI\_APPLICATION\_CONTEXT\_ERROR: El contexto de aplicación necesario es nulo.
* SPI\_BAD\_EXTRACTOR\_CONFIGURATION\_ERROR: Widget: Configuración del extractor incorrecta.
* SPI\_CAMERA\_PERMISSION\_DENIED: El usuario ha rechazado los permisos.
* SPI\_CANCEL\_BY\_USER: El usuario ha cancelado el proceso.
* SPI\_COMPONENT\_LICENSE\_ERROR: La licencia del componente no es correcta.
* SPI\_EMPTY\_LICENSE: El String de licencia está vacío.
* SPI\_EXTRACTION\_LICENSE\_ERROR: Widget: Error de licencia.
* SPI\_ACTIVE\_LIVENESS\_ERROR: Widget: Error en el proceso de liveness activo.
* SPI\_HARDWARE\_ERROR: Widget: Error de hardware.
* SPI\_INITIALIZATION\_ERROR: Error de inicialización.
* SPI\_MANAGER\_NOT\_INITIALIZED: Los managers son nulos.
* SPI\_NO\_DATA\_ERROR: Los datos de entrada son nulos.
* SPI\_OPERATION\_NOT\_CREATED: No hay ninguna operación en curso.
* SPI\_RESOURCES\_FILE\_NOT\_FOUND: No se ha encontrado el zip de recursos.
* SPI\_SETTINGS\_PERMISSION\_ERROR: Widget: Error de permisos.
* SPI\_TEMPLATE\_ERROR:
* SPI\_TIMEOUT: Timeout en el proceso (`SDK_TIMEOUT` o `SELPHI_TIMEOUT` del enum).
* SPI\_UNEXPECTED\_CAPTURE\_ERROR: Widget: Error en la captura.
* SPI\_UNKNOWN\_ERROR: Error desconocido.
* SPI\_WIDGET\_RESULT\_DATA\_ERROR: Error en los datos de salida del widget.
### Recepción de ejecución correcta - data
El contenido del campo `data` depende del componente lanzado. En **Selphi**, puede incluir:
* `template`\
Plantilla facial generada tras la extracción. Válida para **authentication**.
* `templateRaw`\
Plantilla facial en bruto generada después del proceso de extracción. Válida para **authentication**.
* `bestImageData`\
Mejor imagen capturada, en formato array de bytes y tamaño original. Válida para **liveness**.
* `bestImageCroppedData`\
Imagen recortada centrada en el rostro. Recomendado como avatar del usuario.
* `qrData`\
Información obtenida de la lectura de QR en formato `String`.
* `bestImageTokenized`\
Imagen cifrada resultante del proceso. Válida para **liveness**.
***
## Información avanzada
### Controladores adicionales
**SignatureSelphiController**\
Funciona igual que `SelphiController`, pero genera un fichero de firma del proceso.
**RawTemplateController**\
Permite generar un `RawTemplate` a partir de una imagen (`bitmap`).
Ejemplo de uso:
```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)
```
o
```swift
let controller = RawTemplateController(
data: bestImageData,
output: { sdkResult in
guard let result = sdkResult.data else {return}
print(result.base64EncodedString())
})
SDKController.shared.launchMethod(controller: controller)
```
### Configuración avanzada
Para lanzar el componente, se debe crear un objeto `SelphiConfigurationData`.\
Este objeto define el comportamiento y la configuración del componente.
#### Parámetros disponibles
* `resourcesPath`\
Ruta relativa a la carpeta `Resources` donde se encuentra el archivo de recursos.
* `showTutorial`\
Muestra el tutorial previo a la captura.
* `showDiagnostic`\
Muestra una pantalla de diagnóstico en caso de error o permisos insuficientes.
* `showResultAfterCapture`\
Muestra la imagen capturada y permite repetir el proceso.
* `debug`\
Activa el modo depuración.
* `fullscreen`\
Prioriza la visualización en pantalla completa.
* `cropPercent`\
Porcentaje de recorte del rostro.
* `livenessMode`\
Modo de detección de vida:
* `NONE`
* `PASSIVE`
* `MOVE`
* `stabilizationMode`\
Obliga al usuario a mantener la cabeza estable antes de iniciar el proceso.
* `templateRawOptimized`\
Indica si el `templateRaw` debe optimizarse.
* `qrMode`\
Activa o desactiva la lectura de QR.
* `videoFilename`\
Ruta absoluta para grabar el vídeo del proceso.
* `cameraFlashEnabled`\
Activa el flash de la cámara.
* `translationsContent`\
Configuración avanzada de textos mediante XML.
* `viewsContent`\
Configuración avanzada de vistas mediante XML.
* `vibrationEnabled`\
Activa la vibración en errores y en resultados correctos.
* `animateDismiss`\
Indica si se anima el cierre del SDK al finalizar el proceso. Disponible desde **2.8.1**.
### Personalización del componente
Además de los cambios que se pueden realizar a nivel de SDK (explicados en *Personalización del SDK*), este componente permite su propia personalización.
#### Textos
Los textos se personalizan sobrescribiendo claves en `Localizable.strings`, dentro de la carpeta `Resources`.
Las claves con sufijo `_alt` se utilizan para accesibilidad (VoiceOver).
Ejemplo de modificación del texto **COMENZAR** para `es`:
Hay que ir al archivo **Localizable.strings** de la carpeta **es.lproj** (si no existe esta carpeta, habrá que crearla).
```
"selphi_component_tip_button_message" = "EMPEZAR";
```
Si una clave no está definida, se utilizará el valor por defecto.
| **Name** | **Value** |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| selphi\_component\_tutorial\_message\_1 | Coloca tu cara en el centro y mira de frente a la cámara. |
| selphi\_component\_tutorial\_message\_2 | Retira cualquier objeto que cubra tu cara. |
| selphi\_component\_tutorial\_message\_3 | Busca un entorno bien iluminado, sin sombras sobre tu rostro. |
| selphi\_component\_tip\_message | Coloca tu cara en el centro del círculo |
| selphi\_component\_tip\_title | Reconocimiento facial |
| selphi\_component\_tip\_button | COMENZAR |
| selphi\_component\_tip\_button\_alt | Comenzar captura de rostro |
| selphi\_component\_tip\_anim\_alt | Una persona muestra su cara dentro del círculo y la aplicación le hace una foto. |
| selphi\_component\_tip\_move\_anim\_alt | Animación de una pantalla de móvil con la cámara frontal activada. En el centro de la pantalla aparece un círculo. Una persona muestra su cara dentro del círculo, la mueve ligeramente hacia un lado y la aplicación le hace una foto. |
| selphi\_component\_tutorial\_1\_anim\_alt | La foto se realiza cuando la persona está en el centro. |
| selphi\_component\_tutorial\_2\_anim\_alt | Una persona se quita las gafas de sol y se retira el pelo de los ojos. |
| selphi\_component\_tutorial\_3\_anim\_alt | La imagen aparece oscura y una persona enciende la luz. |
| selphi\_component\_tip\_move\_message | Coloca tu cara en el centro del círculo y sigue las indicaciones. |
| selphi\_component\_timeout\_title | Tiempo superado |
| selphi\_component\_timeout\_desc | No hemos podido identificarte. Inténtalo de nuevo |
#### Animaciones
Las animaciones del tip previo y tutoriales son **Lottie (.json)**.
Para sustituirlas:
* Añade el archivo en la carpeta `Resources`.
* Mantén exactamente el mismo nombre del archivo.
Si no se sustituyen, se mostrarán las animaciones por defecto.
| Nombre | Función |
|---|
| selphi_anim_tip | Animación LivenessMode: None, Passive |
| selphi_anim_tip_move | Animación LivenessMode: Move |
| selphi_anim_tuto_1 | Primera animación del tutorial |
| selphi_anim_tuto_2 | Segunda animación del tutorial |
| selphi_anim_tuto_3 | Tercera animación del tutorial |