> 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/ios-sdk/modulos/captura-de-nfc.md).

# NFC Capture

This component requires iOS 13 or later.

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

The *component* discussed in this document is called the ***NFC Component***. It is responsible for reading NFC data from identity documents and passports. Its main features are as follows:

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

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

## Dependencies <a href="#id-21-dependencias-requeridas-para-la-integracion" id="id-21-dependencias-requeridas-para-la-integracion"></a>

To avoid conflicts and compatibility issues, if you want to install the component in a project that contains an older version of the Facephi libraries (*Widgets*), these must be completely removed before installing the ***SDKMobile***.

### **CocoaPods**

* The required dependencies that must be installed beforehand (by adding them to the project's Podfile) are:

```
pod 'FPHISDKMainComponent', '~> $SDK_VERSION'
```

* To install the NFC component, add the following entry to the application's Podfile:

```
pod 'FPHISDKNFCComponent', '~> $NFC_VERSION'
```

### **SPM**

* The required dependencies that must be installed beforehand are:

```
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git

```

* To install the NFC component, it must be added to the project's modules:

```
//HTTPS
https://github.com/facephi-clienters/SDK-NFC_component-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-NFC_component-SPM.git
```

## Available controllers <a href="#id-4-controladores-disponibles" id="id-4-controladores-disponibles"></a>

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

## Simplified Launch

Once the SDK has been initialized and a new operation has been created, you can launch the component. You can use any of its controllers to run its functionality.

Launching the capture:

```swift
let controller = NfcController(data: nfcConfigurationData, viewController: viewController,  output: { sdkResult in
        // Do whatever with the result
        ...
    }, stateDelegate: nil)
SDKController.shared.launch(controller: controller)
```

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

To launch this component, create an object of type *NFCConfigurationData* which will configure the component's controller.

The basic configuration required is as follows:

```swift
static var nfcConfiguration: NfcConfigurationData {
        return NfcConfigurationData(documentNumber: // Document number,
                                    birthDate: // "dd/MM/yyyy",
                                    expirationDate: // "dd/MM/yyyy")
}
```

The required data is that of the document to be captured.

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

The controllers return the required information in SdkResult format.

### Error handling <a href="#id-71-recepcion-de-errores" id="id-71-recepcion-de-errores"></a>

Regarding errors, **internally** we use the NFCPassportReaderError class. This enumeration contains many specific errors that provide no useful information if returned to the integrator, so they are converted to a simpler type (**ErrorType**):

* NFC\_CANCEL\_BY\_USER: The user canceled the process.
* NFC\_COMPONENT\_LICENSE\_ERROR: The component license is invalid.
* NFC\_EMPTY\_LICENSE: The license string is empty.
* NFC\_EXTRACT\_DATA\_ERROR: Error in the extracted data.
* NFC\_INITIALIZATION\_ERROR: Initialization error.
* NFC\_LAST\_COMMAND\_EXPECTED: Error in the completion command
* NFC\_ERROR: General error
* NFC\_ERROR\_DATA: Error in the input data
* NFC\_ERROR\_DISABLED: NFC is disabled
* NFC\_ERROR\_ILLEGAL\_ARGUMENT: NFC with an incorrect tag
* NFC\_ERROR\_IO: Input/output error
* NFC\_ERROR\_NOT\_SUPPORTED: NFC is not supported
* NFC\_ERROR\_TAG\_LOST: Connection lost
* NFC\_OPERATION\_NOT\_CREATED: There is no operation in progress.
* NFC\_TIMEOUT: Timeout during the process.

**NOTE**: `NFC_INVALID_MRZ_KEY` *means that the connection could not be established because the configuration input data (documentNumber, birthDate, expiryDate) is incorrect. All read attempts for that NFC will fail until a new NFCController is initialized with the correct data.*

### Successful execution response - *data* <a href="#id-72-recepcion-de-ejecucion-correcta-data" id="id-72-recepcion-de-ejecucion-correcta-data"></a>

For *data*, we have the *NfcResult*.

```
public class NfcResult {
    public let nfcRawData: NfcRawData
    public private(set) var nfcDocumentInformation: NfcDocumentInformation?
    public private(set) var nfcPersonalInformation: NfcPersonalInformation?
    public let nfcImages: NfcImages?
    public let nfcSecurityData: NfcSecurityData
    public private(set) var nfcValidations: NfcValidations?
}

extension NfcResult {
    public var personalData: [String: String]
    {
        ...
    }
}
```

For this component, the returned fields are as follows:

**nfcRawData**

Data obtained for each data type in raw format.

**nfcDocumentInformation**

Document information, organized by:

* type
* documentNumber
* issuer
* expirationDate
* mrzString

**nfcPersonalInformation**

Document information, organized by:

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

**nfcImages**

Document image information, ordered by:

* facialImage
* fingerprintImage
* signatureImage

**nfcSecurityData**

Document security data information, ordered by:

* ldsVersion
* dataGroupsHashes
* dataGroupsRead
* documentSigningCertificateData
* issuerSigningCertificateData

**nfcValidations**

Document validation information, ordered by:

* accessProtocol
* activeAuthenticationSupported
* activeAuthenticationValidation
* chipAuthenticationValidation
* dataGroupsHashesValidation
* documentSigningValidation
* issuerSigningValidation

**personalData**

* issuer
* documentNumber
* issueDate
* expiryDate
* name
* surname
* fullName
* gender
* birthDate
* birthPlace
* nationality
* address
* nfcKey
* numSupport
* MRZ

## Advanced information

This section provides additional information about the component.

### Advanced component configuration <a href="#id-51-class-nfcconfigurationdata" id="id-51-class-nfcconfigurationdata"></a>

To launch this component, create an object of type *NFCConfigurationData* which will configure the component's controller.

All the fields that are part of this class are described 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 reading.

**showTutorial**

Specifies whether the component displays the tutorial screen. This screen intuitively explains how to capture the document.

**vibrationEnabled**

iOS does not allow vibration to be enabled during NFC reads.

**enableDebugMode**

Enables the component's debug mode.

**skipPace**

Specifies that only NFC BAC reading is desired. This read provides simpler and faster access to information and supports a wider variety of documents.

**showDiagnostic**

If set to true, when an error occurs or permissions are missing, the SDK will display a screen with the error returned by the Widget.

**issuer**

Specifies the country of origin of the document to be read.

**documentType**

Specifies the type of document to be read: - ID\_CARD - PASSPORT - FOREIGN\_CARD

**activeAuthenticationChallenge**

This parameter lets you inject a custom challenge that can be checked later to protect against replay attacks.

**onlyPACE**

If true, only PACE/SAC documents will be detected. Available only from iOS ≥ 16. Requires the PACE string in the *entitlements*.

**tagConnectionLostTimer**

Previously, there was a single timer that could span multiple requests when the response was large.

## Component customization

In addition to the changes that can be made at the SDK level (which are explained in the document on *SDK Customization*), this particular component also allows its interface to be modified.

### Text

The text can be customized by overriding the values of the following keys in a **Localizable.strings**. Keys with the suffix ***\_alt*** are the strings used in the accessibility labels required for the ***VoiceOver***.

| **Name**                                                                                        | **Value**                                                                              |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| nfc\_component\_start\_message                                                                  | \nMove the document\nuntil the device detects it\n                                     |
| nfc\_component\_reading\_face\_message                                                          | Extracting face image.                                                                 |
| nfc\_component\_reading\_images\_message                                                        | Extracting images.                                                                     |
| nfc\_component\_reading\_document\_message                                                      | Extracting document data.                                                              |
| nfc\_component\_error\_retrieving\_document\_data\_message                                      | An error occurred while capturing the document data                                    |
| nfc\_component\_read\_successful\_title                                                         | NFC read successfully                                                                  |
| nfc\_component\_error                                                                           | Oops! NFC could not be read                                                            |
| text\_error\_tag\_connection\_lost                                                              | Reading interrupted. Place the document back on top.                                   |
| text\_error\_tag\_connection\_lost\_timer                                                       | An error occurred while reading. Please cancel to restart the process.                 |
| nfc\_component\_timeout\_desc                                                                   | You have exceeded the NFC reading time limit. Please try again                         |
| text\_chip\_duplicated\_session\_error                                                          | The capture process has been duplicated. Please try again once this message disappears |
| text\_chip\_security\_serial\_number\_title                                                     | Serial number                                                                          |
| text\_chip\_security\_algorithm\_sign\_title                                                    | Signature algorithm                                                                    |
| text\_chip\_security\_algorithm\_public\_key\_title                                             | Public key algorithm                                                                   |
| text\_chip\_security\_certificated\_impress\_title                                              | Certificate fingerprint                                                                |
| text\_chip\_security\_editor\_title                                                             | Issuer                                                                                 |
| text\_chip\_security\_subject\_title                                                            | Subject                                                                                |
| text\_chip\_security\_valid\_from\_title                                                        | Valid from                                                                             |
| text\_chip\_security\_valid\_still\_title                                                       | Valid until                                                                            |
| text\_loading\_optional\_description                                                            | Reading, please do not move the document                                               |
| icon\_loading\_filled\_circle                                                                   | 🟢                                                                                     |
| icon\_loading\_void\_circle                                                                     | ⚪️                                                                                     |
| nfc\_component\_end\_confirmation\_title                                                        | End                                                                                    |
| nfc\_component\_end\_confirmation\_message                                                      | Are you sure you want to end the process?                                              |
| nfc\_component\_cancel                                                                          | Cancel                                                                                 |
| nfc\_component\_agree                                                                           | Accept                                                                                 |
| nfc\_component\_tutorial                                                                        | Place **in contact** the document against the back of your device.                     |
| nfc\_component\_tutorial\_iphone\_15                                                            | Place **in contact** the document with the front of your device.                       |
| text\_tutorial\_nfc\_title                                                                      | NFC reading                                                                            |
| text\_tutorial\_nfc\_button\_ok                                                                 | START                                                                                  |
| text\_tutorial\_nfc\_button\_tip                                                                | CHECK OUT THESE TIPS                                                                   |
| nfc\_component\_tutorial\_title                                                                 | Scan NFC                                                                               |
| nfc\_component\_tutorial\_button\_disabled                                                      | PREPARING NFC                                                                          |
| nfc\_component\_tutorial\_1                                                                     | When we hold a card up to a sensor, an exchange of information called NFC takes place. |
| On your phone, the sensor is in the marked area. You should hold your document against it here. | nfc\_component\_tutorial\_2                                                            |
| nfc\_component\_tutorial\_3                                                                     | For better reading, remove your phone case.                                            |
| nfc\_component\_tutorial\_3\_pass                                                               | Keep **closed** the passport while it is being read.                                   |
| nfc\_component\_next                                                                            | NEXT                                                                                   |
| nfc\_component\_previous                                                                        | PREVIOUS                                                                               |
| nfc\_component\_more\_info\_finish                                                              | FINISH                                                                                 |
| diagnostic\_tag\_connection\_lost\_title                                                        | Reading was not completed                                                              |
| diagnostic\_tag\_connection\_lost\_description                                                  |                                                                                        |

This way, if you want to change, for example, the text “*START*” for the key `text_tutorial_nfc_button_ok` for the language **es-MX**, go to the file **Localizable.strings** in the folder **es-MX.lproj** if it exists (if not, create it), and add:

`"text_tutorial_nfc_button_ok"="EMPEZAR";`

If a message is not specified in the language file, the default message will be used.

### Animations <a href="#id-84-animaciones" id="id-84-animaciones"></a>

Animations are initialized similarly in the animations variable using a dictionary, with a string containing the name of the desired animation found in xcassets as the value.

```
case nfc_anim_tuto_id_male
case nfc_anim_tuto_id_male_iphone_15
case nfc_anim_tuto_id_female
case nfc_anim_tuto_passport
case nfc_anim_tuto_1
case nfc_anim_tuto_2
case nfc_anim_tuto_2_iphone_15
case nfc_anim_tuto_3
case nfc_anim_tuto_3_pass
```

<br>
