Saltar al contenido principal
Version: 1.5.4

Selphi Component

0. Requisitos base de SDK Mobile​

SDK Mobile es un conjunto de librerías (Componentes) que ofrece una serie de funcionalidades y servicios, permitiendo a su vez su integración en una aplicación Mobile de forma sencilla y totalmente escalable. Dependiendo del caso de uso que se requiera, se deberá realizar la instalación de unos determinados componentes. Su alto nivel de modularidad permite que, en un futuro, se puedan añadir otros componentes nuevos sin afectar en absoluto a los ya integrados en el proyecto.

Para más información sobre la configuración base, vaya a la sección de Primeros Pasos.

1. Introducción​

El Componente tratado en el documento actual recibe el nombre de Selphi Component. Éste se encarga de realizar la captura de un selfie del usuario y la posterior extracción de las características faciales más importantes. Sus principales funcionalidades son las siguientes:

  • Gestión interna de cámaras.

  • Gestión de permisos.

  • Asistente en los procesos de captura de la cara del usuario.

  • Generación de las plantillas con las características faciales y de la imagen de la cara del usuario para el proceso de detección de vivacidad (Liveness)

2. Integración del componente​

Antes de integrar este componente se recomienda leer la documentación relativa a:

Primeros Pasos y seguir las instrucciones indicadas en dicho documento.

En esta sección se explicará paso a paso cómo integrar el componente actual en un proyecto ya existente.

2.1. Dependencias requeridas para la integración​

Para evitar conflictos y problemas de compatibilidad, en caso de querer instalar el componente en un proyecto que contenga una versión antigua de las librerías de Facephi (Widgets), éstos deberán eliminarse por completo antes de la instalación de los componentes de la SDKMobile.

  • Actualmente las librerías de FacePhi se distribuyen de forma remota a través de diferentes gestores de dependencias. Las dependencias obligatorias que deberán haberse instalado previamente:

    implementation "com.facephi.androidsdk:selphi_component:$sdk_selphi_component_version"

3. Iniciar nueva operación​

Cuando se desea realizar una determinada operación, para generar la información asociada correctamente en la plataforma deberá ejecutarse previamente el comando newOperation.

Este comando debe haberse ejecutado anteriormente al lanzamiento del componente.

Para saber más acerca de cómo iniciar una nueva operación, se recomienda consultar la documentación de Primeros Pasos, en el que se detalla y explica en qué consiste este proceso.

4. Controladores disponibles​

ControladorDescripción
SelphiControllerControlador principal de reconocimiento facial
RawTemplateControllerControlador para generar un RawTemplate a partir de una imagen
SignatureSelphiControllerControlador para firmar un proceso con una Captura

5. Configuración del componente​

Para configurar el componente actual, una vez inicializado, se deberá crear un objeto SelphiConfigurationData y pasarlo como parámetro al SDKController durante el lanzamiento del componente.

En el siguiente apartado se mostrarán los campos que forman parte de esta clase y para qué se utiliza cada uno de ellos.

5.1. Class SelphiConfigurationData​

5.1.0. debug​

Activación del modo depuración del componente.

5.1.1. resourcesPath​

Indica el nombre de los recursos en formato zip del componente. Ejemplo: “resources-selphi-2-0.zip“.

Este nombre irá a buscar el fichero a la ruta de assets.

Image

5.1.2. cropPercent​

Permite modificar el porcentaje de recortado de la cara. Cuanto mayor sea el número mayor será el recorte del rectángulo con respecto a la cara.

5.1.3. showResultAfterCapture​

Indica si mostrar o no una pantalla con la imagen capturada después del proceso de análisis. En esta pantalla se le da al usuario la posibilidad de repetir el proceso de captura si la imagen que se obtuvo no fuera correcta.

5.1.4. showTutorial​

Indica si el widget activa la pantalla de tutorial. En esta vista se explica de forma intuitiva cómo se realiza la captura.

5.1.5. livenessMode​

Establece el modo liveness del widget. Los valores permitidos son:

  • LIVENESS_NONE: Indica que no debe activarse el modo detección de foto en los procesos de autenticación.

  • LIVENESS_PASSIVE: Indica que la prueba de vida pasiva se realiza en el servidor, enviando para tal fin la “BestImage” o el “TemplateRaw” correspondiente.

5.1.6. stabilizationMode​

Establece un modo de estabilización previo a cualquier proceso de autenticación en el widget. Con este modo se obliga al widget a no empezar ningún proceso si el usuario no se encuentra con la cabeza, mirando al frente y sin moverla.

5.1.7. cameraFlashEnabled​

Indica si se activa el flash de la cámara del dispositivo.

5.1.8 locale​

Fuerza al widget a utilizar la configuración de idioma indicado por el parámetro locale. Este parámetro acepta tanto un código de idioma (p. ej. ‘en’) como un código de identificación regional (p. ej. ‘en_US’). Si el archivo de recursos del widget no tuviera una localización para el ‘locale’ seleccionado su configuración pasaría a utilizar el idioma por defecto.

5.1.9 fullscreen​

Indica si la vista va a tener prioridad para mostrarse en pantalla completa, si el sistema lo permite.

5.1.10. templateRawOptimized​

Indica si el template (templateRaw) generado tras el selfie debe optimizarse o no.

