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, or nfcApiKey (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 KeyEnvironmentsserverUrl & nfcApiKeyOnline Sample App only
IPV Backend API KeyEnvironmentsipvApiKeyOnline Sample App only
LKMS & ArtifactorySDK Artifactory & LicenseslkmsProfileId, lkmsApiKey, artifactoryUserMI, artifactoryPasswordMIBoth 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):

Groovy
1# Required for Online Sample App
2serverUrl="YOUR_PROOFING_PLATFORM_URL"
3nfcApiKey="YOUR_NFC_API_KEY" # GIPS-UA
4ipvApiKey="YOUR_IPV_API_KEY" # GIPS RS
5
6# Required for Both Online & Offline Sample Apps
7artifactoryUserMI="YOUR_ARTIFACTORY_USER"
8artifactoryPasswordMI="YOUR_ARTIFACTORY_CREDENTIALS"
9repositoryUrlMI="https://artifacts.ips.idemia.com/artifactory/smartsdk-android-local"
10
11lkmsProfileId="YOUR_LKMS_PROFILE_ID"
12lkmsApiKey="YOUR_LKMS_API_KEY"

Step 3: Fetch & Execute 

  1. Download the sample application source code package (.zip) from Artifactory depending on your target operational mode:
  2. Open the project in Android Studio.
  3. Verify that your environment configurations are correctly referenced from gradle.properties.
  4. 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):

Groovy
1buildscript {
2 repositories {
3 maven {
4 url = "$repositoryUrlMI"
5 credentials {
6 username = "$artifactoryUserMI"
7 password = "$artifactoryPasswordMI"
8 }
9 }
10 // ... other repositories
11 }
12}

2. Artifactory Credentials & API Keys 

Define repository properties and API keys in your local gradle.properties file:

Properties
1artifactoryUserMI=artifactory_user
2artifactoryPasswordMI=artifactory_credentials
3repositoryUrlMI=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.properties prevents 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:

Gradle
1dependencies {
2 // SmartNFC Library (v3.0.0+)
3 implementation ("com.idemia.smartsdk:smart-nfc:$smartNfcVersion")
4
5 // 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

Kotlin
1val nfcReader = NFCReader(activity)

ℹ️ NFCReader uses the provided Activity context directly to turn on and manage hardware support for NFC scanning.

2. Configure OfflineUseCase

Kotlin
1val offlineCallbacks = object : OfflineUseCaseCallbacks {
2 override fun readingProgressUpdated(progress: Float) {
3 // Update UI progress (0.0 to 1.0)
4 }
5
6 override fun readingFinished(result: OfflineUseCaseResult) {
7 // Handle offline reading result
8 }
9}
10
11val offlineSettings = OfflineUseCaseSettings(
12 dataGroupIds = setOf(DataGroupId.DG1, DataGroupId.DG2),
13 cscaLdif = cscaLdifList, // Provided entirely by the client
14 logLevel = LogLevel.NONE
15)
16
17val offlineUseCase = OfflineUseCase(
18 documentAccessData = MRZDocumentAccessData(mrz = "SAMPLE_MRZ"),
19 phoneNFCLocation = PhoneNFCLocation.TOP,
20 settings = offlineSettings,
21 callbacks = offlineCallbacks
22)

3. License Activation & Start Reading

Kotlin
1lifecycleScope.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)
9
10 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 resulting sessionId from your backend via your own API. Instantiating backend services directly on the mobile client is demonstrated in the sample app for convenience only.

Server-side creation of 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.

Kotlin
1// Backend Representation / Sample App Reference: Creating session via GIPS API
2val serverConfigurationData = ServerConfigurationData(
3 serverUrl = "https://your-proofing-platform-url.com/gips/",
4 serverApiKey = ipvApiKey // ipvApiKey (GIPS RS) kept secure on the backend
5)
6
7// 1. Create identity
8val identity = IdentityService(serverConfigurationData).createIdentity()
9
10// 2. Create NFC session using identity ID and document MRZ lines
11val session = SessionService(serverConfigurationData).createSession(
12 identity.id,
13 MRZData(mrzResult.mrzLines)
14)
15
16val sessionId = session.sessionId ?: throw IllegalStateException("Session ID is null")

