DOT iOS NFC Integration Manual
v9.2.3
Introduction
DOT iOS NFC provides a component for NFC reading which is easy to integrate into an iOS application. Supported documents are those which implement https://www.icao.int/publications/pages/publication.aspx?docnum=9303[ICAO Doc 9303: Machine Readable Travel Documents] as specified by International Civil Aviation Organization (ICAO).
Requirements
- Xcode 26.2+
- iOS 13.0+
- Swift or Objective-C
- CocoaPods or Swift Package Manager
- NFC reading capability is available on iPhone 7 and newer.
Deprecated Objective-C
In the major release 9.0.0, Objective-C support is deprecated, and in the following major release 10.0.0 it will be removed. If your iOS application integrates DOT iOS NFC using Objective-C, you will need to implement the bridging on your side.
Distribution
Swift Package Manager
DOT iOS NFC is distributed as a binary XCFramework - DotNfc.xcframework with its dependencies stored in our public github repository. It can be easily integrated into Xcode project in: Project -> Package Dependencies.
Use https://github.com/innovatrics/dot-ios-sdk-spm.git repository and choose the version you want to use. There you can select DotNfc package. All the required dependencies will be downloaded with the selected package.
Cocoapods
DOT iOS NFC is distributed as a XCFramework - DotNfc.xcframework using Cocoapods with its dependencies stored in our public github repository. It can be easily integrated into Xcode with custom definition of podspecs. First step is to insert following line of code on top of you Podfile.
.Podfile
source 'https://github.com/innovatrics/innovatrics-podspecs'
Then DOT iOS NFC dependency must be specified in Podfile. Dependencies of DOT iOS NFC will be downloaded alongside it.
.Podfile
source 'https://github.com/innovatrics/innovatrics-podspecs'
use_frameworks!
target 'YOUR_TARGET' do
pod 'dot-nfc'
end
In case of CocoaPods problem with pod install, try to clone the private pod repository manually.
pod repo remove innovatrics
pod repo add innovatrics https://github.com/innovatrics/innovatrics-podspecs
Supported Architectures
DOT iOS NFC provides all supported architectures in the distributed XCFramework package.
Device binary contains: arm64.
Simulator binary contains: x86_64, arm64.
Debug symbols
Due to security concerns, DOT iOS NFC does not include debug symbol files (dSYM files) in the distributed XCFramework package. As a result, Xcode will generate warnings when uploading an iOS application that includes DOT iOS NFC to the App Store. These warnings can be safely ignored.
Licensing
In order to use DotSdk in your iOS application, it must be licensed. The license can be compiled into the application as it is bound to Bundle Identifier specified in the General tab in Xcode.
The Bundle ID can be also retrieved in runtime by calling DotSdk.shared.bundleId.
In order to obtain the license, please contact your Innovatrics’ representative specifying Bundle ID. After you have obtained your license file, add it to your Xcode project and use it during the DotSdk initialization, as shown below.
Permissions
- Add capability to your Xcode target:
Near Field Communication Tag Reading. - Add support for PACE only travel documents by adding "PACE" value into your
App.entitlements:
\<key>com.apple.developer.nfc.readersession.formats\</key>
\<array>
\<string>TAG\</string>
\<string>PACE\</string>
\</array>`
- DOT iOS NFC requires following keys in
Info.plist:
\<key>NFCReaderUsageDescription\</key>
\<string>NFC tag to read NDEF messages into the application\</string>
\<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers\</key>
\<array>
\<string>A0000002471001\</string>
\</array>
Transaction Reporting
DOT iOS NFC reports transactions to a remote service. Read more details in the https://developers.innovatrics.com/digital-onboarding/technical/transactions/#reporting-of-usage-with-nfc-mobile-library/[Product Documentation].
Basic Setup
Initialization
Before using any of the components, you need to initialize DOT SDK with the license and DotNfcLibraryConfiguration object.
https://github.com/innovatrics/dot-ios-sdk-samples/blob/main/DotSdkSamples/SceneDelegate.swift[DOT SDK Sample] shows how to initialize DOT SDK with DotNfcLibraryConfiguration. DotSdk.shared.initialize() method should be called on background thread.
Keep in mind that if you try to use any feature which was not added during initialization DOT SDK will generate fatal error.
Deinitialization
When you have finished using the DOT iOS NFC, it is usually a good practice to deinitialize it in order to free the memory. You can deinitialize DOT iOS NFC only after the complete process is finished and not within the life cycle of individual components. This can be performed using the DotSdk.shared.deinitialize() method. If you want to use the DOT iOS NFC components again, you need to call DotSdk.shared.initialize() again.
Logging
DOT iOS NFC supports logging using a global Logger class. You can set the log level as follows:
import DotNfc
Logger.logLevel = .debug
Log levels:
- debug
- info
- warning
- error
- none
Each log message contains DotNfc tag. Keep in mind that logging should be used just for debugging purposes.
Components
Overview
DOT iOS NFC provides a non-UI component for NFC reading. You may customize native UI which is presented during the NFC reading on the iOS platform.
List of Non-UI Components
NFC TRAVEL DOCUMENT READER:: The component for reading NFC enabled travel documents. FLAT TAG STRUCTURE PARSER:: The component for parsing flat tag structure in a data group as defined in Doc 9303.
Non-UI Components
NFC Travel Document Reader
The NfcTravelDocumentReader class provides NFC reading functionality.
You can configure NfcTravelDocumentReader using NfcTravelDocumentReader.Configuration.
You can handle the NfcTravelDocumentReader events using its delegate NfcTravelDocumentReaderDelegate.
Create NfcTravelDocumentReader:
let authorityCertificatesUrl = Bundle.main.url(forResource: "masterList", withExtension: "pem")
let configuration = NfcTravelDocumentReader.Configuration(authorityCertificatesUrl: authorityCertificatesUrl)
let nfcTravelDocumentReader = NfcTravelDocumentReader(configuration: configuration)
nfcTravelDocumentReader.setDelegate(self)
To read NFC data, call the following method:
nfcTravelDocumentReader.read(password: password, activeAuthenticationChallenge: activeAuthenticationChallenge)
TravelDocumentReaderPassword is read either from the Machine Readable Zone or it is the value of Card Access Number.
ActiveAuthenticationChallenge is used in case, when server-side authentication of the chip is required. If the Active Authentication protocol is supported by the chip, it will be used for the authentication of the chip and the response (signature) will be returned in NfcTravelDocumentReaderResult class.
After the NFC reading session has started a system dialog is presented on top of the app content. Customization of this system dialog is limited only to the changing of the text message. This system dialog is dismissed after the NFC reading session has ended.
There are four possible ways how the NFC reading session can end:
- NFC reading was successful - System dialog shows success animation and is dismissed afterwards.
- NFC reading encountered an error - System dialog shows error animation and is dismissed afterwards.
- NFC reading was canceled by the system dialog cancel button on click event - System dialog is dismissed immediately.
- NFC reading timed out (iOS CoreNFC has strict time out of 60 seconds for NFC reading session.) - System dialog is dismissed immediately.
MachineReadableZonePassword
The MachineReadableZonePassword object is created from the travel document number, date of birth and date of expiry.
let mrzPassword = try MachineReadableZonePassword(documentNumber: documentNumber, dateOfExpiry: dateOfExpiry, dateOfBirth: dateOfBirth)
CardAccessNumberPassword
The CardAccessNumberPassword object is created from the Card Access Number.
let canPassword = try CardAccessNumberPassword(value: cardAccessNumber)
Flat Tag Structure Parser
The FlatTagStructureParser class parses input data into a dictionary of data elements.
Create a FlatTagStructureParser:
let flatTagStructureParser = FlatTagStructureParser()
To parse a Data Group value, call the following method:
let elements = try flatTagStructureParser.parse(value: bytes)
Following data structure is expected as an input:
ELEMENT_1_TAG, ELEMENT_1_LENGTH, ELEMENT_1_VALUE, ..., ELEMENT_N_TAG, ELEMENT_N_LENGTH, ELEMENT_N_VALUE
Such a value is parsed into this map:
| Tag | Value |
ELEMENT_1_TAG | ELEMENT_1_VALUE |
| ... | ... |
ELEMENT_N_TAG | ELEMENT_N_VALUE |
This is an example of a resulting map:
| Tag | Length | Value |
0x5C | 0x02 | 0x5F_5B |
0x5F_5B | 0x08 | SPECIMEN (shown as text for readability) |
Some country authorities may use this structure in the Optional Details. This data is present in TravelDocument.optionalDetails as a result of the NFC reading.
Customization of native UI
Localization
String resources can be overridden in your application and alternative strings for supported languages can be provided following these two steps:
-
Add your own
Localizable.stringsfile to your project using standard iOS localization mechanism. To change a specific text override corresponding key in thisLocalizable.stringsfile. -
Set the localization bundle to the bundle of your application (preferably during the application launch in your
AppDelegate).
Use this setup if you want to use standard iOS localization mechanism, which means your iOS application uses system defined locale.
import DotNfc
Localization.bundle = .main
Custom Localization
You can override standard iOS localization mechanism by providing your own translation dictionary and setting the Localization.useLocalizationDictionary flag to true. Use this setup if you do not want to use standard iOS localization mechanism, which means your iOS application ignores system defined locale and uses its own custom locale.
import DotNfc
guard let localizableUrl = Bundle.main.url(forResource: "Localizable", withExtension: "strings", subdirectory: nil, localization: "de"),
let dictionary = NSDictionary(contentsOf: localizableUrl) as? [String: String]
else { return }
Localization.useLocalizationDictionary = true
Localization.localizationDictionary = dictionary
.Localizable.strings
"dot_nfc.nfc_travel_document_reader.instruction.begin_reading" = "Slide your phone gently on the surface of the document until we find the right position.";
"dot_nfc.nfc_travel_document_reader.instruction.reading_in_progress" = "Hold still, we are working on it.";
"dot_nfc.nfc_travel_document_reader.instruction.reading_successful" = "Scanning was successful.";
"dot_nfc.nfc_travel_document_reader.instruction.access_control_error" = "There was a problem establishing access control with the document.";
"dot_nfc.nfc_travel_document_reader.instruction.reading_error" = "There was an error reading the document.";
"dot_nfc.nfc_travel_document_reader.progress_symbol.empty" = "\U25CB";
"dot_nfc.nfc_travel_document_reader.progress_symbol.full" = "\U25CF";
<<<
Appendix
Changelog
9.2.3 - 2026-04-17
Fixed
- Invalid import in
DotCoremodule.
9.2.2 - 2026-04-16
Fixed
- Requirements section in the integration manual.
9.2.1 - 2026-03-20
Changed
- Minimal required version of Xcode to Xcode 26.2.
9.2.0 - 2026-02-26
- Technical release. No changes.
9.1.1 - 2026-02-19
- Technical release. No changes.
9.1.0 - 2026-02-12
- Technical release. No changes.
9.0.2 - 2026-01-22
Changed
- Data Authentication now supports signatures that use non-standard signature algorithm identifiers.
9.0.1 - 2026-01-12
- Technical release. No changes.
9.0.0 - 2025-12-16
Added
- Class
Libraries. - Class
DotNfcLibraryConfiguration. - Class
CommonConfiguration. - Class
DotCore.Image. - Class
DotCore.ImageFormat. - Class
NfcTravelDocumentReader.ReadError. - Property
NfcTravelDocumentReader.Configuration.common.
Changed
- Minimal required iOS version to iOS 13.0.
- Minimal required version of Xcode to Xcode 16.1.
- Property type of
DisplayedSignatureOrUsualMark.displayedSignatureOrUsualMarkImagefromDotNfc.Image?toDotCore.Image?. - Property type of
EncodedIdentificationFeaturesFace.faceImagefromDotNfc.Image?toDotCore.Image?. - Moved property
NfcTravelDocumentReader.Configuration.sessionTokentoCommonConfiguration.sessionToken.
Removed
- Class
DotNfcLibrary. UseDotNfcLibraryConfigurationinstead. - Class
Image. UseDotCore.Imageinstead. - Enum
ImageFormat. UseDotCore.ImageFormatinstead. - Class
NfcKey. UsePasswordinstead. - Method
NfcTravelDocumentReader.read(nfcKey:activeAuthenticationChallenge:). Use methodNfcTravelDocumentReader.read(password:activeAuthenticationChallenge:)instead.
8.17.0 - 2025-12-05
- Technical release. No changes.
8.16.0 - 2025-10-16
- Technical release. No changes.
8.15.2 - 2025-09-24
- Technical release. No changes.
8.15.1 - 2025-09-09
Fixed
- Analytics reporting was not working properly.
8.15.0 - 2025-08-25
Added
- Transaction counting is disabled by default, it can be enabled in your license.
- Property
DotSdkConfiguration.transactionCountingToken. If transaction counting is enabled in your license, you must provide a valid transaction counting token. - Analytics reporting is enabled by default, it can be disabled in your license.
8.14.1 - 2025-07-30
- Technical release. No changes.
8.14.0 - 2025-07-07
- Technical release. No changes.
8.13.0 - 2025-06-19
- Technical release. No changes.
8.12.1 - 2025-06-10
- Technical release. No changes.
8.12.0 - 2025-06-02
- Technical release. No changes.
8.11.0 - 2025-05-06
- Technical release. No changes.
8.10.0 - 2025-04-03
- Technical release. No changes.
8.9.0 - 2025-04-01
- Technical release. No changes.
8.8.0 - 2025-03-26
Fixed
- Stability issue.
8.7.1 - 2025-03-21
Added
- Enum
NfcTravelDocumentReader.Configuration.PollingOption. - Property
NfcTravelDocumentReader.Configuration.pollingOption. - Support for
PACEonly travel documents by addingNfcTravelDocumentReader.Configuration.PollingOption.experimental. In order to readPACEonly travel documents, you also need to modify your app entitlements, see integration manual.
8.7.0 - 2025-02-06
Added
- Property
NfcTravelDocumentReader.Configuration.sessionToken. - Class
NfcTravelDocumentReaderResult.
Changed
- Method
NfcTravelDocumentReaderDelegate.nfcTravelDocumentReader(*: NfcTravelDocumentReader, succeeded: TravelDocument)tonfcTravelDocumentReader(*: NfcTravelDocumentReader, succeeded: NfcTravelDocumentReaderResult). The formerTravelDocumentclass is now accessible via theNfcTravelDocumentReaderResult.travelDocumentproperty.
8.6.1 - 2025-01-15
Fixed
- In some edge cases MRZ was parsed incorrectly.
8.6.0 - 2025-01-10
Changed
- Introduced Package access level which prevents internal types from leaking into public API.
Fixed
- Chip Authentication was failing for some documents.
8.5.0 - 2024-10-24
- Technical release. No changes.
8.4.1 - 2024-10-10
Fixed
- Added property
AdditionalDocumentDetails.otherPersonDetails. - DOT SDK initialization.
8.4.0 - 2024-09-11
Fixed
- Passive Authentication was failing for some documents.
Added
- Protocol
TravelDocumentReaderPassword. - Classes
MachineReadableZonePasswordandCardAccessNumberPassword. - Method
NfcTravelDocumentReader.read(password: TravelDocumentReaderPassword, activeAuthenticationChallenge: Data? = nil).
Changed
- Deprecated class
NfcKey, useMachineReadableZonePasswordinstead. - Deprecated
NfcTravelDocumentReader.read()method withnfcKeyargument, use method withpasswordargument instead.
8.3.2 - 2024-08-16
- Technical release. No changes.
8.3.1 - 2024-08-15
- Technical release. No changes.
8.3.0 - 2024-08-08
- Technical release. No changes.
8.2.1 - 2024-07-31
- Technical release. No changes.
8.2.0 - 2024-07-30
Added
- Nested enumerator
Errorto all public components. It groups all possible errors that might be thrown by a component. - More specific subclasses:
AccessControlError,ChipAuthenticationError,NotConnectedErrorfor error classNfcTravelDocumentReader.Error.
8.1.0 - 2024-07-09
- Technical release. No changes.
8.0.0 - 2024-06-27
Added
- Shared module
DotDocumentCommons. - Class
MachineReadableZonefrom moduleDotDocumentCommons.
Changed
- Minimal required iOS version to iOS 12.0.
- Minimal required version of Xcode to Xcode 15.1.
- Moved
NfcTravelDocumentReaderConfigurationtoNfcTravelDocumentReader.Configuration. - Moved
NfcTravelDocumentReaderErrortoNfcTravelDocumentReader.Error. NfcTravelDocumentReaderDelegateis usingNfcTravelDocumentReaderinstead ofNfcTravelDocumentReaderProtocol.- Removed
NfcTravelDocumentReaderFactory, useNfcTravelDocumentReader.init()instead. - Class
MachineReadableZoneInformationand containing classes. - Updated localization keys.
7.5.3 - 2024-06-24
Fixed
- Chip Authentication was failing for some documents.
7.5.2 - 2024-04-30
Changed
- Changed minimal required version of Xcode to Xcode 14.2.0.
7.5.1 - 2024-04-15
Fixed
- Added
PrivacyInfo.xcprivacyand signature toDotOpenSSLdependency.
7.5.0 - 2024-04-03
Fixed
- Some eMRTD documents will return empty data group data which was causing a crash.
7.4.2 - 2024-03-21
Added
- Method
NfcTravelDocumentReaderDelegate.nfcTravelDocumentReaderCanceled()to handle system dialog cancel button on click event.
7.4.1 - 2024-03-19
Added
- Enum
Lds1ElementaryFileId. - Property
Lds1ElementaryFile.id.
7.4.0 - 2024-03-19
Fixed
- Chip Authentication for eMRTD documents with large public keys.
Added
- Vibration feedback when a connection with an NFC chip has been established.
- Localization key
dot.nfc_travel_document_reader.instruction.readingInProgressfor text instruction during the NFC reading process.
Changed
- Text instruction for localization keys
dot.nfc_travel_document_reader.instruction.beginReading,.readingSuccessful.
Removed
- Localization keys
dot.nfc_travel_document_reader.instruction.establishAccessControl,.readingCom,.readingSod,.readingDG[1-16],.readingUnknownDG.
7.3.0 - 2024-02-23
Fixed
- Fixed licensing issue. Newly generated licenses will only work from this and subsequent releases.
Added
- Class
NfcTravelDocumentReaderFactory. - Reporting of NFC transactions to remote service. See the https://developers.innovatrics.com/digital-onboarding/technical/transactions/#reporting-of-usage-with-nfc-mobile-library.
Changed
NfcTravelDocumentReaderDelegateis usingNfcTravelDocumentReaderProtocolinstead ofNfcTravelDocumentReader.- Deprecated
NfcTravelDocumentReader.init(), useNfcTravelDocumentReaderFactory.create()instead.
7.2.1 - 2024-01-11
- Technical release. No changes.
7.2.0 - 2023-12-28
- Technical release. No changes.
7.1.1 - 2023-12-21
- Technical release. No changes.
7.1.0 - 2023-12-14
Changed
- Access Control mechanism reworked. BAC protocol is used by default. PACE protocol is used only if BAC protocol fails or BAC is not available.
7.0.2 - 2023-12-04
Fixed
- DOT SDK initialization (license parsing).
7.0.1 - 2023-12-01
Changed
- Updated renamed DotOpenSSL dependency version to 1.2.0.
7.0.0 - 2023-11-02
Added
- Class
DotSdk. - Class
DotSdkConfiguration. - Protocol
DotLibrary. - License file is required. To obtain one, please contact
support@innovatrics.com.
Changed
- Class
DotNfcLibraryreworked.
6.5.1 - 2023-10-19
Fixed
- Unable to parse Document Signing Certificate of some documents.
NfcTravelDocumentReader.read()was creating strong reference cycle.
6.5.0 - 2023-10-04
- Technical release. No changes.
6.4.0 - 2023-09-19
- Technical release. No changes.
6.3.0 - 2023-08-18
- Technical release. No changes.
6.2.0 - 2023-07-26
- Technical release. No changes.
6.1.1 - 2023-07-19
Fixed
- Handling of the case when travel document does not support Chip Authentication and Active Authentication.
6.1.0 - 2023-07-07
- Technical release. No changes.
6.0.0 - 2023-06-14
- Technical release. No changes.
5.5.0 - 2023-04-26
Added
- explicit challenge-response for Active Authentication in API suitable for server-side validation.
activeAuthenticationChallengeargument toNfcTravelDocumentReader.read()method.ChipAuthenticationStatus.activeAuthenticationResponse.
5.4.0 - 2023-03-24
- Technical release. No changes.
5.3.0 - 2023-03-23
- Technical release. No changes.
5.2.0 - 2023-03-06
Added
TravelDocument.authenticationStatusAuthenticationStatusChipAuthenticationStatusDataAuthenticationStatus
Removed
TravelDocument.activeAuthenticationStatusTravelDocument.passiveAuthenticationStatus
5.1.1 - 2023-02-21
Added
- support for Swift Package Manager.
5.1.0 - 2023-02-08
- Technical release. No changes.
5.0.0 - 2023-01-27
Changed
- New SDK versioning: All libraries (DOT Document, DOT Face, DOT Face Lite and DOT NFC) are released simultaneously with a single version name. Libraries with the same version name work correctly at build time and at run time.
Fixed
- @objc prefix pattern to
DOTN*
2.3.3 - 2022-12-02
Fixed
- parsing of country code in
TravelDocument.machineReadableZoneInformation.issuingStateOrOrganizationand.nationality
2.3.2 - 2022-10-24
Fixed
- NFC reading retry count was resetting improperly
Changed
- minimal required version to Xcode 14+
2.3.1 - 2022-08-16
Fixed
- stability of NFC reading session
- improved user experience by adding progress bar
- added localization keys for progress bar symbols
2.3.0 - 2022-07-21
Added
DotNfcLibrary.versionNameTravelDocument.ldsMasterFileLdsMasterFileLds1eMrtdApplicationLds1ElementaryFile
Fixed
TravelDocument.encodedIdentificationFeaturesFaceto Non-Optional
2.2.3 - 2022-07-01
Fixed
- support for Access Control Protocol - PACE - Integrated Mapping
- parsing of
NameOfHolder
2.2.2 - 2022-06-08
Fixed
- support for Access Control Protocol - PACE
2.2.1 - 2022-04-22
Fixed
- parsing of
AdditionalPersonalDetails.otherNames
2.2.0 - 2022-01-21
Added
FlatTagStructureParser
2.1.0 - 2022-01-19
Added
OptionalDetailsTravelDocument.optionalDetails
Changed
AdditionalPersonalDetails.nameOfHoldertype fromString?toNameOfHolder?
Fixed
- resolving of JPEG image format, using
ImageFormat.jpeg
2.0.2 - 2021-12-13
Fixed
- parsing of
AdditionalDocumentDetails.dateOfIssue
2.0.1 - 2021-12-13
Fixed
- wrong Passive Authentication flag returned
ImageObjective-C class name changed fromDOTImagetoDOTNImage
2.0.0 - 2021-12-02
Added
NfcKeyNfcTravelDocumentReaderConfigurationNfcTravelDocumentReaderDelegateNfcTravelDocumentReaderErrorPassiveAuthenticationStatusActiveAuthenticationStatusImageMachineReadableZoneInformationEncodedIdentificationFeaturesFaceDisplayedSignatureOrUsualMarkAdditionalPersonalDetailsAdditionalDocumentDetailsNameOfHolderAccessControlProtocolLogger
Changed
- minimal required iOS version to iOS 11.0
- added support for simulator build
- added support for bitcode, ENABLE_BITCODE = YES
- updated OpenSSL to version 1.1.1l
- added support for Active Authentication with RSA public keys
- removed default master list
- renamed module to
DotNfc - renamed
DotNfcLocalizationtoLocalization - updated localization keys
- renamed
NFCPassportReadertoNfcTravelDocumentReader NfcTravelDocumentReaderis now using delegate pattern- changed
NFCPassportReader.readPassport(mrzKey: String, result: @escaping ((ReadPassportResult) -> Void))toNfcTravelDocumentReader.read(nfcKey: NfcKey) - renamed
PassporttoTravelDocument
Removed
NFCFormatter
1.2.1 - 2021-10-01
Changed
- release library as a XCFramework package
1.2.0 - 2021-03-04
Added
DotNfcLocalizationclass to enable localization of alert messages
1.1.1 - 2020-10-23
Fixed
- removed force unwraps and added better error handling
1.1.0 - 2020-07-30
Added
- Released as a new component
dot-nfc
1.0.3 - 2020-03-31
Changed
- Renamed class
NFCReadertoNFCPassportReader
1.0.2 - 2020-03-31
Added
- BUILD_LIBRARY_FOR_DISTRIBUTION = YES
1.0.1 - 2020-03-12
Added
OpenSSLdependancy as an externalpoddependancyinnovatrics-openssl
1.0.0 - 2020-03-02
Added
faceImageandsignatureImagetoPassportstruct