Captura de documentos
1. Introducción
La captura de documentos se realiza con el SelphID Component.
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.
2. Dependencia
La dependencia específica del componente es:
implementation "com.facephi.androidsdk:selphid_component:$version"
3. Controladores disponibles
| Controlador | Descripción |
|---|---|
| SelphIDController | Controlador principal de reconocimiento de documentos |
4. 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.
Lanzamiento de la captura facial:
val response = SDKController.launch(
SelphIDController(SelphIDConfiguration(..))
)
when (response) {
is SdkResult.Error -> Napier.d("SelphID: ERROR - ${response.error.name}")
is SdkResult.Success -> response.data
}
5. Configuración básica
Para lanzar el componente actual, se deberá crear un objeto SelphiConfigurationData que será la configuración del controlador del componente.
La configuración básica necesaria para es la siguiente:
SelphIDConfiguration(
resourcesPath = "resources_file.zip",
wizardMode = true,
specificData = "ES|<ALL>",
documentType = SelphIDDocumentType.ID_CARD,
)
En el campo 'specificData' se deberá cambiar el código de país por el que corresponda (en este caso se está utilizando ES para España).
Los diferentes tipos de documento son:
- SelphIDDocumentType.ID_CARD
- SelphIDDocumentType.PASSPORT
- SelphIDDocumentType.DRIVERS_LICENSE
- SelphIDDocumentType.FOREIGN_CARD
- SelphIDDocumentType.CREDIT_CARD
- SelphIDDocumentType.CUSTOM
- SelphIDDocumentType.VISA
6. Recepción del resultado
El lanzamiento devolverá la información en formato SdkResult. Pudiendo diferenciarse entre un lanzamiento correcto y uno incorrecto:
when (response) {
is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
is SdkResult.Success -> response.data
}
6.1. Recepción de errores
Los errores se devolverán como un objeto 'SelphIdError'.
Listado de errores:
- SPD_ACTIVITY_RESULT_ERROR: El resultado de la actividad es incorrecto.
- SPD_ACTIVITY_RESULT_MSG_ERROR: El resultado de la actividad recibido en el msg es incorrecto.
- 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_FETCH_DATA_ERROR: Error en la recogida del resultado.
- SPD_FLOW_ERROR: Error en el proceso de flow.
- SPD_HARDWARE_ERROR: Widget: Error de hardware
- SPD_INITIALIZATION_ERROR: Error de inicialización.
- SPD_MANAGER_NOT_INITIALIZED: Los managers son nulos.
- 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
6.2. Recepción del resultado correcto - data
En la parte de SdkResult.Success - data, dispondremos de la clase SelphIDResult.
El resultado devuelve las imágenes en formato SdkImage, es posible extraer el bitmap accediendo a image.bitmap. Si se quisiera convertir a base64 se puede utilizar la función:
Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)
Los campos devueltos en el resultado son los siguientes:
6.2.1 frontDocument / tokenFrontDocument:
La imagen frontal del documento procesada, limpiada y recortada por los bordes y su token correspondiente.
6.2.2 backDocument / tokenBackDocument
La imagen trasera del documento procesada, limpiada y recortada por los bordes y su token asociado.
6.2.3 faceImage / tokenFaceImage
La imagen del rostro que se ha encontrado en el documento, en caso de que exista y su token asociado.
Válida para el proceso de MATCHING FACIAL.
6.2.4 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.
6.2.5 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.
6.2.6 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:
Front_Detection_None = 0
Front_Detection_Uncertain = 1
Front_Detection_Completed = 2
Front_Document_Analyzed = 3
Back_Detection_None = 4
Back_Detection_Uncertain = 5
Back_Detection_Completed = 6
Back_Document_Analyzed = 7
-
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.
6.2.7 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.
6.2.8 timeoutDiagnostic
Esta propiedad devuelve una cadena de texto que explica por qué se ha agotado el tiempo de espera del widget. Esta cadena puede ser utilizada en una pantalla de tiempo de espera posterior donde la aplicación principal puede dar más información al usuario sobre lo ocurrido durante la captura del documento.
6.2.9 countryCaptured
País del documento.
6.2.10 documentTypeCaptured
Tipo de documento. Se corresponde con los del apartado 5.1.10.
6.2.11 personalData
Conjunto reducido de datos obtenidos del usuario:
- issuer
- documentNumber
- issueDate
- expiryDate
- name
- surname
- fullName
- gender
- birthDate
- birthPlace
- nationality
- address
- nfcKey
- numSupport
- mrz
7. Información avanzada
Este apartado amplía la información del componente.