1. Instantiate NFCReader

Kotlin
1val nfcReader = NFCReader(activity)

ℹ️ NFCReader uses the provided Activity context directly to turn on and manage hardware support for NFC scanning.

2. Configure OnlineUseCase

Kotlin
1val onlineCallbacks = object : OnlineUseCaseCallbacks {
2 override fun readingProgressUpdated(progress: Float) {
3 // Update UI progress (0.0 to 1.0)
4 }
5
6 override fun readingFinished(result: OnlineUseCaseResult) {
7 // Handle online reading result
8 }
9}
10
11val onlineSettings = OnlineUseCaseSettings(
12 environmentInfo = EnvironmentInfo(
13 nfcServerUrl = "https://your-nfc-server-url.com/api",
14 nfcServerApiKey = nfcApiKey // nfcApiKey (GIPS-UA) obtained from Experience Portal
15 ),
16 logLevel = LogLevel.NONE
17)
18
19val onlineUseCase = OnlineUseCase(
20 documentAccessData = MRZDocumentAccessData(mrz = "SAMPLE_MRZ"),
21 phoneNFCLocation = PhoneNFCLocation.TOP,
22 sessionID = sessionId, // Obtained from session creation step above
23 settings = onlineSettings,
24 callbacks = onlineCallbacks
25)

3. License Activation & Start Reading

Kotlin
1lifecycleScope.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)
9
10 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:

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_EXPIREDProfile expired, all licenses won’t work anymore. (Contact support)
ACTIVATION_COUNT_EXCEEDEDNo more licenses can be consumed. (Contact support)
AUTHENTICATION_ISSUECredentials and/or profile information are wrong.
CONNECTION_ISSUEConnection issue. Make sure that your internet connection is stable.
UNKNOWNUnknown 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
startOnlineUseCase or OfflineUseCaseUnitStarts the document reading procedure on a working thread.
cancelNoneUnitCancels current reading procedure. Triggers FailureType.CANCELED.
isDeviceCompatibleNoneBooleanChecks if device satisfies NFC hardware/software requirements.
enableAnalyticsnetwork: Network, analyticsConfigurationData: AnalyticsConfigurationDataUnitEnables analytics collection with network configuration.
disableAnalyticsNoneUnitDisables 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
documentAccessDataDocumentAccessDataNone (Required)Data required to access document (e.g., MRZDocumentAccessData).
phoneNFCLocationPhoneNFCLocationNone (Required)Antenna position on the device.
sessionIDStringNone (Required)Session identifier created on the NFC Server.
settingsOnlineUseCaseSettingsNone (Required)Server environment info and log level settings.
callbacksOnlineUseCaseCallbacksNone (Required)Callback handler for progress and completion results.

OfflineUseCase

Used for offline verification workflows.

Parameter
Type
Default
Description
documentAccessDataDocumentAccessDataNone (Required)Data required to access document.
phoneNFCLocationPhoneNFCLocationNone (Required)Antenna position on the device.
settingsOfflineUseCaseSettingsNone (Required)Configures dataGroupIds, cscaLdif, dsClrLdif, replaySettings, and logLevel.
callbacksOfflineUseCaseCallbacksNone (Required)Callback handler for progress and completion results.

3. Settings & Configurations 

OnlineUseCaseSettings & EnvironmentInfo

Parameter
Type
Default
Description
environmentInfoEnvironmentInfoNone (Required)Configuration for the server environment (nfcServerUrl and nfcServerApiKey).
logLevelLogLevelNone (Required)Desired logging verbosity (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE).
nfcServerUrlStringNone (Required)Base URL of the NFC Server endpoint.
nfcServerApiKeyStringNone (Required)Customer API key for server authentication.

