> 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/android-sdk/componentes-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 características faciales más relevantes. Durante el proceso se realizan, entre otros, los siguientes pasos: * Gestión interna de cámaras y permisos. * Asistencia guiada durante la captura facial. * Generación de plantillas biométricas e imágenes del usuario. En la sección [Lanzamiento simplificado](/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) se describen los pasos básicos para la integración del SDK. En esta página se detalla la información específica necesaria para lanzar y configurar este componente. *** ## Dependencia La dependencia específica del componente es: ```kotlin implementation "com.facephi.androidsdk:selphi_component:$version" ``` *** ## Controladores disponibles Este componente incluye varios controladores, cada uno orientado a una funcionalidad concreta. | Controlador | Descripción | | --------------------------- | ----------------------------------------------------- | | `SelphiController` | Controlador principal de reconocimiento facial | | `RawTemplateController` | Generación de un `RawTemplate` a partir de una imagen | | `SignatureSelphiController` | Firma de un proceso utilizando una captura facial | *** ## Lanzamiento simplificado Una vez iniciado el SDK y creada una nueva operación el componente puede lanzarse utilizando cualquiera de sus controladores. ```kotlin val response = SDKController.launch( SelphiController(SelphiConfigurationData(...)) ) when (response) { is SdkResult.Error -> Napier.d("Selphi: ERROR - ${response.error.name}") is SdkResult.Success -> response.data } ``` *** ## Configuración básica Para lanzar el componente es necesario crear un objeto `SelphiConfigurationData`, que define el comportamiento del widget. ```kotlin SelphiConfigurationData( resourcesPath = "resources_file.zip", livenessMode = SelphiFaceLivenessMode.NONE ) ``` El componente permite los siguientes modos de detección de vida: * `SelphiFaceLivenessMode.NONE` * `SelphiFaceLivenessMode.PASSIVE` * `SelphiFaceLivenessMode.MOVE` *** ## Recepción del resultado El resultado del lanzamiento se devuelve como un objeto `SdkResult`, que puede indicar un resultado correcto o un error. ```kotlin when (response) { is SdkResult.Error -> Napier.d("ERROR - ${response.error}") is SdkResult.Success -> response.data } ``` ### Recepción de errores Los errores se devolverán como un objeto 'SelphiError'. Listado de errores: * SPI\_ACTIVITY\_RESULT\_ERROR: El resultado de la actividad es incorrecto. * SPI\_ACTIVITY\_RESULT\_MSG\_ERROR: El resultado de la actividad recibido en el msg es incorrecto. * 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\_CANCEL\_LAUNCH: Se ha hecho una cancelación general del SDK. * SPI\_COMPONENT\_LICENSE\_ERROR: La licencia del componente no es correcta. * SPI\_CONTROL\_NOT\_INITIALIZATED\_ERROR: Widget: Error de inicialización. * SPI\_EMPTY\_LICENSE: El String de licencia está vacío. * SPI\_EXTRACTION\_LICENSE\_ERROR: Widget: Error de licencia. * SPI\_FETCH\_DATA\_ERROR: Error en la recogida del resultado. * SPI\_FLOW\_ERROR: Error en el proceso de flow. * 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\_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. * 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 del resultado correcto - *data* Cuando el resultado es correcto (`SdkResult.Success`), se obtiene un objeto `SelphiResult`. Las imágenes se devuelven en formato `SdkImage`. Es posible acceder al bitmap mediante `image.bitmap`.\ Para convertir una imagen a Base64: ```kotlin Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP) ``` #### Campos devueltos * `templateRaw`\ Plantilla en bruto generada tras la extracción. Válida para procesos de matching. * `template`\ Plantilla procesada tras la extracción. Válida para procesos de matching. * `bestImage`\ Mejor imagen capturada en resolución original. Esta imagen tiene el tamaño original extraída de la cámara. Válida para el proceso de liveness. * `bestImageCropped`\ Imagen recortada centrada en la cara del usuario. Se obtiene a partir de la *bestImage*. * `logImages`\ Lista con las 5 mejores imágenes (requiere `logImages = true`). * `bestImageTokenized`\ Mejor imagen cifrada del proceso. Válida para el proceso de liveness. *** ## Información avanzada ### Controladores Adicionales **SignatureSelphiController** Funciona de forma equivalente a `SelphiController`, con la diferencia de que genera un fichero de firma en la plataforma. **RawTemplateController** Permite generar un `RawTemplate` a partir de una imagen (`Bitmap`). Ejemplo de uso: ```kotlin val result = SDKController.launch( RawTemplateController(SdkImage(image)) ) when (result) { is SdkResult.Error -> Napier.d("GenerateRaw: KO - ${result.error}") is SdkResult.Success -> result.data } ``` ### Configuración avanzada El comportamiento del componente se define mediante `SelphiConfigurationData`. #### Parámetros disponibles * `resourcesPath`\ Nombre del archivo ZIP de recursos (ubicado en `assets`). Ejemplo: “resources-selphi-2-0.zip“.
* `cropPercent`\ Porcentaje de recorte de la cara. Cuanto mayor sea el número mayor será el recorte del rectángulo con respecto a la cara. * `cropImageDebug`\ Muestra información de depuración del recorte. * `showResultAfterCapture`\ Muestra una pantalla de confirmación tras la captura. Se le da al usuario la posibilidad de repetir el proceso de captura si la imagen que se obtuvo no fuera correcta. * `showTutorial`\ Activa la pantalla de tutorial. Se explica de forma intuitiva cómo se realiza la captura. * `livenessMode`\ Modo de detección de vida (`NONE`, `PASSIVE`, `MOVE`). * SelphiFaceLivenessMode.NONE: Indica que no debe activarse el modo detección de foto en los procesos de autenticación. * SelphiFaceLivenessMode.PASSIVE: Indica que la prueba de vida pasiva se realiza en el servidor, enviando para tal fin la “BestImage” o el “TemplateRaw” correspondiente. * SelphiFaceLivenessMode.MOVE: Indica que el test de liveness es activo, mostrando unas instrucciones durante la captura, y devolviendo el correspondiente resultado del proceso. * `stabilizationMode`\ Obliga al usuario a mantener la cabeza estable antes de capturar, mirando al frente y sin mover la cabeza. * `cameraFlashEnabled`\ Activa el flash de la cámara. * `fullscreen`\ Prioriza la visualización a pantalla completa. * `templateRawOptimized`\ Optimiza el `templateRaw` generado. * `qrMode`\ Activa la lectura de QR previa al proceso de autenticación. * `videoFilename`\ Ruta absoluta para grabar vídeo del proceso. La aplicación es la responsable de solicitar los permisos necesarios al teléfono en caso de requerirlos. * `viewsContent`\ Configuración avanzada de vistas mediante XML. Esta propiedad no altera el contenido del archivo de recursos. * `showDiagnostic`\ Muestra pantallas de diagnóstico. * `logImages`\ Devuelve las 5 mejores imágenes capturadas. * `showPreviousTip`\ Muestra una pantalla informativa previa a la captura. * `extractionDuration`\ Duración del proceso de extracción. * `cameraPreferred`\ Cámara preferida (`FRONT`, `BACK`). * `vibrationEnabled`\ Feedback de vibración al finalizar. * `moveSuccessfulAttempts`\ Reintentos permitidos en capturas correctas (por defecto 1). * `moveFailedAttempts`\ Reintentos permitidos en capturas incorrectas (por defecto 2). *** ## Personalización del componente Además de los cambios que se pueden realizar a nivel de SDK (explicados en [Personalización del SDK](/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente permite su propia personalización. ### Textos Los textos pueden personalizarse sobrescribiendo los valores en un fichero XML de strings. | **Name** | **Value** | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | selphi\_component\_timeout\_title | Tiempo superado | | selphi\_component\_timeout\_desc | No hemos podido identificarte. Inténtalo de nuevo | | selphi\_component\_internal\_error\_title | Hubo un problema técnico | | selphi\_component\_internal\_error\_desc | Pedimos disculpas. No se ha podido hacer la captura | | selphi\_component\_tip\_message | Coloca tu cara en el centro del círculo | | selphi\_component\_tip\_message\_alt | Coloca tu cara en el centro del círculo | | 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\_title | Reconocimiento facial | | selphi\_component\_tip\_button | COMENZAR | | selphi\_component\_tip\_button\_alt | Comenzar captura de rostro | | selphi\_component\_tip\_move\_message | Coloca tu cara en el centro del círculo y sigue las indicaciones | | selphi\_component\_tip\_move\_message\_alt | Coloca tu cara en el centro del círculo y sigue las indicaciones | | selphi\_component\_tip\_move\_anim\_alt | 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\_tip\_move\_title | Reconocimiento facial | | selphi\_component\_tip\_move\_button | COMENZAR | | selphi\_component\_qr\_tip\_title | Escanea el código QR | | selphi\_component\_qr\_tip\_message | Enfoca el código QR dentro del recuadro | | selphi\_component\_qr\_tip\_anim\_alt | Enfoca el código QR dentro del recuadro | | selphi\_component\_qr\_tip\_button | Comenzar | | selphi\_component\_tip\_close\_button\_alt | Volver | | selphi\_component\_tip\_info\_button\_alt | Ver consejos | | 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 elemento que cubra tu cara. | | selphi\_component\_tutorial\_message\_3 | Busca un entorno bien iluminado, sin sombras sobre tu rostro. | | 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\_tutorial\_close\_button\_alt | Volver al tutorial previo | ### Animaciones Las animaciones Lottie pueden sobrescribirse añadiendo los archivos con el mismo nombre en `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 ```