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
The SmartNFC solution provides two separate sample applications: an Online Sample App and an Offline Sample App.
[!IMPORTANT]
- 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 Credentials from the Experience Portal
Log in to the IDEMIA Experience Portal (My Identity Proofing → Access) to retrieve the required parameters:
Credential / Parameter | Portal Section | gradle.properties Property | Required For |
|---|---|---|---|
| Proofing URL & NFC API Key | Environments | serverUrl & nfcApiKey | Online Sample App only |
| IPV Backend API Key | Environments | ipvApiKey | Online Sample App only |
| LKMS & Artifactory | SDK Artifactory & Licenses | lkmsProfileId, lkmsApiKey, artifactoryUserMI, artifactoryPasswordMI | Both Online & Offline Apps |
Step 2: Configure Global gradle.properties
Place your credentials into your global gradle.properties file (located by default at ~/.gradle/gradle.properties on macOS/Linux or %USERPROFILE%\.gradle\gradle.properties on Windows):
Groovy1# Required for Online Sample App2serverUrl="YOUR_PROOFING_PLATFORM_URL"3nfcApiKey="YOUR_NFC_API_KEY" # GIPS-UA4ipvApiKey="YOUR_IPV_API_KEY" # GIPS RS56# Required for Both Online & Offline Sample Apps7artifactoryUserMI="YOUR_ARTIFACTORY_USER"8artifactoryPasswordMI="YOUR_ARTIFACTORY_CREDENTIALS"9repositoryUrlMI="https://artifacts.ips.idemia.com/artifactory/smartsdk-android-local"1011lkmsProfileId="YOUR_LKMS_PROFILE_ID"12lkmsApiKey="YOUR_LKMS_API_KEY"
Step 3: Fetch & Execute
- Download the sample application source code package (.zip) from Artifactory depending on your target operational mode:
- Online Sample App: smartnfc-sample-project
- Offline Sample App: smartnfc-offline-sample-project
- Open the project in Android Studio.
- Verify that your environment configurations are correctly referenced from
gradle.properties. - Build and run the application on an NFC-enabled physical Android device.
Prerequisites & Configuration
Before integrating the SmartNFC Reader, ensure the build system and project dependencies are properly configured.
1. Repository Setup
Add the Mobile Identity Artifactory repository to your root settings.gradle or project-level build.gradle (Groovy):
Groovy1buildscript {2 repositories {3 maven {4 url = "$repositoryUrlMI"5 credentials {6 username = "$artifactoryUserMI"7 password = "$artifactoryPasswordMI"8 }9 }10 // ... other repositories11 }12}
2. Artifactory Credentials & API Keys
Define repository properties and API keys in your local gradle.properties file:
Properties1artifactoryUserMI=artifactory_user2artifactoryPasswordMI=artifactory_credentials3repositoryUrlMI=https://artifacts.ips.idemia.com/artifactory/smartsdk-android-local
Note: Credentials and API keys can be obtained through the Experience Portal (My Identity Proofing → Access). Storing them in
gradle.propertiesprevents committing sensitive credentials to source control.Required API keys (configured based on your integration mode):
nfcApiKey: Corresponds to GIPS-UA on the Experience Portal (used for NFC Server & SDK Experience authentication).ipvApiKey: Corresponds to GIPS RS on the Experience Portal (used for backend identity and session creation).
3. Dependencies
Add the SmartNFC dependency to your application module's build.gradle:
Gradle1dependencies {2 // SmartNFC Library (v3.0.0+)3 implementation ("com.idemia.smartsdk:smart-nfc:$smartNfcVersion")45 // Coroutines (Optional for asynchronous suspend API calls)6 implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0"7}
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. License management is handled by the Capture SDK LicenseManager.
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
Kotlin1val nfcReader = NFCReader(activity)
ℹ️
NFCReaderuses the providedActivitycontext directly to turn on and manage hardware support for NFC scanning.
2. Configure OfflineUseCase
Kotlin1val offlineCallbacks = object : OfflineUseCaseCallbacks {2 override fun readingProgressUpdated(progress: Float) {3 // Update UI progress (0.0 to 1.0)4 }56 override fun readingFinished(result: OfflineUseCaseResult) {7 // Handle offline reading result8 }9}1011val offlineSettings = OfflineUseCaseSettings(12 dataGroupIds = setOf(DataGroupId.DG1, DataGroupId.DG2),13 cscaLdif = cscaLdifList, // Provided entirely by the client14 logLevel = LogLevel.NONE15)1617val offlineUseCase = OfflineUseCase(18 documentAccessData = MRZDocumentAccessData(mrz = "SAMPLE_MRZ"),19 phoneNFCLocation = PhoneNFCLocation.TOP,20 settings = offlineSettings,21 callbacks = offlineCallbacks22)
3. License Activation & Start Reading
Kotlin1lifecycleScope.launch {2 try {3 val licenseManager = LicenseManager.provideLicenseManager(4 BuildConfig.LkmsProfileId,5 BuildConfig.LkmsApiKey,6 "https://prd.lkms.xantav.com/api"7 )8 val licenseResult = licenseManager.activate(context)910 if (licenseResult is LicenseActivationSuccess) {11 nfcReader.start(offlineUseCase)12 } else {13 Log.e("NFC_READER", "License activation failed")14 }15 } catch (e: Exception) {16 Log.e("NFC_READER", "License activation error", e)17 }18}
Flow 2: Online Mode Integration
Online mode streams document data directly to the NFC Server.
ℹ️ License Preparation: Mandatory before starting reading operations.
Creating NFC session
OnlineUseCase handles online document reading and verification interacting with the NFC Server. It requires a unique session per capture.
[!IMPORTANT] In a customer's production application, identity creation and NFC session generation must be performed securely on your backend server using your
ipvApiKey(GIPS RS). The mobile client should fetch the resultingsessionIdfrom your backend via your own API. Instantiating backend services directly on the mobile client is demonstrated in the sample app for convenience only.
- GIPS API description - Experience Portal API Explorer
Server-side creation of 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.
Kotlin1// Backend Representation / Sample App Reference: Creating session via GIPS API2val serverConfigurationData = ServerConfigurationData(3 serverUrl = "https://your-proofing-platform-url.com/gips/",4 serverApiKey = ipvApiKey // ipvApiKey (GIPS RS) kept secure on the backend5)67// 1. Create identity8val identity = IdentityService(serverConfigurationData).createIdentity()910// 2. Create NFC session using identity ID and document MRZ lines11val session = SessionService(serverConfigurationData).createSession(12 identity.id,13 MRZData(mrzResult.mrzLines)14)1516val sessionId = session.sessionId ?: throw IllegalStateException("Session ID is null")
1. Instantiate NFCReader
Kotlin1val nfcReader = NFCReader(activity)
ℹ️
NFCReaderuses the providedActivitycontext directly to turn on and manage hardware support for NFC scanning.
2. Configure OnlineUseCase
Kotlin1val onlineCallbacks = object : OnlineUseCaseCallbacks {2 override fun readingProgressUpdated(progress: Float) {3 // Update UI progress (0.0 to 1.0)4 }56 override fun readingFinished(result: OnlineUseCaseResult) {7 // Handle online reading result8 }9}1011val onlineSettings = OnlineUseCaseSettings(12 environmentInfo = EnvironmentInfo(13 nfcServerUrl = "https://your-nfc-server-url.com/api",14 nfcServerApiKey = nfcApiKey // nfcApiKey (GIPS-UA) obtained from Experience Portal15 ),16 logLevel = LogLevel.NONE17)1819val onlineUseCase = OnlineUseCase(20 documentAccessData = MRZDocumentAccessData(mrz = "SAMPLE_MRZ"),21 phoneNFCLocation = PhoneNFCLocation.TOP,22 sessionID = sessionId, // Obtained from session creation step above23 settings = onlineSettings,24 callbacks = onlineCallbacks25)
3. License Activation & Start Reading
Kotlin1lifecycleScope.launch {2 try {3 val licenseManager = LicenseManager.provideLicenseManager(4 BuildConfig.LkmsProfileId,5 BuildConfig.LkmsApiKey,6 "https://prd.lkms.xantav.com/api"7 )8 val licenseResult = licenseManager.activate(context)910 if (licenseResult is LicenseActivationSuccess) {11 nfcReader.start(onlineUseCase)12 } else {13 Log.e("NFC_READER", "License activation failed")14 }15 } catch (e: Exception) {16 Log.e("NFC_READER", "License activation error", e)17 }18}
License Activation API Reference
LicenseActivationResult
This is information of result from activation license using coroutines solution. Instance might be type of:
LicenseActivationSuccess- LicenseActivationError
LicenseActivationError
This is the information about why license can not be activated.
Attribute | Description |
|---|---|
type (ActivationErrorType) | The type of error why license activation failed |
message (String) | The activation failure reason. |
ActivationErrorType Enum
Attribute | Description |
|---|---|
PROFILE_EXPIRED | Profile expired, all licenses won’t work anymore. (Contact support) |
ACTIVATION_COUNT_EXCEEDED | No more licenses can be consumed. (Contact support) |
AUTHENTICATION_ISSUE | Credentials and/or profile information are wrong. |
CONNECTION_ISSUE | Connection issue. Make sure that your internet connection is stable. |
UNKNOWN | Unknown issue. |
API Reference
All primary classes are located in the com.idemia.smartsdk.nfc.reader.api package.
1. NFCReader
The main entry point for document reading. Requires an AppCompatActivity context.
Method | Parameters | Return Type | Description |
|---|---|---|---|
start | OnlineUseCase or OfflineUseCase | Unit | Starts the document reading procedure on a working thread. |
cancel | None | Unit | Cancels current reading procedure. Triggers FailureType.CANCELED. |
isDeviceCompatible | None | Boolean | Checks if device satisfies NFC hardware/software requirements. |
enableAnalytics | network: Network, analyticsConfigurationData: AnalyticsConfigurationData | Unit | Enables analytics collection with network configuration. |
disableAnalytics | None | Unit | Disables analytics collection. |
2. Document Reading Configurations
Integrators instantiate either OnlineUseCase or OfflineUseCase depending on the selected operating mode.
OnlineUseCase
Used for online verification workflows (Server Mode & Remote Mode).
Parameter | Type | Default | Description |
|---|---|---|---|
documentAccessData | DocumentAccessData | None (Required) | Data required to access document (e.g., MRZDocumentAccessData). |
phoneNFCLocation | PhoneNFCLocation | None (Required) | Antenna position on the device. |
sessionID | String | None (Required) | Session identifier created on the NFC Server. |
settings | OnlineUseCaseSettings | None (Required) | Server environment info and log level settings. |
callbacks | OnlineUseCaseCallbacks | None (Required) | Callback handler for progress and completion results. |
OfflineUseCase
Used for offline verification workflows.
Parameter | Type | Default | Description |
|---|---|---|---|
documentAccessData | DocumentAccessData | None (Required) | Data required to access document. |
phoneNFCLocation | PhoneNFCLocation | None (Required) | Antenna position on the device. |
settings | OfflineUseCaseSettings | None (Required) | Configures dataGroupIds, cscaLdif, dsClrLdif, replaySettings, and logLevel. |
callbacks | OfflineUseCaseCallbacks | None (Required) | Callback handler for progress and completion results. |
3. Settings & Configurations
OnlineUseCaseSettings & EnvironmentInfo
Parameter | Type | Default | Description |
|---|---|---|---|
environmentInfo | EnvironmentInfo | None (Required) | Configuration for the server environment (nfcServerUrl and nfcServerApiKey). |
logLevel | LogLevel | None (Required) | Desired logging verbosity (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE). |
nfcServerUrl | String | None (Required) | Base URL of the NFC Server endpoint. |
nfcServerApiKey | String | None (Required) | Customer API key for server authentication. |
OfflineUseCaseSettings
Parameter | Type | Default | Description |
|---|---|---|---|
dataGroupIds | Set<DataGroupId> | setOf(DataGroupId.DG1) | The set of Data Groups to be read from the document chip. |
cscaLdif | List<String>? | null | CSCA certificates in LDIF format supplied by the client for Passive Authentication. |
dsClrLdif | List<String>? | null | Document Signer Certificate Revocation Lists (CRLs) supplied by the client. |
replaySettings | OfflineUseCaseReplaySettings | null | Optional settings for scenario dumping or replaying. |
logLevel | LogLevel | LogLevel.NONE | Desired logging verbosity (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE). |
OfflineUseCaseReplaySettings
Parameter | Type | Default | Description |
|---|---|---|---|
replayScenarioData | ByteArray? | null | Binary data for replaying a previously captured offline session. |
dumpScenarioData | Boolean | false | Whether to dump current scenario data. |
dumpSerialisedSession | Boolean | false | Whether to dump the serialized session data. |
onDumpCreated | ((ByteArray) -> Unit)? | null | Callback triggered when a debug dump is successfully created. |
NFCConfiguration
Parameter | Type | Default | Description |
|---|---|---|---|
serverUrl | String | "https://proofing.app.proofing.zz3.io/nfc/" | Base endpoint URL of the target NFC server. |
serverApiKey | String | None (Required) | Server API key for authentication. |
logLevel | LogLevel | LogLevel.NONE | Log level applied to network operations (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE). |
4. Listeners & Callbacks
OnlineUseCaseCallbacks
Method | Parameters | Return Type | Description |
|---|---|---|---|
readingProgressUpdated | progress: Float (FloatRange 0.0 .. 1.0) | Unit | Invoked when reading progress updates (progress in range 0.0 .. 1.0). |
readingFinished | result: OnlineUseCaseResult | Unit | Invoked when online reading process completes. |
OfflineUseCaseCallbacks
Method | Parameters | Return Type | Description |
|---|---|---|---|
readingProgressUpdated | progress: Float (FloatRange 0.0 .. 1.0) | Unit | Invoked when reading progress updates (progress in range 0.0 .. 1.0). |
readingFinished | result: OfflineUseCaseResult | Unit | Invoked when offline reading process completes. |
ResultListener
Method | Parameters | Return Type | Description |
|---|---|---|---|
onSuccess | None | Unit | Called on the Main Thread when document reading completes successfully. |
onFailure | failure: Failure | Unit | Called on the Main Thread when document reading fails. |
ProgressListener
Method | Parameters | Return Type | Description |
|---|---|---|---|
onProgressUpdated | progress: Int (0 .. 100) | Unit | Called from the Main Thread whenever progress updates (progress in range 0 .. 100 percent). |
5. Results & Error Handling
Online Reading Results (OnlineUseCaseResult)
OnlineUseCaseSuccess
Represents a successful online reading operation.
OnlineUseCaseFailure Properties
Property | Type | Description |
|---|---|---|
error | NFCReaderOnlineError | Detailed information about the error. |
NFCReaderOnlineError Properties
Property | Type | Description |
|---|---|---|
type | FailureType | The type of failure. |
code | Int | An error code. |
message | String | A descriptive error message. |
NFCReaderOnlineError.FailureType Enum
Failure Type | Description |
|---|---|
UNKNOWN | Unexpected error. |
NFC_CONNECTION_BROKEN | NFC connection has been broken. |
SERVER_CONNECTION_BROKEN | Cannot process data with the server side, might be a compatibility issue. |
SERVER_ERROR | Server side error occurred. |
CONNECTION_ISSUE | Cannot connect with external server, no internet connection. |
INVALID_SESSION_STATE | Session is in an unexpected state. New one needs to be created. |
READING_ISSUE | Document reading issue occurred. Can be related with NFC issues and data converting. |
UNSUPPORTED_DEVICE | Device does not support NFC or it's disabled. |
CANCELED | Operation was canceled. |
REQUESTS_LIMIT_EXCEEDED | Document reading is impossible because of too many requests to server has been made or API key request limit has been exceeded. |
NFC_INVALID_POSITION | NFC tag is not in valid position. |
WRONG_MRZ | MRZ passed to 'start' method is not the same as the one scanned from NFC chip. |
INVALID_LICENSE | Invalid or inactive license. |
Offline Reading Results (OfflineUseCaseResult)
OfflineUseCaseSuccess
Property | Type | Default | Description |
|---|---|---|---|
status | OfflineUseCaseReadingStatus | None | Status of offline reading & verification (READ_AND_VERIFIED, READ_AND_NOT_VERIFIED, READ_AND_INVALID). |
isDocumentExpired | Boolean | None | Indicates whether the document expiry date has passed based on system time. |
dataGroups | Map<DataGroupId), Map<String, String>>? | None | Map of read DataGroupId) tags to parsed key-value field data. |
securityChecks | SecurityChecks | None | Detailed cryptographic security check statuses (Active Authentication, Passive Authentication, CA/TA, etc.). |
Helper Methods
Method | Return Type | Description |
|---|---|---|
toGipsJson() | String | Converts the success result and parsed data groups into GIPS JSON formatted string. |
OfflineUseCaseFailure
Wraps NFCReaderOfflineError containing error details and status.
NFCReaderOfflineError Properties
Property | Type | Default | Description |
|---|---|---|---|
type | FailureType | None | High-level failure classification enum for offline reading. |
code | Int | None | Numeric error code. |
message | String | None | Descriptive error message. |
NFCReaderOfflineError.FailureType Enum
Failure Type | Description |
|---|---|
UNKNOWN | Unexpected error occurred. |
NFC_CONNECTION_BROKEN | Physical NFC connection to document chip was interrupted. |
READING_ISSUE | Issue reading document chip or parsing data. |
UNSUPPORTED_DEVICE | Device lacks required NFC hardware or NFC is disabled. |
CANCELED | Operation was canceled by the user. |
NFC_INVALID_POSITION | NFC tag/passport is not in a valid reading position against device antenna. |
MISSING_CERTIFICATE | NFC reading was started without CSCA certificate required for authentication. |
WRONG_MRZ | MRZ provided in start() does not match MRZ read from physical chip. |
INVALID_LICENSE | Invalid or inactive license. |
OfflineUseCaseReadingStatus Enum
Status | Description |
|---|---|
READ_AND_VERIFIED | Document data was read and all cryptographic security checks passed. |
READ_AND_NOT_VERIFIED | Document data was read, but security checks could not be concluded (e.g. missing CSCA certificates). |
READ_AND_INVALID | Document data was read, but security verification failed (e.g., hash mismatch or bad signature). |
ERROR | An error occurred during the reading process. |
SecurityChecks
Detailed cryptographic security check statuses evaluated during offline reading:
Property | Type | Default | Description |
|---|---|---|---|
aaStatus | SecurityCheckStatus | None | Active Authentication (AA) status (verifies chip genuineness). |
caStatus | SecurityCheckStatus | None | Chip Authentication (CA) status (EAC protocol). |
paHashCheck | SecurityCheckStatus | None | Passive Authentication Data Group hash verification status. |
bacStatus | SecurityCheckStatus | None | Basic Access Control (BAC) status. |
paceStatus | SecurityCheckStatus | None | Password Authenticated Connection Establishment (PACE) status. |
paDocumentSignerCheck | SecurityCheckStatus | None | Passive Authentication Document Signer (DS) certificate validation status. |
taStatus | SecurityCheckStatus | None | Terminal Authentication (TA) status (EAC protocol). |
paResultCode | Int? | null | Detailed numeric result code for Passive Authentication. |
paSodSignatureCheck | SecurityCheckStatus | None | Passive Authentication SOD digital signature verification status. |
SecurityCheckStatus Enum
Value | Description |
|---|---|
VERIFIED | The security check was executed and successfully verified (positive result). |
NOT_VERIFIED | The security check could not be performed or completed (e.g. missing certificate/key). |
FAILED | The security check was executed and failed verification (negative result). |
6. Models & Data Types
DocumentAccessData
MRZDocumentAccessData
Access credentials constructed using the raw Machine Readable Zone (mrz) string.
PhoneNFCLocation Enum
Value | Description |
|---|---|
TOP | NFC antenna is located at the top of the phone. |
MIDDLE | NFC antenna is located in the middle of the phone. |
BOTTOM | NFC antenna is located at the bottom of the phone. |
SWIPE | Antenna position unknown; instructs user to swipe/move phone across document. |
DocumentNFCLocation Enum
Value | Description |
|---|---|
FRONT_COVER | NFC chip is located in the front cover of the document. |
INSIDE_PAGE | NFC chip is located in an inside page or back cover. |
NO_NFC | Document does not contain a contactless NFC chip. |
DocumentType Enum
Value | Description |
|---|---|
PASSPORT | Passport document with MRZ. |
ID | Identity Card document with MRZ. |
RESIDENT_CARD | Residence Permit Card document with MRZ. |
UNKNOWN | Document type unknown or unclassified. |
Data Groups Specification (ICAO Doc 9303)
The DataGroupId enum specifies the logical data structures (LDS) to read from the document's contactless chip, defined according to ICAO Doc 9303:
Name | Description (ICAO Doc 9303 Specification) | |
|---|---|---|
COM | Header & Data Group Map | Header information containing Logical Data Structure (LDS) version, Unicode version, and tag list of present Data Groups. |
DG1 | Machine Readable Zone (MRZ) | Primary document details including Document Type, Issuing State, Document Number, Expiration Date, Holder's Name, Date of Birth, Sex, and Nationality. |
DG2 | Encoded Biometric - Facial Image | High-resolution face image of the document holder used for 1:1 facial comparison and verification. |
DG3 | Encoded Biometric - Fingerprint(s) | Biometric template data for holder's fingerprint(s) (requires Extended Access Control - EAC). |
DG4 | Encoded Biometric - Iris Feature(s) | Biometric template data for holder's iris image(s) (requires Extended Access Control - EAC). |
DG5 | Displayed Portrait | Visual portrait image as displayed/printed on the physical document page. |
DG6 | Reserved / Optional Biometric | Reserved for future biometric features in ICAO LDS. |
DG7 | Displayed Signature / Mark | High-resolution image of the holder's signature or usual mark as displayed/printed on the document. |
DG8 | Data Feature(s) | Security features and physical data elements embedded in the document. |
DG9 | Structure Feature(s) | Physical structure features of the document substrate. |
DG10 | Substance Feature(s) | Special substance and material security elements embedded in the document. |
DG11 | Additional Personal Detail(s) | Extended holder information: full name in local/national character set, place of birth, full address, telephone number, personal number, custody info, and spouse details. |
DG12 | Additional Document Detail(s) | Extended document issuing details: issuing authority, date/time of system inscription, endorsements/observations, tax/exit requirements, and front/back page images. |
DG13 | Optional Detail(s) | Issuer-specific or country-specific national extension data. |
DG14 | Security Options | Security protocol information including Chip Authentication (CA) and Terminal Authentication (TA) public keys / parameters (EAC). |
DG15 | Active Authentication Public Key | Active Authentication (AA) public key info used to verify that the contactless chip is genuine and not cloned. |
DG16 | Person(s) to Notify | Emergency contact person(s) details. |
SOD | Document Security Object | Contains cryptographic hashes of all populated Data Groups, digitally signed by the Document Signer (DS) certificate. |
CVCA | Card Verifiable CA Reference | References and key identifiers for Card Verifiable Certificate Authority used in Extended Access Control (EAC). |
TutorialProvider
TutorialProvider is a utility class providing real-time guidance and animations tailored to the physical NFC antenna position on the user's device.
Configuration (SDKExperience)
Property | Type | Default | Description |
|---|---|---|---|
serviceAddress | String | "https://proofing.app.proofing.zz3.io/sdk-experience/" | Base endpoint URL of the SDK Experience service. |
apiKey | String | None (Required) | Customer API key for authenticating with SDK Experience platform. |
assetsAddress | String | "https://sdk-experience-platform.app.proofing.zz3.io/assets/animations/" | Content delivery network URL hosting Lottie animation assets. |
API Methods
Method | Parameters | Return Type | Description |
|---|---|---|---|
getTutorialProvider | context: Context, sdkExperience: SDKExperience ? = null | TutorialProvider | Companion factory method for creating TutorialProvider. |
getNFCLocation | mrz: String, listener: NFCLocationListener | Unit | Asynchronously fetches NFC location via callback. |
getNFCLocation | mrz: String (suspend) | NFCLocationResult | Asynchronously fetches NFC location via Coroutines. |
getAnimation | phoneNFCLocation: PhoneNFCLocation, documentNFCLocation: DocumentNFCLocation, documentType: DocumentType, documentFeature: String?, listener: AnimationListener | Unit | Asynchronously fetches Lottie animation via callback. |
getAnimation | phoneNFCLocation: PhoneNFCLocation, documentNFCLocation: DocumentNFCLocation, documentType: DocumentType, documentFeature: String? (suspend) | AnimationResult | Asynchronously fetches Lottie animation via Coroutines. |
AnimationListener
Method | Parameters | Return Type | Description |
|---|---|---|---|
onAnimationProvided | animation: ByteArray | Unit | Called when Lottie animation has been provided. |
onFailure | failure: AnimationFetchFailure | Unit | Called when fetching animation fails. |
NFCLocationListener
Method | Parameters | Return Type | Description |
|---|---|---|---|
onNFCLocation | nfcLocation: NFCLocation | Unit | Called when NFC and document location info is successfully retrieved. |
onFailure | failure: LocationFetchFailure | Unit | Called when fetching NFC location fails. |
AnimationResult & Models
AnimationFetchSuccess: Animation in Lottie format.AnimationFetchFailure: Information about why the animation could not be retrieved.
AnimationFetchSuccess Properties
Property | Type | Description |
|---|---|---|
animation | ByteArray | Animation in Lottie format. |
AnimationFetchFailure Properties
Property | Type | Description |
|---|---|---|
message | String | Description of the failure. |
type | TutorialFailure | General failure cause enum. |
NFCLocationResult & Models
NFCLocation: Information about NFC antenna location on document and phone.LocationFetchFailure: Information about why the antenna location of document and phone could not be retrieved.
NFCLocation Properties
Property | Type | Description |
|---|---|---|
phoneNFCLocation | List<PhoneNFCLocation> | NFC antenna location on phone. If unknown, returns a list of possible locations. |
documentNFCLocation | DocumentNFCLocation | Location of NFC chip on document. |
documentType | DocumentType | Document type which has MRZ. |
documentFeature | String? | Additional information about the document. |
LocationFetchFailure Properties
Property | Type | Description |
|---|---|---|
message | String | Description of the failure. |
type | TutorialFailure | General failure cause enum. |
TutorialFailure Enum
Failure Type | Description |
|---|---|
CONNECTION_ISSUE | Cannot connect with external server. |
NO_INTERNET_CONNECTION | No internet connection. |
SERVER_ERROR | Server side error occurred. |
MRZ_ISSUE | Issue with parsing MRZ. |
READING_ISSUE | Fetching information about NFC and animation issue occurred. Can be related with data converting. |
DOCUMENT_TYPE_ISSUE | It only occurs when there is no such animation for chosen DocumentType. |
UNSUPPORTED_DEVICE | Device does not support NFC or it's disabled. |
REQUEST_ERROR | Fetching information about NFC and animation is impossible because of too many requests to server has been made or API key request limit has been exceeded. |
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
Kotlin1// Local resources (default)2val tutorialProvider = TutorialProvider.getTutorialProvider(context)34// OR with remote SDK Experience configuration (using nfcApiKey / GIPS-UA)5val sdkExperience = SDKExperience(apiKey = nfcApiKey)6val tutorialProvider = TutorialProvider.getTutorialProvider(context, sdkExperience)
Step 2: Fetch NFC Location and Animation
Option A: Using Callbacks
Kotlin1tutorialProvider.getNFCLocation(mrzString, object : NFCLocationListener {2 override fun onNFCLocation(nfcLocation: NFCLocation) {3 val phoneLocation = nfcLocation.phoneNFCLocation.first()45 tutorialProvider.getAnimation(6 phoneNFCLocation = phoneLocation,7 documentNFCLocation = nfcLocation.documentNFCLocation,8 documentType = nfcLocation.documentType,9 documentFeature = nfcLocation.documentFeature,10 listener = object : AnimationListener {11 override fun onAnimationProvided(animation: ByteArray) {12 // Load animation ByteArray into your Lottie animation view13 }1415 override fun onFailure(failure: AnimationFetchFailure) {16 // Handle animation fetch error17 }18 }19 )20 }2122 override fun onFailure(failure: LocationFetchFailure) {23 // Handle location fetch error24 }25})
Option B: Using Kotlin Coroutines (suspend)
Kotlin1lifecycleScope.launch {2 when (val locationResult = tutorialProvider.getNFCLocation(mrzString)) {3 is NFCLocation -> {4 val phoneLocation = locationResult.phoneNFCLocation.first()56 when (val animResult = tutorialProvider.getAnimation(7 phoneNFCLocation = phoneLocation,8 documentNFCLocation = locationResult.documentNFCLocation,9 documentType = locationResult.documentType,10 documentFeature = locationResult.documentFeature11 )) {12 is AnimationFetchSuccess -> {13 val lottieBytes = animResult.animation14 // Load lottieBytes into your Lottie animation view15 }16 is AnimationFetchFailure -> { /* Handle animation failure */ }17 }18 }19 is LocationFetchFailure -> { /* Handle location failure */ }20 }21}
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:
Kotlin1val offlineSettings = OfflineUseCaseSettings(2 // Request specific Data Groups required by your use case3 dataGroupIds = setOf(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 logLevel = LogLevel.NONE10)
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: List<String>?. Note: This must be the master list of certificates; delta LDIF files are not supported. - Document Signer CRLs (
dsClrLdif): Provide Document Signer Certificate Revocation Lists (CRLs) in LDIF format viadsClrLdif: List<String>?. - Automatic Storage: During offline reading, any provided
cscaLdifordsClrLdiflists are automatically stored in local storage (LocalPkdRepository). - Missing Certificate Error: If no CSCA certificate exists in local storage and
cscaLdifis null/empty,MissingCertificateExceptionwill be thrown.
Kotlin1val cscaLdifList: List<String> = loadCscaLdifFromAssets(context)2val dsClrLdifList: List<String> = loadDsClrLdifFromAssets(context)34val offlineSettings = OfflineUseCaseSettings(5 dataGroupIds = setOf(DataGroupId.DG1, DataGroupId.DG2),6 cscaLdif = cscaLdifList,7 dsClrLdif = dsClrLdifList,8 logLevel = LogLevel.DEBUG9)
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.
Kotlin1val debugReplaySettings = OfflineUseCaseReplaySettings(2 dumpScenarioData = true,3 dumpSerialisedSession = true,4 onDumpCreated = { dumpedByteArray ->5 saveDumpToFile(dumpedByteArray)6 }7)
Summary Matrix
Mode | Internet Connection | Highlights |
|---|---|---|
| Offline | Not Required | Operates fully locally using client-provided certificates; requires license preparation. |
| Online | Required | Real-time online verification via NFC Server; requires license preparation. |