OfflineUseCaseSettings

Parameter
Type
Default
Description
dataGroupIdsSet<DataGroupId>setOf(DataGroupId.DG1)The set of Data Groups to be read from the document chip.
cscaLdifList<String>?nullCSCA certificates in LDIF format supplied by the client for Passive Authentication.
dsClrLdifList<String>?nullDocument Signer Certificate Revocation Lists (CRLs) supplied by the client.
replaySettingsOfflineUseCaseReplaySettingsnullOptional settings for scenario dumping or replaying.
logLevelLogLevelLogLevel.NONEDesired logging verbosity (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE).

OfflineUseCaseReplaySettings

Parameter
Type
Default
Description
replayScenarioDataByteArray?nullBinary data for replaying a previously captured offline session.
dumpScenarioDataBooleanfalseWhether to dump current scenario data.
dumpSerialisedSessionBooleanfalseWhether to dump the serialized session data.
onDumpCreated((ByteArray) -> Unit)?nullCallback triggered when a debug dump is successfully created.

NFCConfiguration

Parameter
Type
Default
Description
serverUrlString"https://proofing.app.proofing.zz3.io/nfc/"Base endpoint URL of the target NFC server.
serverApiKeyStringNone (Required)Server API key for authentication.
logLevelLogLevelLogLevel.NONELog level applied to network operations (LogLevel.INFO, LogLevel.DEBUG, LogLevel.ERROR, LogLevel.NONE).

4. Listeners & Callbacks 

OnlineUseCaseCallbacks

Method
Parameters
Return Type
Description
readingProgressUpdatedprogress: Float (FloatRange 0.0 .. 1.0)UnitInvoked when reading progress updates (progress in range 0.0 .. 1.0).
readingFinishedresult: OnlineUseCaseResultUnitInvoked when online reading process completes.

OfflineUseCaseCallbacks

Method
Parameters
Return Type
Description
readingProgressUpdatedprogress: Float (FloatRange 0.0 .. 1.0)UnitInvoked when reading progress updates (progress in range 0.0 .. 1.0).
readingFinishedresult: OfflineUseCaseResultUnitInvoked when offline reading process completes.

ResultListener

Method
Parameters
Return Type
Description
onSuccessNoneUnitCalled on the Main Thread when document reading completes successfully.
onFailurefailure: FailureUnitCalled on the Main Thread when document reading fails.

ProgressListener

Method
Parameters
Return Type
Description
onProgressUpdatedprogress: Int (0 .. 100)UnitCalled 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
errorNFCReaderOnlineErrorDetailed information about the error.
NFCReaderOnlineError Properties
Property
Type
Description
typeFailureTypeThe type of failure.
codeIntAn error code.
messageStringA descriptive error message.
NFCReaderOnlineError.FailureType Enum
Failure Type
Description
UNKNOWNUnexpected error.
NFC_CONNECTION_BROKENNFC connection has been broken.
SERVER_CONNECTION_BROKENCannot process data with the server side, might be a compatibility issue.
SERVER_ERRORServer side error occurred.
CONNECTION_ISSUECannot connect with external server, no internet connection.
INVALID_SESSION_STATESession is in an unexpected state. New one needs to be created.
READING_ISSUEDocument reading issue occurred. Can be related with NFC issues and data converting.
UNSUPPORTED_DEVICEDevice does not support NFC or it's disabled.
CANCELEDOperation was canceled.
REQUESTS_LIMIT_EXCEEDEDDocument reading is impossible because of too many requests to server has been made or API key request limit has been exceeded.
NFC_INVALID_POSITIONNFC tag is not in valid position.
WRONG_MRZMRZ passed to 'start' method is not the same as the one scanned from NFC chip.
INVALID_LICENSEInvalid or inactive license.

