NFC Capture
This component requires a minimum iOS13 version
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 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:
SPM
The mandatory dependencies that must have been installed previously are:
To install the NFC component, it must be included in the project modules:
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:
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:
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.
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.
Last updated