5.1.11. qrMode​

Booleano que indica si se quiere o no activar la lectura de QR previo al proceso de autenticación.

5.1.12 videoFilename​

Establece la ruta absoluta del nombre del archivo en el que se grabará un video del proceso de captura. La aplicación es la responsable de solicitar los permisos necesarios al teléfono en caso de que esa ruta requiera de permisos adicionales. El widget, por defecto, no realizará ningún proceso de grabación a menos que se especifique una ruta de archivo mediante este método.

5.1.13 translationsContent​

Esta propiedad avanzada permite, mediante una cadena en formato xml, configurar la traducción de los literales que se muestran durante el proceso.

Nota: Esta propiedad no altera el contenido del archivo de recursos.

5.1.14 viewsContent​

Esta propiedad avanzada permite, mediante una cadena en formato xml, configurar las vistas del widget.

Nota: Esta propiedad no altera el contenido del archivo de recursos.

5.1.15. showDiagnostic​

Mostrar pantallas de diagnóstico al final del proceso

6. Uso del componente​

Una vez iniciado el componente y creada una nueva operación (apartado 3) se podrán lanzar los componentes del SDK. Hay dos formas de lanzar el componente:

  • [CON TRACKING] Esta llamada permite lanzar la funcionalidad del componente con normalidad, pero sí se trackearán los eventos internos al servidor de tracking:
SDKController.launch(
    SelphiController(SelphiConfigurationData(...)) {
        when (it) {
            is SdkResult.Error -> Napier.d("Selphi: ERROR - ${it.error.name}")
            is SdkResult.Success -> it.data
        }
    }
)
  • [SIN TRACKING] Esta llamada permite lanzar la funcionalidad del componente con normalidad, pero no se trackeará ningún evento al servidor de tracking:
SDKController.launchMethod(
    SelphiController(SelphiConfigurationData(...)) {
        when (it) {
            is SdkResult.Error -> Napier.d("Selphi: ERROR - ${it.error.name}")
            is SdkResult.Success -> it.data
        }
    }
)

El método launch debe usarse por defecto. Este método permite utilizar tracking en caso de estar su componente activado, y no lo usará cuando esté desactivado (o no se encuentre el componente instalado).

Por el contrario, el método launchMethod cubre un caso especial, en el cual el integrador tiene instalado y activado el tracking, pero en un flujo determinado dentro de la aplicación no desea trackear información. En ese caso se usa este método para evitar que se envíe esa información a la plataforma.

7. Recepción del resultado​

Los controllers devolverán la información necesaria en formato SdkResult. Más información en la sección de 6. Retorno de resultado del Android Mobile SDK

7.1. Recepción de errores​

En la parte del error, dispondremos de la clase SelphiError.

    SelphiError.ACTIVITY_RESULT_ERROR
    SelphiError.BAD_EXTRACTOR_CONFIGURATION_ERROR
    SelphiError.CAMERA_PERMISSION_DENIED
    SelphiError.CANCEL_BY_USER
    SelphiError.CONTROL_NOT_INITIALIZATED_ERROR
    SelphiError.EXTRACTION_LICENSE_ERROR
    SelphiError.HARDWARE_ERROR
    is SelphiError.INITIALIZATION_ERROR -> it.error //Para más detalles
    SelphiError.NO_ERROR
    SelphiError.RESOURCES_NOT_FOUND
    SelphiError.SETTINGS_PERMISSION_ERROR
    SelphiError.TIMEOUT
    SelphiError.UNEXPECTED_CAPTURE_ERROR
    SelphiError.UNKNOWN_ERROR

7.2. Recepción de ejecución correcta - data​

En la parte de data, dispondremos de la clase SelphiResult.

El resultado devuelve las imágenes en formato Bitmap, es posible convertir las imágenes a Base64 de la siguiente manera:

Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)

El campo data es variable y dependerá de qué componente se ha devuelto el resultado. En el caso de este componente, los campos devueltos son los siguientes:

7.2.1 templateRaw​

Devuelve la plantilla en bruto que se genera después del proceso de extracción. Válida para el proceso de AUTHENTICATION.

7.2.2 template​

Devuelve la plantilla que se genera después del proceso de extracción. Válida para el proceso de AUTHENTICATION.

7.2.3 bestImageBmp​

Devuelve la mejor imagen extraída del proceso de autenticación en formato SdkImage (Se puede extraer el bitmap de dentro). Esta imagen es la imagen con el tamaño original extraída de la cámara. Válido para el proceso de liveness.

7.2.4 bestImageCroppedBmp​

Devuelve una imagen recortada centrada en la cara del usuario en formato SdkImage (Se puede extraer el bitmap de dentro). Esta imagen se obtiene a partir de la bestImage. Ésta es la imagen que se podrá utilizar como imagen característica del usuario que realizó el proceso a modo de avatar.

8. Controladores Adicionales​

8.1. RawTemplateController​

Controlador para generar un RawTemplate a partir de una imagen (bitmap).

Ejemplo de uso:

SDKController.launch(
    RawTemplateController(SdkImage(image)) {
        when (it) {
            is SdkResult.Error -> Napier.d("GenerateRaw: KO - ${it.error}")
            is SdkResult.Success -> it.data
        }
    }
)