Offline Reading Results (OfflineUseCaseResult)

OfflineUseCaseSuccess
Property
Type
Default
Description
statusOfflineUseCaseReadingStatusNoneStatus of offline reading & verification (READ_AND_VERIFIED, READ_AND_NOT_VERIFIED, READ_AND_INVALID).
isDocumentExpiredBooleanNoneIndicates whether the document expiry date has passed based on system time.
dataGroupsMap<DataGroupId), Map<String, String>>?NoneMap of read DataGroupId) tags to parsed key-value field data.
securityChecksSecurityChecksNoneDetailed cryptographic security check statuses (Active Authentication, Passive Authentication, CA/TA, etc.).
Helper Methods
Method
Return Type
Description
toGipsJson()StringConverts 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
typeFailureTypeNoneHigh-level failure classification enum for offline reading.
codeIntNoneNumeric error code.
messageStringNoneDescriptive error message.
NFCReaderOfflineError.FailureType Enum
Failure Type
Description
UNKNOWNUnexpected error occurred.
NFC_CONNECTION_BROKENPhysical NFC connection to document chip was interrupted.
READING_ISSUEIssue reading document chip or parsing data.
UNSUPPORTED_DEVICEDevice lacks required NFC hardware or NFC is disabled.
CANCELEDOperation was canceled by the user.
NFC_INVALID_POSITIONNFC tag/passport is not in a valid reading position against device antenna.
MISSING_CERTIFICATENFC reading was started without CSCA certificate required for authentication.
WRONG_MRZMRZ provided in start() does not match MRZ read from physical chip.
INVALID_LICENSEInvalid or inactive license.

OfflineUseCaseReadingStatus Enum
Status
Description
READ_AND_VERIFIEDDocument data was read and all cryptographic security checks passed.
READ_AND_NOT_VERIFIEDDocument data was read, but security checks could not be concluded (e.g. missing CSCA certificates).
READ_AND_INVALIDDocument data was read, but security verification failed (e.g., hash mismatch or bad signature).
ERRORAn error occurred during the reading process.
SecurityChecks

Detailed cryptographic security check statuses evaluated during offline reading:

Property
Type
Default
Description
aaStatusSecurityCheckStatusNoneActive Authentication (AA) status (verifies chip genuineness).
caStatusSecurityCheckStatusNoneChip Authentication (CA) status (EAC protocol).
paHashCheckSecurityCheckStatusNonePassive Authentication Data Group hash verification status.
bacStatusSecurityCheckStatusNoneBasic Access Control (BAC) status.
paceStatusSecurityCheckStatusNonePassword Authenticated Connection Establishment (PACE) status.
paDocumentSignerCheckSecurityCheckStatusNonePassive Authentication Document Signer (DS) certificate validation status.
taStatusSecurityCheckStatusNoneTerminal Authentication (TA) status (EAC protocol).
paResultCodeInt?nullDetailed numeric result code for Passive Authentication.
paSodSignatureCheckSecurityCheckStatusNonePassive Authentication SOD digital signature verification status.
SecurityCheckStatus Enum
Value
Description
VERIFIEDThe security check was executed and successfully verified (positive result).
NOT_VERIFIEDThe security check could not be performed or completed (e.g. missing certificate/key).
FAILEDThe 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
TOPNFC antenna is located at the top of the phone.
MIDDLENFC antenna is located in the middle of the phone.
BOTTOMNFC antenna is located at the bottom of the phone.
SWIPEAntenna position unknown; instructs user to swipe/move phone across document.

DocumentNFCLocation Enum

Value
Description
FRONT_COVERNFC chip is located in the front cover of the document.
INSIDE_PAGENFC chip is located in an inside page or back cover.
NO_NFCDocument does not contain a contactless NFC chip.

DocumentType Enum

