Version: 2.4.X

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)

1.1 Requisitos mínimos

La versión mínima de la SDK de iOS requerida es la siguiente:

Versión mínima de iOS: 13

2. Integración del componente

⚠️ Antes de integrar este componente se recomienda leer la documentación de Integración Inicial 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.

Cocoapods

Actualmente las librerías de FacePhi se distribuyen de forma remota a través de diferentes gestores de dependencias, en este caso Cocoapods. Las dependencias obligatorias que deberán haberse instalado previamente (añadiéndolas en el fichero Podfile del proyecto) son:

  pod 'FPHISDKMainComponent', '~> 2.4.0'
  pod 'zipzap'

Para instalar el componente de Selphi deberá incluirse la siguiente entrada en el Podfile de la aplicación:

  pod 'FPHISDKSelphiComponent', '~> 2.4.0'

Una vez instaladas las dependencias, se podrá hacer uso de las diferentes funcionalidades del componente.
En caso de realizar el desarrollo con XCode15 se deberá incluir un script de post-instalacion:

SPM

Las dependencias obligatorias que deberán haberse instalado previamente son:

//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git

Para instalar el componente de NFC deberá incluirse en los módulos del proyecto:

//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-Selphi_component-SPM.git

2.2 Permisos y configuraciones

En la aplicación cliente donde se vayan a integrar los componentes es necesario incorporar el siguiente elementos en el fichero info.plist

Es necesario permitir el uso de la cámara (Privacy - Camera Usage Description)

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 Iniciar nueva operación, en el que se detalla y explica en qué consiste este proceso.

4. 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

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.1 Configuración Básica

resourcesPath

Establece la ruta donde se encuentra el archivo de recursos del widget. Este archivo contiene tanto los recursos gráficos como los recursos de localización. Esta ruta debe especificarse relativa a la carpeta ‘assets’ de la aplicación principal.

showTutorial

Esta propiedad permite mostrar el tutorial previo al proceso de captura.

showDiagnostic

Si se le da valor true, al producirse un error o una falta de permisos, el sdk mostrará una pantalla con el error devuelto por el widget.

showResultAfterCapture

Indica si mostrar o no una pantalla con la imagen capturada del documento 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 del documento no fuera correcta.

5.1.2 Configuración Avanzada

debug

Activación del modo depuración del componente.

fullscreen

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

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.

locale

A partir de la versión 2.4.X este parámetro deja de configurarse a nivel de Componente y se hará en el initSdk del apartado Parámetros opcionales del initSdk.

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.

livenessMode

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

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.
SelpiFaceLivenessMode.MOVE: Indica que el test de liveness es activo, mostrando unas instrucciones durante la captura, y devolviendo el correspondiente resultado del proceso.

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.

templateRawOptimized

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

qrMode

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

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.

cameraFlashEnabled

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

translationsContent

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

viewsContent

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

5.1.3 Otros parametros

vibrationEnabled

Si se le da valor true, se activa la vibración en errores y si la respuesta del widget es OK

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, y trackeando los eventos internos al servidor de tracking:

let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)

[SIN TRACKING] Esta llamada permite lanzar la funcionalidad del componente con normalidad, pero no se trackeará ningún evento al servidor de tracking:

let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launchMethod(controller: controller)

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 Retorno de Resultado.

7.1. Recepción de errores

finishStatus: Que nos indicará si la operación ha finalizado correctamente. Posibles valores:

FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR

errorType: Errores propios del widget.

public enum ErrorType: Equatable, Error {
    //COMMON - BASIC
    case NO_ERROR
    case UNKNOWN_ERROR
    case OTHER(String)
    
    //COMMON - REQUIREMENTS
    case NO_DATA_ERROR
    case NO_OPERATION_CREATED_ERROR
    case NETWORK_CONNECTION
    
    //COMMON - PERMISSIONS
    case CAMERA_PERMISSION_DENIED
    case MIC_PERMISSION_DENIED
    case LOCATION_PERMISSION_DENIED
    case STORAGE_PERMISSION_DENIED
    
    //COMMON - USER'S INTERACTION
    case CANCEL_BY_USER
    case SELPHI_TIMEOUT(LivenessDiagnostic?)
    
    //COMMON - LICENSE ERROR
    case LICENSE_CHECKER_ERROR(String)
    case MISSING_COMPONENT_LICENSE_DATA
    case COMPONENT_LICENSE_ERROR
    case EMPTY_LICENSE
}

IMPORTANTE: SelphiComponent no utiliza el ErrorType.TIMEOUT común, sino SELPHI_TIMEOUT. Este error proporciona un LivenessDiagnostic opcional para ofrecer más información al integrador. Este diagnóstico proporciona información si se salta un evaluador de IAD.

Los errores 'ErrorType.OTHER' y 'ErrorType.LICENSE_CHECKER_ERROR' son especiales porque además pueden informar del detalle del error.

El String puede tener los siguientes valores en el caso del 'ErrorType.OTHER':

