Captura de documentos
Este componente se encarga de realizar capturas de documentos de identidad y del análisis de los datos obtenidos. Sus principales procesos son:
Gestión interna de cámaras y permisos.
Asistente en los procesos de captura de la parte frontal y trasera del documento.
Extracción de la información contenida en el documento.
Obtención de las imágenes del dorso y reverso del documento, así como otras imagénes incluidas en el documento: cara del usuario, firma del usuario,...
Alto nivel de configuración: diferentes países, idiomas, tipos de documentos...
En el apartado de Lanzamiento simplificado se detallan los pasos necesarios para la integración básica del SDK. En esta sección se añade la información para el lanzamiento de este componente.
Dependencias
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.3.0'Para instalar el componente de SelphID deberá incluirse la siguiente entrada en el Podfile de la aplicación:
pod 'FPHISDKSelphIDComponent', '~> 2.3.0'SPM
Las dependencias obligatorias que deberán haberse instalado previamente son:
Para instalar el componente de Selphid deberá incluirse en los módulos del proyecto:
Controladores disponibles
SelphIDController
Controlador principal de reconocimiento de documentos
Lanzamiento simplificado
Una vez iniciado el SDK y creada una nueva operación se podrá lanzar el componente. Se podrá hacer uso de cualquiera de sus controladores para ejecutar su funcionalidad.
Recepción del resultado
El lanzamiento devolverá la información en formato SdkResult.
selphIDResult.errorType
selphIDResult.finishStatus
selphIDResult.data
Recepción de errores
finishStatus: Que nos indicará si la operación ha finalizado correctamente. Posibles valores:
errorType: Errores propios del widget.
SPD_APPLICATION_CONTEXT_ERROR: El contexto de aplicación necesario es nulo.
SPD_BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Configuración del extractor incorrecta
SPD_CAMERA_PERMISSION_DENIED: El usuario ha rechazado los permisos.
SPD_CANCEL_BY_USER: El usuario ha cancelado el proceso.
SPD_CANCEL_LAUNCH: Se ha hecho una cancelación general del SDK.
SPD_COMPONENT_LICENSE_ERROR: La licencia del componente no es correcta.
SPD_CONTROL_NOT_INITIALIZATED_ERROR: Widget: Error de inicialización
SPD_EMPTY_LICENSE: El String de licencia está vacío.
SPD_EXTRACTION_LICENSE_ERROR: Widget: Error de licencia
SPD_HARDWARE_ERROR: Widget: Error de hardware
SPD_INITIALIZATION_ERROR: Error de inicialización.
SPD_MOVE_FAIL: El usuario no se ha movido como se le ha especificado en el proceso.
SPD_NO_DATA_ERROR: Los datos de entrada son nulos.
SPD_OPERATION_NOT_CREATED: No hay ninguna operación en curso.
SPD_RESOURCES_NOT_FOUND: No se ha encontrado el zip de recursos
SPD_SETTINGS_PERMISSION_ERROR: Widget: Error de permisos
SPD_TIMEOUT: Timeout en el proceso.
SPD_UNEXPECTED_CAPTURE_ERROR: Widget: Error en la captura
SPD_UNKNOWN_ERROR: Error desconocido
SPD_WIDGET_RESULT_DATA_ERROR: Error en los datos de salida del widget
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:
frontDocument / tokenFrontDocument
La imagen frontal del documento procesada, limpiada y recortada por los bordes y su token correspondiente.
backDocument / tokenBackDocument
La imagen trasera del documento procesada, limpiada y recortada por los bordes y su token asociado.
faceImage / tokenFaceImage
La imagen del rostro que se ha encontrado en el documento, en caso de que exista y su token asociado.
documentCaptured
Esta propiedad indica el modelo de documento que se ha capturado cuando se realiza una busqueda en modo SMSearch. De esta forma la aplicación puede conocer qué modelo, de entre todos los permitidos, se ha detectado.
matchingSidesScore
Esta propiedad devuelve un cálculo de la similitud de los datos leídos entre el front y el back del documento. El cálculo se realiza comprobando la similitud entre los campos comunes leídos en ambas caras. El resultado del cálculo será un valor entre 0.0 y 1.0 para el caso de que existan campos comunes en el documento. Cuanto mayor es el valor, más similares son los datos comparados. Si el cálculo devuelve -1.0 es que el documento no contiene campos comunes o aún no se tiene información de las dos caras.
Propiedad captureProgress
Esta propiedad devuelve el estado en el que se encontraba el proceso de captura cuando el widget terminó. Estos son los posibles valores:
0: En la lectura del Front, el widget termino sin poder haber detectado nada. Generalmente cuando no se pone ningún documento.
1: En la lectura del Front, el widget termino habiendo detectado parcialmente un documento. En este caso algunos de los elementos esperados se han conseguido detectar, pero no todos los necesarios.
2: En la lectura del Front, el widget termino habiendo completado la detección de todos los elementos del documento. Si el widget acaba en este estado es porque el análisis de OCR no se ha podido completar con éxito.
3: En la lectura del Front, el widget termino habiendo analizado y extraído todo el OCR del documento. Este es el estado en el que acabaría una lectura correcta del Front de un documento.
Los estados del 4 al 7 son exactamente iguales solo que se refieren al resultado del proceso cuando se analiza el back.
ocrResults
Este diccionario contiene todos los datos detectados en el documento. Las claves de cada campo están codificadas de tal forma que la propia clave contiene información de donde se ha obtenido el valor. Así, por ejemplo, la clave Front/MRZ/DocumentNumber indica el valor del DocumentNumber que se ha leído en el Front del documento y en la región del MRZ. Estas claves dependen del documento capturado y por tanto serán diferentes entre distintos países y modelos de documento. El diccionario también contiene claves con nombres más genéricos y que no llevan información relativa a la ubicación. Estas claves contienen el dato más completo de todos los leídos para dicho campo.
Estas claves son los siguientes:
FirstName: El valor asociado a esta clave contiene el nombre del usuario.
LastName: El valor asociado a esta clave contiene los apellidos del usuario.
DateOfBirth: El valor asociado a esta clave contiene la fecha de nacimiento detectada en el documento.
Gender: El valor asociado a esta clave contiene el sexo del usuario detectado en el documento.
Nationality: El valor asociado a esta clave contiene la nacionalidad del usuario detectado en el documento.
DocumentNumber: El valor asociado a esta clave contiene el número de documento.
DateOfExpiry: El valor asociado a esta clave contiene la fecha de expiración del documento.
Issuer: El valor asociado a esta clave contiene el editor del documento.
DateofIssue: El valor asociado a esta clave contiene la fecha de expedición del documento.
PlaceOfBirth: El valor asociado a esta clave contiene el lugar de nacimiento del usuario.
Address: El valor asociado a esta clave contiene la dirección detectada en el documento.
Adicionalmente se añaden claves del propio objeto results para hacer más fácil su búsqueda:
DocumentCaptured: Valor del modelo de documento que se ha capturado según el .xml de modelos. Corresponde a la propiedad documentCaptured.
MatchingSidesScore: Valor que indica la correspondencia entre las caras leídas del documento. Corresponde a la propiedad matchingSidesScore.
countryCaptured
País del documento.
documentTypeCaptured
Tipo de documento. Se corresponde con los del apartado 5.1.10.
personalData
Conjunto reducido de datos obtenidos del usuario:
issuer
documentNumber
issueDate
expiryDate
name
surname
fullName
gender
birthDate
birthPlace
nationality
address
nfcKey
numSupport
mrz
Información avanzada
Este apartado amplía la información del componente
Configuración avanzada
Para lanzar el componente actual, se deberá crear un objeto SelphIDConfigurationData que será la configuración del controlador del componente.
A continuación se detallan todos los campos que forman parte de esta clase.
debug
Activación del modo depuración del componente.
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 ‘Resources’ de la aplicación principal.
wizardMode
Indica si el widget queda configurado para realizar la captura de ambas partes (frontal y trasera) del documento una a continuación de la otra. En este modo el widget solo se lanzaría una vez y al terminar de capturar el front, continuaría seguidamente con el back.
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.
showTutorial
Indica si el widget activa la pantalla de tutorial. En esta vista se explica de forma intuitiva cómo se realiza la captura.
tutorialOnly
Indica si el widget se quiere lanzar solo para mostrar el tutorial.
scanMode
Indica el modo de escaneo OCR de los documentos. Dependiendo de la elección, se escanearán y buscarán varios tipos de documentos o uno en concreto. Este modo puede ser de tres tipos:
SelphIDScanMode.MODE_GENERIC: El modo genérico que permite escanear cualquier tipo de documento independiente del país o el tipo de documento. El resultado de este modo no es tan preciso como los siguientes pero permite escanear varios documentos estándar.
SelphIDScanMode.MODE_SEARCH: El modo de búsqueda permitirá utilizar una whitelist y blacklist, y buscará en los documentos que cumplan dichas condiciones. Estas condiciones se indican en la variable "specificData". De este modo se permite realizar la búsqueda acotando el número de plantillas, y haciendo que la búsqueda sea mucho más afinada que en el caso genérico.
SelphIDScanMode.MODE_SPECIFIC: Búsqueda de un documento específico. Estas condiciones se indican en la propiedad "specificData" que se muestra en lo sucesivo.
SpecificData
Esta propiedad permite definir qué documentos se escanearán durante el proceso, en caso de declarar el modo de escaneo (scanMode) a SMSearch o SMSpecific.
Un ejemplo de configuración que permita escanear todos los documentos de nacionalidad española sería el siguiente:
tokenImageQuality
Indica la cantidad de calidad que se quiere recibir en las imágenes tokenizadas. Valor entre 0 y 1.
DocumentType
Los valores permitidos son los siguientes:
SelphIDDocumentType.ID_CARD: El widget queda configurado para realizar la captura de documentos de identidad.
SelphIDDocumentType.PASSPORT: El widget queda configurado para realizar la captura de pasaportes.
SelphIDDocumentType.DRIVERS_LICENSE: El widget queda configurado para realizar la captura de licencias de conducción.
SelphIDDocumentType.FOREIGN_CARD: El widget queda configurado para realizar la captura de documentos extranjeros.
SelphIDDocumentType.CUSTOM: El widget queda configurado para realizar la captura de otro tipo de documentos que no corresponden a ninguna de las categorias anteriores.
DocumentSide
Los valores permitidos son los siguientes:
SelphIDDocumentSide.FRONT: El widget queda configurado para realizar la captura de la parte frontal del documento.
SelphIDDocumentSide.BACK: El widget queda configurado para realizar la captura de la parte trasera del documento.
SelphIDDocumentSide.ALL: El widget queda configurado para realizar la captura de ambas partes del documento.
Timeout
Es un enumerado que define el timeout de la captura de un lado del documento. Tiene 3 posibles valores:
SelphIDTimeout.SHORT: 15 segundos.
SelphIDTimeout.MEDIUM: 20 segundos.
SelphIDTimeout.LONG: 25 segundos.
SelphIDTimeout.VERY_LONG: 60 segundos.
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.
DocumentModels
Esta propiedad permite, mediante una cadena en formato xml, configurar modelado de los documentos que el widget va a tratar de capturar. La definición de este modelado se encentra, por defecto, en un .xml de modelos que se encuentra en el .zip de recursos. Con esta propiedad se permite a una aplicación actualizar, en caliente, los modelados de los documentos.
Nota: Esta propiedad no altera el contenido del archivo de recursos.
generateRawImages
Esta propiedad configura el widget para devolver la imagen completa de la cámara que se utilizó para capturar el documento. Estas imágenes se devuelven en las propiedades rawFrontDocument y rawBackDocument del objeto results respectivamente.
tokenPreviousCaptureData
Cuando la captura del documento se realiza en 2 llamadas, esta propiedad permite pasar un diccionario con la información de la captura previa. De esta manera el widget puede combinar los resultados de ambas lecturas de una manera inteligente y así devolver la información combinada de ambas capturas. También permite al widget calcular un grado de similitud de los datos de ambas caras.
En el caso que la captura de ambas caras del documento se realice en una única llamada esto no es necesario ya que el widget internamente hace este proceso.
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.
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.
showDiagnostic
Mostrar pantallas de diagnóstico al final del proceso
showPreviousTip
Muestra una pantalla previa al lanzamiento de la captura con información sobre el proceso a realizar y un botón para el lanzamiento.
vibrationEnabled
Indica si se desea un feedback de vibración al acabar el proceso.
Personalización del componente
Aparte de los cambios que se pueden realizar a nivel de SDK (los cuales se explican en el documento de Personalización del SDK), este componente en concreto permite la modificación de su interfaz.
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.
Name
Value
selphid_component_tutorial_message_1
Busca un fondo con buen contraste.
selphid_component_tutorial_message_2
Coloca el documento dentro del recuadro.
selphid_component_tutorial_message_3
Evita brillos que dificulten la lectura del documento.
selphid_component_tip_message
Enfoca tu documento dentro del recuadro. La foto se hará automáticamente.
selphid_component_tip_title
Foto del documento
selphid_component_tip_button
COMENZAR
selphid_component_tip_close_button_alt
VOLVER
selphid_component_tip_button_alt
Comenzar captura de documento
selphid_component_tip_anim_id_alt
Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical.
selphid_component_tip_anim_passport_alt
Animación de un teléfono móvil haciendo una foto a un pasaporte. El documento aparece en horizontal, abierto por la página donde aparece la foto. El móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando la página del pasaporte encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tip_anim_driving_alt
Animación de un teléfono móvil haciendo una foto a un carné de conducir. El documento aparece en horizontal, y el móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando el documento encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tutorial_1_anim_id_alt
Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical.
selphid_component_tutorial_2_anim_id_alt
Coloca el documento en una superficie con un color distinto al documento.
selphid_component_tutorial_3_anim_id_alt
Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical.
selphid_component_tutorial_1_anim_pass_alt
Se muestra un pasaporte de color blanco, sobre un fondo blanco. Los bordes del documento no se distinguen con claridad. Mediante una animación, el fondo cambia de color.
selphid_component_tutorial_2_anim_pass_alt
Un teléfono móvil hace una foto a un pasaporte. El documento aparece en horizontal, y el móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando el documento encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tutorial_3_anim_pass_alt
Un pasaporte, visto de frente. Al inclinarlo, aparecen reflejos sobre el documento.
selphid_component_tutorial_1_anim_driving_alt
Se muestra un carné de conducir de color blanco, sobre un fondo blanco. Los bordes del documento no se distinguen con claridad. Mediante una animación, el fondo cambia de color.
selphid_component_tutorial_2_anim_driving_alt
Un teléfono móvil hace una foto a un carné de conducir. El documento aparece en horizontal, y el móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando el documento encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tutorial_3_anim_driving_alt
Un carné de conducir, visto de frente. Al inclinarlo, aparecen reflejos sobre el documento.
selphid_component_tip_health_alt
Animación de un teléfono móvil haciendo una foto a una tarjeta sanitaria. El documento aparece en horizontal, y el móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando el documento encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tutorial_1_anim_health_alt
Se muestra una tarjeta sanitaria de color blanco, sobre un fondo blanco. Los bordes del documento no se distinguen con claridad. Mediante una animación, el fondo cambia de color.
selphid_component_tutorial_2_anim_health_alt
Un teléfono móvil hace una foto a una tarjeta sanitaria. El documento aparece en horizontal, y el móvil en posición vertical. En la pantalla del móvil aparece un recuadro. Cuando el documento encaja dentro del recuadro, la aplicación hace una foto.
selphid_component_tutorial_3_anim_health_alt
Una tarjeta sanitaria, visto de frente. Al inclinarlo, aparecen reflejos sobre el documento.
selphid_component_tip_custom_alt
selphid_component_tutorial_1_anim_custom_alt
selphid_component_tutorial_2_anim_custom_alt
selphid_component_tutorial_3_anim_custom_alt
selphid_component_timeout_title
Tiempo superado
selphid_component_timeout_front_desc
Comprueba que el frente del documento está dentro del recuadro y los datos son visibles.
selphid_component_timeout_back_desc
Comprueba que el dorso del documento está dentro del recuadro y los datos son visibles.
selphid_component_timeout_desc
Comprueba que el documento está dentro del recuadro y los datos son visibles.
De este modo, si se desea modificar por ejemplo el texto “COMENZAR” de la clave selphid_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:
"selphid_component_tip_button_message"="EMPEZAR";
Si un mensaje no se especifica en el fichero del idioma, este se rellenará con el mensaje por defecto.
Animaciones
Las animaciones del Tip Previo y Tutoriales son lotties (json) las cuales pueden ser sustituidas por otras siempre respetando el nombre.
Para sustituirlas es necesario añadirlas en la carpeta Resources de la aplicación, siempre respetando el nombre, como se ha dicho anteriormente.
En caso de no sustituir dichas animaciones, se mostraran las animaciones por defecto.
Las animaciones son las siguientes:
selphid_anim_tip_id_male
Animación para el tip previo del documento de identidad
selphid_anim_tip_pass_male
Animacion para el tip previo del pasaporte
selphid_anim_tip_driver_male
Animacion para el tip previo de la licencia de conducir
selphid_anim_tuto_id_1
Primera animación del tutorial del documento de identidad
selphid_anim_tuto_id_2
Segunda animación del tutorial del documento de identidad
selphid_anim_tuto_id_3
Tercera animación del tutorial del documento de identidad
selphid_anim_tuto_pass_1
Primera animación del tutorial del pasaporte
selphid_anim_tuto_pass_2
Segunda animación del tutorial del pasaporte
selphid_anim_tuto_pass_3
Tercera animación del tutorial del pasaporte
selphid_anim_tuto_driving_1
Primera animación del tutorial de la licencia de conducir
selphid_anim_tuto_driving_2
Segunda animación del tutorial de la licencia de conducir
selphid_anim_tuto_driving_3
Tercera animación del tutorial de la licencia de conducir
selphid_anim_tuto_custom_1
Primera animacion del tutorial para un documento customizado
selphid_anim_tuto_custom_2
Segunda animacion del tutorial para un documento customizado
selphid_anim_tuto_custom_3
Tercera animacion del tutorial para un documento customizado
Last updated