Value
Description
PASSPORTPassport document with MRZ.
IDIdentity Card document with MRZ.
RESIDENT_CARDResidence Permit Card document with MRZ.
UNKNOWNDocument 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)
COMHeader & Data Group MapHeader information containing Logical Data Structure (LDS) version, Unicode version, and tag list of present Data Groups.
DG1Machine Readable Zone (MRZ)Primary document details including Document Type, Issuing State, Document Number, Expiration Date, Holder's Name, Date of Birth, Sex, and Nationality.
DG2Encoded Biometric - Facial ImageHigh-resolution face image of the document holder used for 1:1 facial comparison and verification.
DG3Encoded Biometric - Fingerprint(s)Biometric template data for holder's fingerprint(s) (requires Extended Access Control - EAC).
DG4Encoded Biometric - Iris Feature(s)Biometric template data for holder's iris image(s) (requires Extended Access Control - EAC).
DG5Displayed PortraitVisual portrait image as displayed/printed on the physical document page.
DG6Reserved / Optional BiometricReserved for future biometric features in ICAO LDS.
DG7Displayed Signature / MarkHigh-resolution image of the holder's signature or usual mark as displayed/printed on the document.
DG8Data Feature(s)Security features and physical data elements embedded in the document.
DG9Structure Feature(s)Physical structure features of the document substrate.
DG10Substance Feature(s)Special substance and material security elements embedded in the document.
DG11Additional 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.
DG12Additional Document Detail(s)Extended document issuing details: issuing authority, date/time of system inscription, endorsements/observations, tax/exit requirements, and front/back page images.
DG13Optional Detail(s)Issuer-specific or country-specific national extension data.
DG14Security OptionsSecurity protocol information including Chip Authentication (CA) and Terminal Authentication (TA) public keys / parameters (EAC).
DG15Active Authentication Public KeyActive Authentication (AA) public key info used to verify that the contactless chip is genuine and not cloned.
DG16Person(s) to NotifyEmergency contact person(s) details.
SODDocument Security ObjectContains cryptographic hashes of all populated Data Groups, digitally signed by the Document Signer (DS) certificate.
CVCACard Verifiable CA ReferenceReferences 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
serviceAddressString"https://proofing.app.proofing.zz3.io/sdk-experience/"Base endpoint URL of the SDK Experience service.
apiKeyStringNone (Required)Customer API key for authenticating with SDK Experience platform.
assetsAddressString"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
getTutorialProvidercontext: Context, sdkExperience: SDKExperience ? = nullTutorialProviderCompanion factory method for creating TutorialProvider.
getNFCLocationmrz: String, listener: NFCLocationListenerUnitAsynchronously fetches NFC location via callback.
getNFCLocationmrz: String (suspend)NFCLocationResultAsynchronously fetches NFC location via Coroutines.
getAnimationphoneNFCLocation: PhoneNFCLocation, documentNFCLocation: DocumentNFCLocation, documentType: DocumentType, documentFeature: String?, listener: AnimationListenerUnitAsynchronously fetches Lottie animation via callback.
getAnimationphoneNFCLocation: PhoneNFCLocation, documentNFCLocation: DocumentNFCLocation, documentType: DocumentType, documentFeature: String? (suspend)AnimationResultAsynchronously fetches Lottie animation via Coroutines.

AnimationListener

Method
Parameters
Return Type
Description
onAnimationProvidedanimation: ByteArrayUnitCalled when Lottie animation has been provided.
onFailurefailure: AnimationFetchFailureUnitCalled when fetching animation fails.

NFCLocationListener