public enum SelphiError: String {
    case WIDGET_RESULT_DATA_ERROR
    case INITIALIZATION_ERROR
    case RESOURCES_FILE_NOT_FOUND
    case ACTIVE_LIVENESS_ERROR
    
    //Widget ERRORS
    case BAD_EXTRACTOR_CONFIGURATION_ERROR
    case BAD_CONFIGURATION_ERROR
    case CONTROL_NOT_INITIALIZED_ERROR
    case EXTRACTION_LICENSE_ERROR
    case HARDWARE_ERROR
    case SETTINGS_PERMISSION_ERROR
    case UNEXPECTED_CAPTURE_ERROR
    case TEMPLATE_ERROR
}

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

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 template

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

7.2.2 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.3 bestImageData

Devuelve la mejor imagen extraída del proceso de autenticación en formato array de bytes. 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 bestImageCroppedData

Devuelve una imagen recortada centrada en la cara del usuario en formato array de bytes. Esta imagen se obtiene a partir de la bestImage. Ésta es la imagen que se deberá utilizar como imagen característica del usuario que realizó el proceso a modo de avatar.

7.2.5 QrData

Devuelve la información proveniente de la lectura del QR en formato String

7.2.6 bestImageTokenized

Devuelve la mejor imagen extraída del proceso cifrada. Válido para el proceso de liveness.

8. Controladores Adicionales

8.1. RawTemplateController

Controlador para generar un RawTemplate se puede usar tanto la imagen en base64 como en data. .

Ejemplo de uso:

let controller = RawTemplateController(
	base64: bestImageData.base64EncodedString(),
	output: { sdkResult in
		guard let result = sdkResult.data else {return}
		print(result.base64EncodedString())
	})
SDKController.shared.launchMethod(controller: controller)

let controller = RawTemplateController(
	data: bestImageData,
	output: { sdkResult in
		guard let result = sdkResult.data else {return}
		print(result.base64EncodedString())
	})
SDKController.shared.launchMethod(controller: controller)

9. Personalizando el componente

Aparte de los cambios que se pueden realizar a nivel de SDK (los cuales se explican en el documento de Personalización de la SDK), este componente en concreto permite la modificación de animaciones y textos específicos.

9.1 Personalizando las animaciones

El componente de Selphi utiliza las siguientes animaciones:

public enum Animation : String, CaseIterable {
	case selphi_anim_tip
	case selphi_anim_tip_move
	case selphi_anim_tuto_1
	case selphi_anim_tuto_2
	case selphi_anim_tuto_3
}

Las animaciones configuradas por defecto pueden sobreescribirse creando un archivo en el proyecto con el mismo nombre y extensión (.json en este caso).

También pueden configurarse de forma dinamica en tiempo de ejecución. Para hacer esto, es necesario crear una clase "tema custom" (custom "theme") que implemente la interfaz ThemeSelphiProtocol.

import selphiComponent
class CustomThemeSelphi: ThemeSelphiProtocol {
	var name: String = "custom"

	public var customBoolean: Bool = true
	var animations: [R.Animation : String] {
		[.selphi_anim_tip: customBoolean ? "primary_custom_selphi_anim_tip": "secondary_custom_selphi_anim_tip",
		 .selphi_anim_tip_move: customBoolean ? "primary_custom_selphi_anim_tip_move": "secondary_custom_selphi_anim_tip_move",
		 .selphi_anim_tuto_1: customBoolean ? "primary_custom_selphi_anim_tuto_1": "secondary_custom_selphi_anim_tuto_1",
		 .selphi_anim_tuto_2: customBoolean ? "primary_custom_selphi_anim_tuto_2": "secondary_custom_selphi_anim_tuto_2",
		 .selphi_anim_tuto_3: customBoolean ? "primary_custom_selphi_anim_tuto_3": "secondary_custom_selphi_anim_tuto_3"]
	}
}

Para que la personalización se aplique al componente, se debe ejecutar ThemeSelphiManager.setup(theme: CustomThemeSelphi()) antes de lanzar el selphidController.

