NFC Capture

Introduction

Face Capture is performed with the NFC Component.

This component is responsible for reading NFC from identity documents and passports. Its main processes are:

• Internal management of the NFC sensor.

• Permission management.

• Document analysis.

• Progress analysis.

• Assistant in the reading processes.

• Return all possible information to be read

• Return images when they are available for reading

In the section of Simplified Launch the steps necessary for the basic integration of the SDK are detailed. In this section, information is added for launching this component.

Dependency

The specific dependency for the component is:

implementation "com.facephi.androidsdk:nfc_component:$sdk_nfc_component_version"{
      exclude group : "org.bouncycastle", module : "bcprov-jdk15on"
      exclude group : "org.bouncycastle", module : "jetified-bcprov-jdk15on-1.68"
  }

In addition, the following must be added to Gradle:

android {
  ...
 packaging {
      resources {
          pickFirsts.add("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
      }
  }
}

Available controllers

Controller	Description
NFCController	Main NFC reading controller

Simplified Launch

Once the SDK has been initialized and a new operation has been created, the component can be launched. Any of its controllers can be used to execute its functionality.

Starting the capture:

val response = SDKController.launch(
    NfcController(
        componentData = NfcConfigurationData(...),
        state = { state ->
            Napier.d("NFC: State: ${state.name}")
        },
        debugLogs = {
            Napier.d("NFC Logs: $it")
        }
    )
)
when (response) {
    is SdkResult.Error -> Napier.d("NFC: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

Basic configuration

To launch the current component, an object must be created NFCConfigurationData which will be the configuration of the component controller.

The basic configuration required for it is as follows:

NfcConfigurationData(
    documentNumber = NFC_SUPPORT_NUMBER, // Num soport.
    birthDate = NFC_BIRTH_DATE, // "dd/MM/yyyy"
    expirationDate = NFC_EXPIRATION_DATE, // "dd/MM/yyyy",
)

The required data are those of the document to be captured.

Receiving the result

The launch will return the information in SdkResult format. It can distinguish between a successful and unsuccessful launch:

when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}

Receiving errors

The errors will be returned as an 'NfcError' object.

List of errors:

• NFC_APPLICATION_CONTEXT_ERROR: The required application context is null.

• NFC_CANCEL_BY_USER: The user has canceled the process.

• NFC_CANCEL_LAUNCH: A general SDK cancellation has been made.

• NFC_COMPONENT_LICENSE_ERROR: The component license is not correct.

• NFC_EMPTY_LICENSE: The license String is empty.

• NFC_EXTRACT_DATA_ERROR: Error in the extracted data.

• NFC_FETCH_DATA_ERROR: Error in retrieving the result.

• NFC_FLOW_ERROR: Error in the flow process.

• NFC_INITIALIZATION_ERROR: Initialization error.

• NFC_LAST_COMMAND_EXPECTED: Error in the finalization command

• NFC_MANAGER_NOT_INITIALIZED: The managers are null.

• NFC_NO_DATA_ERROR: The input data are null or no reading result has been received.

• NFC_ERROR: General error

• NFC_ERROR_DATA: Error in the input data

• NFC_ERROR_DISABLED: NFC disabled

• NFC_ERROR_ILLEGAL_ARGUMENT: NFC with an incorrect tag

• NFC_ERROR_IO: Input/output error

• NFC_ERROR_NOT_SUPPORTED: NFC not supported

• NFC_ERROR_TAG_LOST: Connection lost

• NFC_OPERATION_NOT_CREATED: There is no operation in progress.

• NFC_TIMEOUT: Timeout in the process.

Receipt of the correct result - data

In the SdkResult.Success part - data, we will have the class NfcResult.

The result returns the images in format SdkImage, it is possible to extract the bitmap by accessing image.bitmap. If you want to convert it to base64, you can use the function:

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

The encrypted fields in the result are added starting with version 2.6.0

The fields returned in the result are as follows:

nfcRawData

Information obtained for each data type in raw format.

nfcDocumentInformation

Information obtained from the document sorted by:

• documentNumber

• expirationDate

• issuer

• mrzString

• type

nfcPersonalInformation

Information obtained from the document sorted by:

• address

• birthdate

• city

• gender

• name

• nationality

• personalNumber

• placeOfBirth

• surname

nfcImages

Image information obtained from the document sorted by:

• facialImage

• fingerprintImage

• signatureImage

• tokenFacialImage

• tokenSignatureImage

nfcSecurityData

Security data information from the document sorted by:

• dataGroupsHashes

• dataGroupsRead

• documentSigningCertificateData

• issuerSigningCertificateData

• ldsVersion

nfcValidations

Validation information from the document sorted by:

• accessType

• activeAuthenticationSupported

• activeAuthenticationValidation

• chipAuthenticationSupported

• chipAuthenticationValidation

• dataGroupsHashesValidation

• documentSigningValidation

• issuerSigningValidation

tokenOcr

Encrypted OCR data

Advanced information

This section expands the component information.

Advanced component configuration

To launch the current component, an object must be created NFCConfigurationData which will be the configuration of the component controller.

Below are all the fields that are part of this class.

documentNumber

Indicates the document number or support number depending on the document to be read.

This field is mandatory.

birthDate

Indicates the date of birth that appears in the document ("dd/MM/yyyy").

This field is mandatory.

expirationDate

Indicates the expiration date that appears in the document ("dd/MM/yyyy").

This field is mandatory.

extractionTimeout

Sets the maximum time allowed for reading.

showReadingScreen

Sets whether you want to show the lower modal screen with the reading being performed. If it is disabled, no view is shown and you must listen to the states returned by the controller.

showTutorial

Indicates whether the component enables the tutorial screen. In this view, how capture is performed is explained intuitively.

vibrationEnabled

Indicates whether vibration feedback is desired when the process ends.

skipPace

Indicates that only NFC BAC reading is desired. It is a reading with simpler and faster information that allows reading a wider variety of documents.

showDiagnostic

Show diagnostic screens at the end of the process

extractFacialImage

Indicates whether you want to extract the face image.

extractSignatureImage

Indicates whether you want to extract the signature image.

documentType

Field used to change the tutorial view and make it show the different documents.

showPreviousTip

Shows a screen before capture launch with information about the process to be carried out and a button to launch it.

readingProgressStyle

Style change on the document reading screen:

• ReadingProgressStyle.DOTS: The progress is visually marked with dots

• ReadingProgressStyle.PERCENTAGE: The progress is shown with a percentage

---

Component customization

Apart from the changes that can be made at the SDK level (which are explained in the document of SDK Customization), this particular component allows modification of its interface.

Texts

Texts can be customized by adding an XML resource file to the client application and overriding the default values.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="nfc_widget_previous_tip_title_passport">NFC Reader</string>
    <string name="nfc_widget_previous_tip_title_id">NFC Reader</string>
    <string name="nfc_widget_previous_tip_description">&lt;b&gt;Attach&lt;/b&gt; the document to the back of your device.</string>
    <string name="nfc_widget_start_button">Start</string>
    <string name="nfc_widget_tutorial_button">Check out these tips</string>
    <string name="nfc_widget_close_button">Close</string>
    <string name="nfc_widget_info_button">More information</string>
    <string name="nfc_widget_previous_tip_animation_desc">NFC previous tips</string>
    <string name="nfc_widget_mandatory_tutorial_title">NFC Reader</string>
    <string name="nfc_widget_tutorial_tip_1">When we pass a card through a sensor, there is an exchange of information called NFC.</string>
    <string name="nfc_widget_tutorial_tip_2">On your mobile, the sensor is in the marked area. Here you must gather your document.</string>
    <string name="nfc_widget_tutorial_tip_3_passport">Keep &lt;b&gt; closed &lt;/b&gt; the passport to do the reading.</string>
    <string name="nfc_widget_tutorial_tip_3_id">For a better reading, remove the cover of your mobile.</string>
    <string name="nfc_widget_ready_to_scan">Ready to scan</string>
    <string name="nfc_widget_reading_device">Reading device</string>
    <string name="nfc_widget_start_message">Attach the chip to your mobile.\nWhen it detects it, hold it still.</string>
    <string name="nfc_widget_reading_message">Hold the position.</string>
    <string name="nfc_widget_reading_document_message">Extracting document data.</string>
    <string name="nfc_widget_reading_images_message">Extracting images.</string>
    <string name="nfc_widget_close_alt">Close process</string>
    <string name="nfc_widget_reading_title">Reading NFC chip</string>
    <string name="nfc_widget_reading_animation_desc">NFC reading animation</string>
    <string name="nfc_widget_cancel_button">Cancel</string>
    <string name="nfc_widget_success_title">Reading finished</string>
    <string name="nfc_widget_success_document_prefix">Document:</string>
    <string name="nfc_widget_success_animation_desc">Reading completed</string>
    <string name="nfc_widget_error_title">Reading incomplete</string>
    <string name="nfc_widget_error_animation_desc">Reading cancelled</string>
    <string name="nfc_widget_retry_button">Retry</string>
    <string name="nfc_widget_close_action">Close</string>
    <string name="nfc_widget_cancelled_title">NFC flow cancelled</string>
    <string name="nfc_widget_cancelled_desc">Close the view to continue.</string>
    <string name="nfc_widget_cancelled_animation_desc">NFC flow cancelled</string>
    <string name="nfc_widget_timeout_title">Follow the instructions</string>
    <string name="nfc_widget_timeout_desc">Join the document &lt;b&gt;after&lt;/b&gt; clicking on the &lt;b&gt;Start button.&lt;/b&gt;</string>
    <string name="nfc_widget_tag_lost_title">Reading not finished</string>
    <string name="nfc_widget_tag_lost_desc">Hold the position until the end of the reading</string>
    <string name="nfc_widget_data_error_title">Document could not be read</string>
    <string name="nfc_widget_data_error_desc">Review the data entered</string>
    <string name="nfc_widget_internal_error_title">There was a technical problem</string>
    <string name="nfc_widget_internal_error_desc">We apologize. The capture could not be made</string>
    <string name="nfc_widget_state_waiting_for_tag">Slide the document until the sensor detects it.</string>
    <string name="nfc_widget_state_preparing">Preparing chip reading...</string>
    <string name="nfc_widget_state_secure_access">Validating secure document access...</string>
    <string name="nfc_widget_state_reading_data">Reading document data...</string>
    <string name="nfc_widget_state_reading_images">Reading document images...</string>
    <string name="nfc_widget_state_io_error">A communication issue with NFC was detected.</string>
    <string name="nfc_widget_state_finished">Reading completed.</string>
</resources>

Animations

If you want to modify the SDK animations (lottie), you should include the animations with the same name in the application's res/raw/ folder.

nfc_anim_reader.json
nfc_anim_tuto_1.json
nfc_anim_tuto_2.json
nfc_anim_tuto_3.json
nfc_anim_tuto_3_pass.json
nfc_anim_tuto_id.json
nfc_anim_tuto_passport.json

External views

It is possible to modify the component's bottom reading screens while maintaining their functionality and navigation. Starting with version 2.8.0, external customization is limited to the reading bottom sheets; the legacy previous-tip and diagnostics views are no longer part of the public contract. To do this, the following interfaces must be implemented:

Reading dialog screens:

interface INfcWaitingBottomView {
    @Composable
    fun Content(
        onClose: () -> Unit,
    )
}

interface INfcReadingBottomView {
    @Composable
    fun Content(
        state: NfcReadState,
        onClose: () -> Unit
    )
}

interface INfcSuccessBottomView {
    @Composable
    fun Content(
        onContinue: () -> Unit,
    )
}

interface INfcErrorBottomView {
    @Composable
    fun Content(
        error: NfcError,
        onContinue: () -> Unit,
    )
}

Once the classes implementing the interfaces have been created, at component launch the "customViews" parameter can be added so they are used in the SDK.