Version: 1.5.2

NFC 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 NFC Component. Éste se encarga de realizar la lectura de nfc de documentos de identidad y pasaportes. Sus principales funcionalidades son las siguientes:

Gestión interna del sensor de NFC.
Gestión de permisos.
Análisis de documento.
Análisis del progreso.
Asistente en los procesos de lectura.
Devolución de toda la información posible a leer
Devolución de imágenes cuando estén disponible para su lectura

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:nfc_component:$sdk_nfc_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


Controlador	Descripción
NFCController	Controlador principal de lectura NFC

5. Configuración del componente

Para configurar el componente actual, una vez inicializado, se deberá crear un objeto

NFCConfigurationData 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 NFCConfigurationData

5.1.1. documentNumber

Indica el número de documento o número de soporte dependiendo del documento a realizar la lectura.

Éste campo es obligatorio.

5.1.2. birthDate

Indica la fecha de nacimiento que aparece en el documento ("dd/MM/yyyy").

Éste campo es obligatorio.

5.1.3. expirationDate

Indica la fecha de expiración que aparece en el documento ("dd/MM/yyyy").

Éste campo es obligatorio.

5.1.4. extractionTimeout

Establece el tiempo máximo que se puede realizar la lectura.

5.1.5. showReadingScreen

Establece si se desea mostrar la pantalla modal inferior con la lectura que se está realizando. Si se desactiva, no se muestra ninguna vista y se deberán escuchar los estados que devuelve el controlador.

5.1.6. showTutorial

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

5.1.7. vibrationEnabled

Indica si se desea un feedback de vibración al acabar el proceso.

5.1.8. enableDebugMode

Activación del modo depuración del componente.

5.1.9. onlyBAC

Indica que solo se desea realizar la lectura BAC de NFC. Es una lectura con información más simple y rápida que permite la lectura de más variedad de documentos.

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(
    NfcController(
        componentData = NfcConfigurationData(
            documentNumber = NFC_SUPPORT_NUMBER, // Num soport.
            birthDate = NFC_BIRTH_DATE, // "dd/MM/yyyy"
            expirationDate = NFC_EXPIRATION_DATE, // "dd/MM/yyyy",
            ),
        state = { state ->
            Napier.d("NFC: State: ${state.name}")
        },
        debugLogs = {
            Napier.d("NFC Logs: $it")
        }
    ) {
        when (it) {
            is SdkResult.Error -> Napier.d("APP: NFC: KO - ${it.error.name}")
            is SdkResult.Success -> {
                Napier.d("APP: NFC: OK")
                Napier.d("DOCUMENT: ${it.data.nfcDocumentInformation}")
                Napier.d("PERSONAL: ${it.data.nfcPersonalInformation}")
            }
        }
    }
)

