> 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 ### Introduction The *Component* the one addressed in the current document is called ***NFC Component***. It is responsible for performing NFC reading of identity documents and passports. Its main functionalities are the following: * Internal management of the NFC sensor. * Permission management. * Document analysis. * Progress analysis. * Assistant in the reading processes. * Return of all possible information to read * Return of images when they are available for reading In the section of [Simplified Launch](/docs.facephi-en/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) the necessary steps for the basic integration of the SDK are detailed. In this section, information is added for the launch of this component. ## Dependencies To avoid conflicts and compatibility issues, if you want to install the component in a project that contains an old version of the Facephi libraries (*Widgets*), they must be completely removed before installing the components of the ***SDKMobile***. ### **CocoaPods** * The required dependencies that must have been installed previously (by adding them to the project's Podfile) are: ``` pod 'FPHISDKMainComponent', '~> $SDK_VERSION' ``` * To install the NFC component, the following entry must be included in the application's Podfile: ``` pod 'FPHISDKNFCComponent', '~> $NFC_VERSION' ``` ### **SPM** * The mandatory dependencies that must have been installed previously 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 included in the project 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 | **Controller** | **Description** | | -------------- | --------------------------- | | NFCController | Main NFC reading controller | ## Simplified Launch Once the SDK has been started and a new operation has been created, the component can be launched. Any of its controllers can be used to execute its functionality. Capture launch: ```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 To launch the current component, an object *NFCConfigurationData* must be created, which will be the configuration of the component controller. The basic configuration needed for this is as follows: ```swift static var nfcConfiguration: NfcConfigurationData { return NfcConfigurationData(documentNumber: // Num soporte, birthDate: // "dd/MM/yyyy", expirationDate: // "dd/MM/yyyy") } ``` The necessary data are those of the document that is going to be captured. ## Result reception The controllers will return the necessary information in SdkResult format. ### Error handling In the error part, **internally** we have the NFCPassportReaderError class. This enum contains many specific errors that do not provide useful information if returned to the integrator, so they are transformed into a simpler type (**ErrorType**): * NFC\_CANCEL\_BY\_USER: The user has canceled the process. * 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\_INITIALIZATION\_ERROR: Initialization error. * NFC\_LAST\_COMMAND\_EXPECTED: Error in the finalization command * 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. **NOTE**: `NFC_INVALID_MRZ_KEY` *means that the connection could not be established because the input data of the configuration (documentNumber, birthDate, expiryDate) are not correct. All reading launches for that NFC will fail until a new NFCController is initialized with the correct data.* ### Successful execution receipt - *data* In the *data*, we will have the class *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] { ... } } ``` In the case of this component, the returned fields are the following: **nfcRawData** Information obtained by each data type in raw format. **nfcDocumentInformation** Information obtained from the document ordered by: * type * documentNumber * issuer * expirationDate * mrzString **nfcPersonalInformation** Information obtained from the document ordered by: * name * surname * address * nationality * personalNumber * birthdate * placeOfBirth * gender **nfcImages** Image information obtained from the document ordered by: * facialImage * fingerprintImage * signatureImage **nfcSecurityData** Security data information from the document ordered by: * ldsVersion * dataGroupsHashes * dataGroupsRead * documentSigningCertificateData * issuerSigningCertificateData **nfcValidations** Information about the document validations 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 expands on the component information. ### Advanced component configuration To launch the current component, an object *NFCConfigurationData* must be created, 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 required. **birthDate** Indicates the birth date that appears on the document ("dd/MM/yyyy"). This field is required. **expirationDate** Indicates the expiration date that appears on the document ("dd/MM/yyyy"). This field is required. **extractionTimeout** Sets the maximum time allowed for reading. **showTutorial** Indicates whether the component activates the tutorial screen. In this view, it intuitively explains how the capture is performed. **vibrationEnabled** iOS does not allow vibration to be added while NFC readings are being performed. **enableDebugMode** Enables the component debug mode. **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** If set to true, when an error or a lack of permissions occurs, the sdk will show a screen with the error returned by the widget. **issuer** We indicate the country of origin of the document to be read. **documentType** Indicates the type of document to be read: - ID\_CARD - PASSPORT - FOREIGN\_CARD **activeAuthenticationChallenge** This parameter allows injecting a custom challenge that can later be checked to protect against replay attacks. **onlyPACE** If true, it will only detect PACE/SAC documents. Available only from iOS ≥ 16. Requires the PACE string in the *entitlements*. **tagConnectionLostTimer** Previously there was a single timer that could span more than one request when the response was large. ## Component Customization Besides the changes that can be made at SDK level (which are explained in the document of *SDK Customization*), this specific component allows its interface to be modified. ### Texts The texts can be customized by overriding the value of the following keys in a **Localizable.strings**. The keys containing the suffix ***\_alt*** are the literals used in the accessibility labels needed for the functionality of ***voice over***. | **Name** | **Value** | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | | nfc\_component\_start\_message | \nSwipe 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 the 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! The NFC could not be read | | text\_error\_tag\_connection\_lost | Reading interrupted. Put the document back on top. | | text\_error\_tag\_connection\_lost\_timer | There was an error 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 after 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 imprint | | 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 | Finish | | 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 | Put **in contact** the document against the back of your device. | | nfc\_component\_tutorial\_iphone\_15 | Put **in contact** the document against 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 pass a card over a sensor, there is an exchange of information called NFC. | | nfc\_component\_tutorial\_2 | On your phone, the sensor is in the marked area. Here you should place your document. | | nfc\_component\_tutorial\_3 | For a better reading, remove your phone case. | | nfc\_component\_tutorial\_3\_pass | Keep **closed** the passport to perform the reading. | | nfc\_component\_next | NEXT | | nfc\_component\_previous | PREVIOUS | | nfc\_component\_more\_info\_finish | FINISH | | diagnostic\_tag\_connection\_lost\_title | The reading did not finish | | diagnostic\_tag\_connection\_lost\_description | | In this way, if you want to modify, for example, the text “*START*” of the key `text_tutorial_nfc_button_ok` for the language **es-MX**, you will have to go to the file **Localizable.strings** in the folder **es-MX.lproj** if it exists (if not, it must be created) and there, add: `"text_tutorial_nfc_button_ok"="EMPEZAR";` If a message is not specified in the language file, it will be filled with the default message. ### Animations The animations to use are initialized similarly in the animations variable with a dictionary, having as value a string with the name of the animation found in xcassets that you want to use. ``` 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 ```