let selphiController = SelphiController(data: SelphiConfigurationData(), output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
ThemeSelphiManager.setup(theme: CustomThemeSelphi())
SDKController.shared.launch(controller: selphiController)

9.1.1 Guía de animaciones

selphi_anim_tip Esta animación se muestra si el livenessMode NO es MOVE.

var configSelphi = SelphiConfigurationData()
...
configSelphi.livenessMode = SelphiFaceLivenessMode.PASSIVE

MobileCapture

selphi_anim_tip_move Esta animación se muestra si el livenessMode es MOVE.

var configSelphi = SelphiConfigurationData()
...
configSelphi.livenessMode = SelphiFaceLivenessMode.MOVE

MobileCapture

selphi_anim_tuto_1

MobileCapture

selphi_anim_tuto_2

MobileCapture

selphi_anim_tuto_3

MobileCapture

9.2 Textos

Los textos pueden ser customizados sobreescribiendo el valor de las siguientes claves en un Localizable.strings. Las claves que contienen el sufijo _alt son los literales utilizados en las etiquetas de accesibilidad necesarias para la funcionalidad de voice over.

"selphi_component_tutorial_1"="Coloca tu cara en el centro y mira de frente a la cámara.";
"selphi_component_tutorial_2"="Retira cualquier objeto que cubra tu cara.";
"selphi_component_tutorial_3"="Busca un entorno bien iluminado, sin sombras sobre tu rostro.";
"selphi_component_tip_desc"="Coloca tu cara en el centro del círculo";
"selphi_component_tip_title"="Reconocimiento facial";
"selphi_component_tip_button_message"="COMENZAR";
"selphi_component_tip_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 y la aplicación le hace una foto.";
"selphi_component_tip_move_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_alt"="Aparece un círculo en el centro de la pantalla. Una persona muestra su cara. Se puede ver su cabeza al completo dentro del círculo. Cuando está bien posicionada, la aplicación le hace una foto.";
"selphi_component_tutorial_2_alt"="Aparece un círculo en el centro de la pantalla. Dentro del círculo hay una persona, con gafas de sol, y el pelo tapando parte de su cara. Se quita las gafas y se retira el pelo de la cara. La aplicación detecta su cara al completo y le hace una foto.";
"selphi_component_tutorial_3_alt"="Aparece un círculo oscuro en el centro de la pantalla. Dentro del círculo, se observa con dificultad la cara de una persona. Se enciende una luz y su cara se aprecia con claridad. Tras esto, la aplicación le hace una foto.";
"selphi_component_tutorial_move_desc"="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";

De este modo, si se desea modificar por ejemplo el texto “COMENZAR” de la clave selphi_component_tip_button_message para el idioma es-MX, se deberá ir al archivo Localizable.strings de la carpeta es-MX.lproj si es que existe (si no, se deberá crear) y ahí, añadir:

"selphi_component_tip_button_message"="EMPEZAR";

Si un mensaje no se especifica en el fichero del idioma, este se rellenará con el mensaje por defecto.

9.3 Colores, imágenes, tamaños y fuentes

Al contrario que con las animaciones, la personalización de estos elementos se hace desde el Componente de Status.

Selphi está dividido en dos partes, la primera es la espeicifcada en las secciones previas y contiene las pantallas de "tutorial" y "Más información". La segunda es el widget de captura con cámara.

MobileCapture

Este widget puede ser personalizado también, pero para hacerlo se deben modificar los recursos de Selphi.

0. Requisitos base de SDK Mobile​

1. Introducción​

1.1 Requisitos mínimos​

2. Integración del componente​

2.1. Dependencias requeridas para la integración​

Cocoapods​

SPM​

2.2 Permisos y configuraciones​

3. Iniciar nueva operación​

4. Controladores disponibles​

5. Configuración del componente​

5.1. Class SelphiConfigurationData​

5.1.1 Configuración Básica​

resourcesPath​

showTutorial​

showDiagnostic​

showResultAfterCapture​

5.1.2 Configuración Avanzada​

debug​

fullscreen​

cropPercent​

locale​

livenessMode​

stabilizationMode​

templateRawOptimized​

qrMode​

videoFilename​

cameraFlashEnabled​

translationsContent​

viewsContent​

5.1.3 Otros parametros​

vibrationEnabled​

6. Uso del componente​

7. Recepción del resultado.​

7.1. Recepción de errores​

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

7.2.1 template​

7.2.2 templateRaw​

7.2.3 bestImageData​

7.2.4 bestImageCroppedData​

7.2.5 QrData​

7.2.6 bestImageTokenized​

8. Controladores Adicionales​

8.1. RawTemplateController​

9. Personalizando el componente​

9.1 Personalizando las animaciones​

9.1.1 Guía de animaciones​

9.2 Textos​

9.3 Colores, imágenes, tamaños y fuentes​

9.4 Personalización del Widget​

0. Requisitos base de SDK Mobile

1. Introducción

1.1 Requisitos mínimos

2. Integración del componente

2.1. Dependencias requeridas para la integración

Cocoapods

SPM

2.2 Permisos y configuraciones

3. Iniciar nueva operación

4. Controladores disponibles

5. Configuración del componente

5.1. Class SelphiConfigurationData

5.1.1 Configuración Básica

resourcesPath

showTutorial

showDiagnostic

showResultAfterCapture

5.1.2 Configuración Avanzada

debug

fullscreen

cropPercent

locale

livenessMode

stabilizationMode

templateRawOptimized

qrMode

videoFilename

cameraFlashEnabled

translationsContent

viewsContent

5.1.3 Otros parametros

vibrationEnabled

6. Uso del componente

7. Recepción del resultado.

7.1. Recepción de errores

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

7.2.1 template

7.2.2 templateRaw

7.2.3 bestImageData

7.2.4 bestImageCroppedData

7.2.5 QrData

7.2.6 bestImageTokenized

8. Controladores Adicionales

8.1. RawTemplateController

9. Personalizando el componente

9.1 Personalizando las animaciones

9.1.1 Guía de animaciones

9.2 Textos

9.3 Colores, imágenes, tamaños y fuentes

9.4 Personalización del Widget