NFCReader
The NFC Reader library is the Android client component of the NFC Document Reading Solution. It provides ICAO Doc 9303 compliant contactless chip reading, cryptographic verification, and session streaming capabilities for passports and identity documents on mobile devices.
In online operational modes, the core backend component is the NFC Server (minimum supported version 2.2.2), which processes and validates passport data. Once reading sessions are complete, structured results become available via secure download or push notification.
Sample Application
There are two reference sample applications demonstrating full integration of the SmartNFC Reader library:
- Online Sample App: Requires proofing platform URL, backend API keys (
nfcApiKey/ipvApiKey), LKMS license parameters, and Artifactory credentials. - Offline Sample App: Operates fully locally without backend connection; does not require
ipvApiKey,serverUrl, ornfcApiKey(only requires Artifactory credentials and LKMS license parameters).
Step 1: Obtain the API keys from the IDEMIA Experience Portal dashboard:
For NFC API Key (only online):
Language not specified11. Log in to the [IDEMIA Experience Portal](https://idplatform.idemia.com/).22. In the top menu, go to My Dashboard and select My Identity Proofing.33. On the right-hand menu, under Access, select [**Environment**](/dashboard/my-identity-proofing/access/environments/).44. On the Environments page, look for the **gips-ua** key under Environment.
For IPV (GIPS) API Key (only online):
Language not specified11. Log in to the [IDEMIA Experience Portal](https://idplatform.idemia.com/).22. In the top menu, go to My Dashboard and select My Identity Proofing.33. On the right-hand menu, under Access, select [**Environment**](/dashboard/my-identity-proofing/access/environments/).44. On the Environments page, look for the **gips-rs** key under Environment.
Note: Remember to use the default environment (US PROD) and confirm that serverUrl value in NFCAppConfiguration is the same as the selected environment address.
Note: In case of using non-default environment, SDK Experience service and assets urls in SDKExperience initializer in NFCScanner.reader must be provided.
To access your LKMS and Artifactory credentials, follow these steps:
Language not specified11. Log in to the [IDEMIA Experience Portal](https://idplatform.idemia.com/).22. In the top menu, go to **My Dashboard** and select **My Identity Proofing**.33. On the right-hand menu, under **Access**, select **SDK artifactory and licenses**.44. On the **SDK artifactory and licenses**, go to [**Artifactory access**](/dashboard/my-identity-proofing/access/artifactory-and-licenses/) to find the credentials you need.
Step 2: Download the sample app source code as a .zip package from Artifactory at Artifactory.
Step 3: Before building the app, you need to configure the project settings and select the application build target. Go to Build Settings and set the Build libraries for distribution flag to YES. If this flag is not visible, it is likely because the Basic view is set as default. Switch to All to make the row with flag visible.
Step 4: In the folder with the source sample app run pod install to configure the project. Cocoapods has to be at least 1.14.3 ver.
Step 5: Open project settings again and select application build target. Make sure that General tab is selected.
- In Identity section make sure that Bundle Identifier (PRODUCT_BUNDLE_IDENTIFIER) is set to the APP_ID that you provided to us to generate your license.
- In
Capabilities & Signingsection make sure that your Team (DEVELOPER_TEAM) is selected.
Step 6: Open the NFCAppConfiguration and add NFC, IPV, LKMS and SDKExperience credentials.
Online sample app configuration:
Swift1enum NFCAppConfiguration {2 enum LKMS {3 static let endpoint: String = "URL for proofing platform"4 static let profileID: String = "profile id"5 static let apiKey: String = "license api key"6 }7 enum IPV {8 static let baseAddress: String = "URL for proofing platform"9 static let apiKey: String = "api key with ACL gips-rs"10 static let endpointUrl = URL(string: "\(baseAddress)/gips")!11 }12 enum NFCServer {13 static let baseAddress: String = "URL for proofing platform"14 static let apiKey: String = "api key with ACL gips-ua"15 static let endpointUrl = URL(string: baseAddress)!.appendingPathComponent("nfc")16 }17 enum SDKExperience {18 static let baseAddress: String = "URL for proofing platform"19 static let apiKey: String = "api key with ACL gips-ua"20 static let endpointUrl = URL(string: baseAddress)!.appendingPathComponent("sdk-experience")21 }22}
Offline sample app configuration:
Swift1enum NFCAppConfiguration {2 enum LKMS {3 static let endpoint: String = "URL for proofing platform"4 static let profileID: String = "profile id"5 static let apiKey: String = "license api key"6 }7}
Step 7: You can now run the app. If you have followed all the steps correctly, you should not encounter any issues.
Integration guide
Adding the framework to your project
CocoaPods (from Artifactory)
- To use CocoaPods with Artifactory you must install the
cocoapods-artplugin. To installcocoapods-art, run the following command:
Language not specified1gem install cocoapods-art
- The plugin uses authentication as specified in a standard
.netrcfile.
Language not specified1machine artifacts.ips.idemia.com2login <USERNAME>3password <PASSWORD>
- Once set, add our repository to your cocoapod dependency management system:
Language not specified1pod repo-art add smartsdk "https://artifacts.ips.idemia.com/artifactory/api/pods/smartsdk-ios-local"
- At the top of your
Podfileadd:
Language not specified1plugin 'cocoapods-art', :sources => [2 'smartsdk' # so it could resolve NFCReader depdendency3]
-
(Optional) Before building the app, please change
Build libraries for distributionflag toYESin theBuild Settingsin Xcode for the project. If this flag is not visible usuallyBasicview is set as default. Then change toAll. -
Add the pod in your
Podfile:
Language not specified1pod 'NFCReader'
- Then you can use install as usual:
Language not specified1pod install
Note: If you already are using our repository, and you cannot resolve some dependency, try to update the specifications:
Language not specified1pod repo-art update smartsdk
Manual
-
In the project editor, select the target to which you want to add
NFCReader.xcframework. -
Click the General tab at the top of the project editor.
-
Scroll down to the Embedded Binaries section.
-
Click Add (+).
-
Click Add Other below the list.
-
Find the
NFCReader.xcframeworkfile and click Open. -
NFCReader.xcframeworkneeds specific dependency to compile the app:SQLite.swift. -
Add dependency
SQLite.swiftat least 0.14.0 ver. Follow tutorial from the webpage: manual integration with SQLite.swift -
(Optional) If
NFCReaderTutorialViewis added, please add another dependencylottie-ios4.4.1 ver. You can find it here: lottie-ios framework.
Modes of Operation
The NFC Reader component supports two primary operational modes:
1. Offline Mode
- Architecture: Performs local document reading and cryptographic verification without external internet communication.
- Dependencies: Relies entirely on client-provided CSCA certificates and Document Signer CRLs.
- Use Case: Air-gapped environments, offline field verification, and strict data residency requirements.
2. Online Mode
- Architecture: Streams document data in real-time to the external NFC Server (minimum supported version
2.2.2). - Dependencies: Requires an active internet connection and a pre-created session ID from the GIPS-RS backend.
- Use Case: Online identity proofing workflows connected to central identity platforms.
Licensing Requirements
In every operating mode (Offline and Online), a valid license must be prepared and activated on the client via LicenseManager prior to initiating reading operations.
Integration Guide by Mode
Select and follow the integration flow corresponding to your target Operating Mode:
Flow 1: Offline Mode Integration
Offline mode reads document data locally without server connection.
ℹ️ License Preparation: Mandatory before starting reading operations.
1. Instantiate NFCReader
Swift1let nfcReader = SmartNFCReader()
2. License Preparation & Execution
Swift1let manager = LicenseManager.provideLicenseManager(2 profileId: LKMS.profileId,3 apiKey: LKMS.apiKey,4 serverUrl: LKMS.serverEndpointUrl5)6do {7 try await manager.activate()8} catch {9 // handle LicenseActivationError10}
3. Configure OfflineUseCase
Swift1extension SomeClass: OfflineUseCaseCallbacks {2 func readingProgressUpdated(progress: Double) {3 // Update UI progress (0.0 to 1.0)4 }56 // After NFCReader library had finished reading document.7 func readingFinished(result: NFCReader.OfflineUseCaseResult) {8 // Handle offline reading result9 switch result {10 case .success(let success):11 // Handle success12 case .failure(let failure):13 // Handle failure14 }15 }16}1718let offlineSettings = OfflineUseCaseSettings(19 dataGroupIds: [DataGroupId.DG1, DataGroupId.DG2],20 cscaLdif: cscaLdifList, // Provided entirely by the client21)2223let offlineUseCase = OfflineUseCase(24 documentAccessData: .mrz("SAMPLE_MRZ"),25 phoneNFCLocation: PhoneNFCLocation.TOP,26 settings: offlineSettings,27 callbacks: offlineCallbacks28)
Flow 2: Online Mode Integration
Online mode streams document data directly to the NFC Server.
ℹ️ License Preparation: Mandatory before starting reading operations. See Capture SDK License & Manual Integration Steps for implementation details.
Creating NFC session
OnlineUseCase handles online document reading and verification interacting with the NFC Server. It requires a unique session per capture. The standard architectural approach is to create a session on the integrator's backend side using ipvApiKey (GIPS RS) and provide it to the application.
- GIPS API description - Experience Portal API Explorer
Creating an NFC session via GIPS involves:
-
Create Identity (on backend):
POST: /v1/identitiesReturns anIdentityobject containing theidentityId. -
Create NFC Session (on backend):
POST: /v1/identities/{identityId}/id-documents/nfc-sessionRequest body must contain MRZ lines data (MRZData). Response contains thesessionIdrequired byOnlineUseCase.
1. Instantiate NFCReader
Swift1let nfcReader = SmartNFCReader()
2. Configure OnlineUseCase
Swift1extension SomeClass: OnlineUseCaseCallbacks {2 func readingProgressUpdated(progress: Double) {3 // Update UI progress (0.0 to 1.0)4 }56 // After NFCReader library had finished reading document.7 func readingFinished(result: OnlineUseCaseResult) {8 // Handle offline reading result9 switch result {10 case .success(_):11 // Handle success12 case .failure(let failure):13 // Handle failure14 }15 }16}1718let onlineSettings = OnlineUseCaseSettings(19 environmentInfo = EnvironmentInfo(20 nfcServerUrl = "https://your-nfc-server-url.com/api",21 nfcServerApiKey = nfcApiKey // nfcApiKey (GIPS-UA) obtained from Experience Portal22 )23)2425let onlineUseCase = OnlineUseCase(26 documentAccessData: .mrz("SAMPLE_MRZ"),27 sessionId: sessionId,28 settings: onlineSettings,29 callbacks: onlineCallbacks30)
3. License Activation & Start Reading
Swift1let manager = LicenseManager.provideLicenseManager(2 profileId: LKMS.profileId,3 apiKey: LKMS.apiKey,4 serverUrl: LKMS.serverEndpointUrl5)6manager.activate { (error: LicenseActivationError?) in7 if let error {8 // Failed to fetch or activate the license.9 } else {10 // License fetched and activated with success.11 }12}1314// License is active; proceed with NFC reading15nfcReader.start(useCase: useCase)
Integration Guide: Using TutorialProvider
To guide the user during the NFC scanning process, you can use TutorialProvider to fetch the physical phone antenna location and retrieve corresponding Lottie animations.
Step 1: Initialize TutorialProvider
Swift1// Local resources (default)2let tutorialProvider = TutorialProvider.getTutorialProvider()34// OR with remote SDK Experience configuration (using nfcApiKey / GIPS-UA)5let sdkExperience = SDKExperience(apiKey: nfcApiKey)6let tutorialProvider = TutorialProvider.getTutorialProvider(sdkExperience: sdkExperience)
Step 2: Fetch NFC Location and Animation
Option A: Using callback
Swift1tutorialProvider.provideNFCLocation(mrzString) { result in2 switch result {3 case .success(let nfcLocation):4 tutorialProvider.provideAnimation(nfcLocation: nfcLocation) { animationResult in5 switch animationResult {6 case .success(let animationData):7 // Load animation Data into your Lottie animation view8 case .failure(let error):9 // Handle animation fetch error10 }11 case .failure(let error):12 // Handle location fetch error13 }14}
Option B: Using async/await
Swift1do {2 let location = try await tutorialProvider.provideNFCLocation(mrzString).get()3 let animation = try await tutorialProvider.provideAnimation(forLocation: location).get()4} catch {5 // Handle location / animation fetch error6}
Detailed Offline Integration Features
When integrating Offline Mode, the following advanced configuration options are available:
1. Data Group (DG) Selection
Integrators select which Data Groups to read from the physical chip via the dataGroupIds parameter in OfflineUseCaseSettings:
Swift1let offlineSettings = OfflineUseCaseSettings(2 // Request specific Data Groups required by your use case3 dataGroupIds: [4 DataGroupId.dg1, // MRZ document data5 DataGroupId.dg2, // Holder facial image6 DataGroupId.dg14, // Security Options (CA/TA)7 DataGroupId.sod // Document Security Object signature8 ]9)
2. PKD Setup & LDIF Management
Passive Authentication (PA) verifies that the data on the document chip is authentic and was issued by an authorized authority. Both CSCA certificates and Document Signer Certificate Revocation Lists (CRLs) can be fetched from the official ICAO PKD portal: https://pkddownload.icao.int/.
- CSCA Certificates (
cscaLdif): Provide Country Verifying Certificate Authority (CSCA) certificates in LDIF format viacscaLdif: [String]?. Note: This must be the master list of certificates; delta LDIF files are not supported. - Document Signer CRLs (
dsCrlLdif): Provide Document Signer Certificate Revocation Lists (CRLs) in LDIF format viadsCrlLdif: [String]?. - Automatic Storage: During offline reading, any provided
cscaLdifordsCrlLdiflists are automatically stored in local storage. - Missing Certificate Error: If no CSCA certificate exists in local storage and
cscaLdifis nil/empty,FailureType.missingCertificatewill be returned in the result callback.
Swift1let cscaLdifList: [String] = loadCscaLdifFromAssets()2let dsCrlLdifList: [String] = loaddsCrlLdifFromAssets()34let offlineSettings = OfflineUseCaseSettings(5 dataGroupIds: [.dg1, .dg2],6 cscaLdif: cscaLdifList,7 dsCrlLdif: dsCrlLdifList8)
3. Debug Data Fetching (Scenario Dumping & Replaying)
For troubleshooting, automated testing, or bug reporting, you can capture or replay offline NFC reading sessions via replaySettings:
Capturing / Dumping a Session
OfflineUseCaseReplaySettings allows capturing or replaying sessions:
Note: The dump may contain PII/personal data from the NFC document and shall be used only for debugging purposes.
Swift1let debugReplaySettings = OfflineUseCaseReplaySettings(2 dumpScenarioData: true,3 dumpSerialisedSession: true,4 onDumpCreated: { dumpedData in5 saveDumpToFile(dumpedData)6 }7)