Method
Parameters
Return Type
Description
onNFCLocationnfcLocation: NFCLocationUnitCalled when NFC and document location info is successfully retrieved.
onFailurefailure: LocationFetchFailureUnitCalled 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
animationByteArrayAnimation in Lottie format.
AnimationFetchFailure Properties
Property
Type
Description
messageStringDescription of the failure.
typeTutorialFailureGeneral 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
phoneNFCLocationList<PhoneNFCLocation>NFC antenna location on phone. If unknown, returns a list of possible locations.
documentNFCLocationDocumentNFCLocationLocation of NFC chip on document.
documentTypeDocumentTypeDocument type which has MRZ.
documentFeatureString?Additional information about the document.
LocationFetchFailure Properties
Property
Type
Description
messageStringDescription of the failure.
typeTutorialFailureGeneral failure cause enum.
TutorialFailure Enum
Failure Type
Description
CONNECTION_ISSUECannot connect with external server.
NO_INTERNET_CONNECTIONNo internet connection.
SERVER_ERRORServer side error occurred.
MRZ_ISSUEIssue with parsing MRZ.
READING_ISSUEFetching information about NFC and animation issue occurred. Can be related with data converting.
DOCUMENT_TYPE_ISSUEIt only occurs when there is no such animation for chosen DocumentType.
UNSUPPORTED_DEVICEDevice does not support NFC or it's disabled.
REQUEST_ERRORFetching 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

Kotlin
1// Local resources (default)
2val tutorialProvider = TutorialProvider.getTutorialProvider(context)
3
4// 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
Kotlin
1tutorialProvider.getNFCLocation(mrzString, object : NFCLocationListener {
2 override fun onNFCLocation(nfcLocation: NFCLocation) {
3 val phoneLocation = nfcLocation.phoneNFCLocation.first()
4
5 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 view
13 }
14
15 override fun onFailure(failure: AnimationFetchFailure) {
16 // Handle animation fetch error
17 }
18 }
19 )
20 }
21
22 override fun onFailure(failure: LocationFetchFailure) {
23 // Handle location fetch error
24 }
25})
Option B: Using Kotlin Coroutines (suspend)
Kotlin
1lifecycleScope.launch {
2 when (val locationResult = tutorialProvider.getNFCLocation(mrzString)) {
3 is NFCLocation -> {
4 val phoneLocation = locationResult.phoneNFCLocation.first()
5
6 when (val animResult = tutorialProvider.getAnimation(
7 phoneNFCLocation = phoneLocation,
8 documentNFCLocation = locationResult.documentNFCLocation,
9 documentType = locationResult.documentType,
10 documentFeature = locationResult.documentFeature
11 )) {
12 is AnimationFetchSuccess -> {
13 val lottieBytes = animResult.animation
14 // Load lottieBytes into your Lottie animation view
15 }
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:

Kotlin
1val offlineSettings = OfflineUseCaseSettings(
2 // Request specific Data Groups required by your use case
3 dataGroupIds = setOf(
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 logLevel = LogLevel.NONE
10)

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: 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 via dsClrLdif: List<String>?.
  • Automatic Storage: During offline reading, any provided cscaLdif or dsClrLdif lists are automatically stored in local storage (LocalPkdRepository).
  • Missing Certificate Error: If no CSCA certificate exists in local storage and cscaLdif is null/empty, MissingCertificateException will be thrown.
Kotlin
1val cscaLdifList: List<String> = loadCscaLdifFromAssets(context)
2val dsClrLdifList: List<String> = loadDsClrLdifFromAssets(context)
3
4val offlineSettings = OfflineUseCaseSettings(
5 dataGroupIds = setOf(DataGroupId.DG1, DataGroupId.DG2),
6 cscaLdif = cscaLdifList,
7 dsClrLdif = dsClrLdifList,
8 logLevel = LogLevel.DEBUG
9)

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.

Kotlin
1val debugReplaySettings = OfflineUseCaseReplaySettings(
2 dumpScenarioData = true,
3 dumpSerialisedSession = true,
4 onDumpCreated = { dumpedByteArray ->
5 saveDumpToFile(dumpedByteArray)
6 }
7)

Summary Matrix 

Mode
Internet Connection
Highlights
OfflineNot RequiredOperates fully locally using client-provided certificates; requires license preparation.
OnlineRequiredReal-time online verification via NFC Server; requires license preparation.