[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(
    NfcController(
        componentData = NfcConfigurationData(
            documentNumber = NFC_SUPPORT_NUMBER, // Num soport.
            birthDate = NFC_BIRTH_DATE, // "dd/MM/yyyy"
            expirationDate = NFC_EXPIRATION_DATE, // "dd/MM/yyyy",
            ),
        state = { state ->
            Napier.d("NFC: State: ${state.name}")
        },
        debugLogs = {
            Napier.d("NFC Logs: $it")
        }
    ) {
        when (it) {
            is SdkResult.Error -> Napier.d("APP: NFC: KO - ${it.error.name}")
            is SdkResult.Success -> {
                Napier.d("APP: NFC: OK")
                Napier.d("DOCUMENT: ${it.data.nfcDocumentInformation}")
                Napier.d("PERSONAL: ${it.data.nfcPersonalInformation}")
            }
        }
    }
)

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

    NfcError.ACTIVITY_RESULT_ERROR
    NfcError.CANCEL_BY_USER
    NfcError.INITIALIZATION_ERROR -> it.error // Para más detalles
    NfcError.NFC_ERROR
    NfcError.NFC_ERROR_DATA
    NfcError.NFC_ERROR_DISABLED
    NfcError.NFC_ERROR_ILLEGAL_ARGUMENT
    NfcError.NFC_ERROR_IO
    NfcError.NFC_ERROR_NOT_SUPPORTED
    NfcError.NFC_ERROR_READING
    NfcError.NFC_ERROR_TAG_LOST
    NfcError.NO_DATA_ERROR
    NfcError.TIMEOUT
    NfcError.LAST_COMMAND_EXPECTED

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

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

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

Información obtenida por cada tipo de dato en formato crudo.

7.2.2. nfcDocumentInformation

Información obtenida del documento ordenada por:

documentNumber
expirationDate
issuer
mrzString
type

7.2.3. nfcPersonalInformation

Información obtenida del documento ordenada por:

address
birthdate
city
gender
name
nationality
personalNumber
placeOfBirth
surname

7.2.4. nfcImages

Información de imágenes obtenida del documento ordenada por:

facialImage
fingerprintImage
signatureImage

7.2.5 nfcSecurityData

Información de datos de seguridad del documento ordenada por:

dataGroupsHashes
dataGroupsRead
documentSigningCertificateData
issuerSigningCertificateData
ldsVersion

7.2.6. nfcValidations

Información de las validaciones del documento ordenada por:

accessType
activeAuthenticationSupported
activeAuthenticationValidation
chipAuthenticationValidation
dataGroupsHashesValidation
documentSigningValidation
issuerSigningValidation

7.2.7. nfcCertificateData

Información del certificado X509 obtenido del documento ordenada por.

X509Certificate

8. Personalización del componente

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

8.1 Textos

Si se desea modificar los textos de la SDK habría que incluir el siguiente fichero XML en la aplicación del cliente, y modificar el valor de cada String por el deseado.

<string name="nfc_component_start_message">Attach the chip to your mobile.\nWhen it detects it, hold it still.</string>
<string name="nfc_component_ready_to_scan">Ready to scan</string>
<string name="nfc_component_reading_device">Reading device</string>
<string name="nfc_component_in_progress">In progress:</string>
<string name="nfc_component_connector_of">in</string>
<string name="nfc_component_error">The NFC could not be\nread correctly</string>
<string name="nfc_component_tutorial">Attach the document to the back of your device.</string>
<string name="nfc_component_tutorial_button">Continue</string>
<string name="nfc_component_tutorial_title">Scan NFC</string>
<string name="nfc_component_tutorial_1">When we pass a card through a sensor, there is an exchange of information called NFC.</string>
<string name="nfc_component_tutorial_2">On your mobile, the sensor is in the marked area. Here you must gather your document.</string>
<string name="nfc_component_tutorial_3">For a better reading, remove the cover of your mobile.</string>
<string name="nfc_component_tutorial_more_info_button">More info</string>

0. Requisitos base de SDK Mobile​

1. Introducción​

2. Integración del componente​

2.1. Dependencias requeridas para la integración​

3. Iniciar nueva operación​

4. Controladores disponibles​

5. Configuración del componente​

5.1. Class NFCConfigurationData​

5.1.1. documentNumber​

5.1.2. birthDate​

5.1.3. expirationDate​

5.1.4. extractionTimeout​

5.1.5. showReadingScreen​

5.1.6. showTutorial​

5.1.7. vibrationEnabled​

5.1.8. enableDebugMode​

5.1.9. onlyBAC​

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. nfcRawData​

7.2.2. nfcDocumentInformation​

7.2.3. nfcPersonalInformation​

7.2.4. nfcImages​

7.2.5 nfcSecurityData​

7.2.6. nfcValidations​

7.2.7. nfcCertificateData​

8. Personalización del componente​

8.1 Textos​

0. Requisitos base de SDK Mobile

1. Introducción

2. Integración del componente

2.1. Dependencias requeridas para la integración

3. Iniciar nueva operación

4. Controladores disponibles

5. Configuración del componente

5.1. Class NFCConfigurationData

5.1.1. documentNumber

5.1.2. birthDate

5.1.3. expirationDate

5.1.4. extractionTimeout

5.1.5. showReadingScreen

5.1.6. showTutorial

5.1.7. vibrationEnabled

5.1.8. enableDebugMode

5.1.9. onlyBAC

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

7.2.2. nfcDocumentInformation

7.2.3. nfcPersonalInformation

7.2.4. nfcImages

7.2.5 nfcSecurityData

7.2.6. nfcValidations

7.2.7. nfcCertificateData

8. Personalización del componente

8.1 Textos