> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-de-nfc.md).

# NFC Capture

## Introduction <a href="#id-1-introduccion" id="id-1-introduccion"></a>

NFC reading is performed with the ***NFC Component***.

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

* Internal management of the NFC sensor.
* Permission management.
* Document analysis.
* Progress analysis.
* Assistance with the reading processes.
* Returning all information that can be read
* Returning images when they are available to be read

The [Simplified Launch](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) section describes the steps required for basic SDK integration. This section provides information on launching this component.

## Dependency <a href="#id-2-dependencia" id="id-2-dependencia"></a>

The component’s specific dependency is:

```kts
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"
  }
```

You will also need to add the following to Gradle:

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

## Available controllers

| **Controller** | **Description**             |
| -------------- | --------------------------- |
| NfcController  | Main NFC reading controller |

## Simplified Launch <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

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:

<pre class="language-kotlin"><code class="lang-kotlin"><strong>val response = SDKController.launch(
</strong><strong>    NfcController(
</strong>        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
}
</code></pre>

## Basic configuration <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

To launch the current component, you must create an object of type *NfcConfigurationData* which will configure the component's controller.

The basic configuration required is as follows:

```kotlin
NfcConfigurationData(
    documentNumber = NFC_SUPPORT_NUMBER, // Support number
    birthDate = NFC_BIRTH_DATE, // "dd/MM/yyyy"
    expirationDate = NFC_EXPIRATION_DATE, // "dd/MM/yyyy",
)
```

The required data is the information from the document to be captured.

## Receiving the result <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

Launching the component returns the information in SdkResult format. The result can be either a successful or an unsuccessful launch:

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

### Receiving errors <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as an 'NfcError' object.

List of errors:

* `ACTIVITY_RESULT_MSG_ERROR` (`NFC_610`): Error in the activity result message.
* `APPLICATION_CONTEXT_ERROR` (`NFC_611`): The required application context is null.
* `CANCEL_BY_USER` (`NFC_000`): The user canceled the process.
* `CANCEL_LAUNCH` (`NFC_007`): The SDK was canceled in general.
* `COMPONENT_LICENSE_ERROR` (`NFC_002`): The component license is invalid.
* `EMPTY_LICENSE` (`NFC_003`): The license string is empty.
* `EXTRACT_DATA_ERROR` (`NFC_600`): Error in the extracted data.
* `FETCH_DATA_ERROR` (`NFC_601`): Error fetching the result.
* `FLOW_ERROR` (`NFC_617`): Error in the flow process.
* `FLOW_TRACKING_ERROR` (`NFC_615`): Error tracking the flow.
* `FLOW_VIDEO_RECORDING_ERROR` (`NFC_613`): Error recording video for the flow.
* `INITIALIZATION_ERROR` (`NFC_004`): Initialization error.
* `INTERNAL_ERROR` (`NFC_616`): Internal error.
* `LAST_COMMAND_EXPECTED` (`NFC_602`): Error in the completion command
* `MANAGER_NOT_INITIALIZED` (`NFC_612`): Managers are null.
* `NO_DATA_ERROR` (`NFC_005`): The input data is null, or no result was received from the read operation.
* `NFC_ERROR` (`NFC_603`): General error
* `NFC_ERROR_DATA` (`NFC_604`): Error in the input data
* `NFC_ERROR_DISABLED` (`NFC_605`): NFC is disabled
* `NFC_ERROR_ILLEGAL_ARGUMENT` (`NFC_606`): NFC with an invalid tag
* `NFC_ERROR_IO` (`NFC_607`): Input/output error
* `NFC_ERROR_NOT_SUPPORTED` (`NFC_608`): NFC not supported
* `NFC_ERROR_TAG_LOST` (`NFC_609`): Connection lost
* `OPERATION_NOT_CREATED` (`NFC_006`): No operation is in progress.
* `TIMEOUT` (`NFC_001`): Process timeout.
* `TRACKING_STEP_ERROR` (`NFC_614`): Error tracking a process step.

### Receiving the successful result - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

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

The result returns the images in **SdkImage**format; you can extract the bitmap by accessing *image.bitmap*. To convert it to base64, you can use the function:

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

{% hint style="info" %}
Encrypted fields in the result are included starting with version 2.6.0
{% endhint %}

The fields returned in the result are as follows:

**nfcRawData**

Information obtained for each data type in raw format, ordered by:

* comSdkModel
* dg1SdkModel
* dg2SdkModel
* dg3SdkModel
* dg4SdkModel
* dg5SdkModel
* dg7SdkModel
* dg11SdkModel
* dg12SdkModel
* dg13SdkModel
* dg14SdkModel
* dg15SdkModel

**nfcDocumentInformation**

Information obtained from the document, ordered by:

* documentNumber
* expirationDate
* issuer
* mrzString
* type

**nfcPersonalInformation**

Information obtained from the document, ordered by:

* address
* birthdate
* city
* gender
* name
* nationality
* personalNumber
* placeOfBirth
* surname

**nfcImages**

Image information obtained from the document, ordered by:

* facialImage
* signatureImage
* tokenFacialImage
* tokenSignatureImage

**nfcSecurityData**

Security data information from the document, ordered by:

* dataGroupsHashes
* dataGroupsRead
* documentSigningCertificateData
* issuerSigningCertificateData
* ldsVersion

**nfcValidations**

Document validation information, ordered by:

* accessType
* activeAuthenticationSupported
* activeAuthenticationValidation
* chipAuthenticationSupported
* chipAuthenticationValidation
* dataGroupsHashesValidation
* documentSigningValidation
* issuerSigningValidation

**tokenOCR**

Encrypted OCR data

## Advanced information <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

This section provides more information about the component.

### Advanced component configuration <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

To launch the current component, you must create an object of type *NfcConfigurationData* which will configure the component's controller.

All the fields that make up this class are detailed below.

**documentNumber**

Specifies the document number or support number, depending on the document being read.

This field is required.

**birthDate**

Specifies the date of birth shown on the document ("dd/MM/yyyy").

This field is required.

**expirationDate**

Specifies the expiration date shown on the document ("dd/MM/yyyy").

This field is required.

**extractionTimeout**

Sets the maximum time allowed for the reading process, in milliseconds. The default is 60000.

**showTutorial**

Specifies whether the component displays the tutorial screen. This screen intuitively explains how to capture the document. The default is true.

**vibrationEnabled**

Specifies whether to provide vibration feedback when the process ends. The default is true.

**skipPACE**

Specifies that only BAC NFC reading should be performed. This reading is simpler and faster, and supports a wider variety of documents. The default is false.

**showDiagnostic**

Display diagnostic screens at the end of the process. The default is true.

**extractFacialImage**

Specifies whether to extract the facial image. The default is true.

**extractSignatureImage**

Specifies whether to extract the signature image. The default is false.

**documentType**

Field used to change the tutorial screen so it displays different document types. It is optional (defaults to null), and the possible values are:

* NfcDocumentType.ID\_CARD
* NfcDocumentType.PASSPORT
* NfcDocumentType.FOREIGN\_CARD

**showPreviousTip**

Displays a screen before capture starts with information about the process and a button to start it. The default is true.

**readingProgressStyle**

Changes the style of the document-reading screen (defaults to ReadingProgressStyle.DOTS):

* ReadingProgressStyle.DOTS: Progress is shown visually using dots
* ReadingProgressStyle.PERCENTAGE: Progress is displayed as a percentage

***

## Component customization <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

In addition to the changes that can be made at the SDK level (explained in the document on [SDK Customization](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this particular component also allows its interface to be modified.

### Text <a href="#id-81-textos" id="id-81-textos"></a>

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

```kotlin
<?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 <a href="#id-82-animaciones" id="id-82-animaciones"></a>

To modify the SDK animations (Lottie), include animations with the same names 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
```
