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, or nfcApiKey (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 specified
11. 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 specified
11. 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 specified
11. 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.

  1. 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.
  2. In Capabilities & Signing section 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:

Swift
1enum 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:

Swift
1enum 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)

  1. To use CocoaPods with Artifactory you must install the cocoapods-art plugin. To install cocoapods-art, run the following command:
Language not specified
1gem install cocoapods-art
  1. The plugin uses authentication as specified in a standard .netrc file.
Language not specified
1machine artifacts.ips.idemia.com
2login <USERNAME>
3password <PASSWORD>
  1. Once set, add our repository to your cocoapod dependency management system:
Language not specified
1pod repo-art add smartsdk "https://artifacts.ips.idemia.com/artifactory/api/pods/smartsdk-ios-local"
  1. At the top of your Podfile add:
Language not specified
1plugin 'cocoapods-art', :sources => [
2 'smartsdk' # so it could resolve NFCReader depdendency
3]
  1. (Optional) Before building the app, please change Build libraries for distribution flag to YES in the Build Settings in Xcode for the project. If this flag is not visible usually Basic view is set as default. Then change to All.

  2. Add the pod in your Podfile:

Language not specified
1pod 'NFCReader'
  1. Then you can use install as usual:
Language not specified
1pod install

Note: If you already are using our repository, and you cannot resolve some dependency, try to update the specifications:

Language not specified
1pod repo-art update smartsdk

Manual

  1. In the project editor, select the target to which you want to add NFCReader.xcframework.

  2. Click the General tab at the top of the project editor.

  3. Scroll down to the Embedded Binaries section.

  4. Click Add (+).

  5. Click Add Other below the list.

  6. Find the NFCReader.xcframeworkfile and click Open.

  7. NFCReader.xcframework needs specific dependency to compile the app: SQLite.swift.

  8. Add dependency SQLite.swift at least 0.14.0 ver. Follow tutorial from the webpage: manual integration with SQLite.swift

  9. (Optional) If NFCReaderTutorialView is added, please add another dependency lottie-ios 4.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

Swift
1let nfcReader = SmartNFCReader()

2. License Preparation & Execution

Swift
1let manager = LicenseManager.provideLicenseManager(
2 profileId: LKMS.profileId,
3 apiKey: LKMS.apiKey,
4 serverUrl: LKMS.serverEndpointUrl
5)
6do {
7 try await manager.activate()
8} catch {
9 // handle LicenseActivationError
10}

3. Configure OfflineUseCase

Swift
1extension SomeClass: OfflineUseCaseCallbacks {
2 func readingProgressUpdated(progress: Double) {
3 // Update UI progress (0.0 to 1.0)
4 }
5
6 // After NFCReader library had finished reading document.
7 func readingFinished(result: NFCReader.OfflineUseCaseResult) {
8 // Handle offline reading result
9 switch result {
10 case .success(let success):
11 // Handle success
12 case .failure(let failure):
13 // Handle failure
14 }
15 }
16}
17
18let offlineSettings = OfflineUseCaseSettings(
19 dataGroupIds: [DataGroupId.DG1, DataGroupId.DG2],
20 cscaLdif: cscaLdifList, // Provided entirely by the client
21)
22
23let offlineUseCase = OfflineUseCase(
24 documentAccessData: .mrz("SAMPLE_MRZ"),
25 phoneNFCLocation: PhoneNFCLocation.TOP,
26 settings: offlineSettings,
27 callbacks: offlineCallbacks
28)

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.

Creating an NFC session via GIPS involves:

  1. Create Identity (on backend): POST: /v1/identities Returns an Identity object containing the identityId.

  2. Create NFC Session (on backend): POST: /v1/identities/{identityId}/id-documents/nfc-session Request body must contain MRZ lines data (MRZData). Response contains the sessionId required by OnlineUseCase.

1. Instantiate NFCReader

Swift
1let nfcReader = SmartNFCReader()

2. Configure OnlineUseCase

Swift
1extension SomeClass: OnlineUseCaseCallbacks {
2 func readingProgressUpdated(progress: Double) {
3 // Update UI progress (0.0 to 1.0)
4 }
5
6 // After NFCReader library had finished reading document.
7 func readingFinished(result: OnlineUseCaseResult) {
8 // Handle offline reading result
9 switch result {
10 case .success(_):
11 // Handle success
12 case .failure(let failure):
13 // Handle failure
14 }
15 }
16}
17
18let onlineSettings = OnlineUseCaseSettings(
19 environmentInfo = EnvironmentInfo(
20 nfcServerUrl = "https://your-nfc-server-url.com/api",
21 nfcServerApiKey = nfcApiKey // nfcApiKey (GIPS-UA) obtained from Experience Portal
22 )
23)
24
25let onlineUseCase = OnlineUseCase(
26 documentAccessData: .mrz("SAMPLE_MRZ"),
27 sessionId: sessionId,
28 settings: onlineSettings,
29 callbacks: onlineCallbacks
30)

3. License Activation & Start Reading

Swift
1let manager = LicenseManager.provideLicenseManager(
2 profileId: LKMS.profileId,
3 apiKey: LKMS.apiKey,
4 serverUrl: LKMS.serverEndpointUrl
5)
6manager.activate { (error: LicenseActivationError?) in
7 if let error {
8 // Failed to fetch or activate the license.
9 } else {
10 // License fetched and activated with success.
11 }
12}
13
14// License is active; proceed with NFC reading
15nfcReader.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

Swift
1// Local resources (default)
2let tutorialProvider = TutorialProvider.getTutorialProvider()
3
4// 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
Swift
1tutorialProvider.provideNFCLocation(mrzString) { result in
2 switch result {
3 case .success(let nfcLocation):
4 tutorialProvider.provideAnimation(nfcLocation: nfcLocation) { animationResult in
5 switch animationResult {
6 case .success(let animationData):
7 // Load animation Data into your Lottie animation view
8 case .failure(let error):
9 // Handle animation fetch error
10 }
11 case .failure(let error):
12 // Handle location fetch error
13 }
14}
Option B: Using async/await
Swift
1do {
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 error
6}

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:

Swift
1let offlineSettings = OfflineUseCaseSettings(
2 // Request specific Data Groups required by your use case
3 dataGroupIds: [
4 DataGroupId.dg1, // MRZ document data
5 DataGroupId.dg2, // Holder facial image
6 DataGroupId.dg14, // Security Options (CA/TA)
7 DataGroupId.sod // Document Security Object signature
8 ]
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 via cscaLdif: [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 via dsCrlLdif: [String]?.
  • Automatic Storage: During offline reading, any provided cscaLdif or dsCrlLdif lists are automatically stored in local storage.
  • Missing Certificate Error: If no CSCA certificate exists in local storage and cscaLdif is nil/empty, FailureType.missingCertificate will be returned in the result callback.
Swift
1let cscaLdifList: [String] = loadCscaLdifFromAssets()
2let dsCrlLdifList: [String] = loaddsCrlLdifFromAssets()
3
4let offlineSettings = OfflineUseCaseSettings(
5 dataGroupIds: [.dg1, .dg2],
6 cscaLdif: cscaLdifList,
7 dsCrlLdif: dsCrlLdifList
8)

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.

Swift
1let debugReplaySettings = OfflineUseCaseReplaySettings(
2 dumpScenarioData: true,
3 dumpSerialisedSession: true,
4 onDumpCreated: { dumpedData in
5 saveDumpToFile(dumpedData)
6 }
7)