IDV Android NFC library

v9.6.0

Introduction

IDV Android NFC provides a component for NFC reading which is easy to integrate into an Android application. Supported documents are those which implement ICAO Doc 9303: Machine Readable Travel Documents as specified by International Civil Aviation Organization (ICAO).

Requirements

IDV Android NFC has the following requirements:

Minimum Android API level 24
Minimum Kotlin Gradle plugin version 1.7.0 (if used)

Distribution

Maven Repository

IDV Android NFC is distributed as an Android library (.aar package) stored in the Innovatrics maven repository.

In order to integrate IDV Android NFC into your project, the first step is to include the Innovatrics maven repository to your settings.gradle.kts file.

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        maven {
            url = URI("https://maven.innovatrics.com/releases")
        }
    }
}

Then, specify the dependency on IDV Android NFC library in the build.gradle.kts file. Dependencies of this library will be downloaded alongside the library.

build.gradle.kts

dependencies {
    implementation("com.innovatrics.dot:dot-nfc:$dotVersion")
}

Licensing

In order to use IDV SDK in other apps, it must be licensed. The license can be compiled into the application as it is bound to the application ID specified in build.gradle.kts:

build.gradle.kts

android {
    defaultConfig {
        applicationId = "com.innovatrics.dot.samples"
    }
}

The application ID can be also retrieved in runtime by calling DotSdk.getApplicationId().

In order to obtain the license, please contact your Innovatrics’ representative specifying the application ID. If the application uses build flavors with different application IDs, each flavor must contain a separate license. Put the license file into the raw resource folder.

Permissions

IDV Android NFC declares the following permission in AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.INTERNET" />

Transaction Reporting

IDV Android NFC reports transactions to a remote service. Read more details in the Product Documentation.

Basic Setup

Initialization

Before using any of the components, you need to initialize IDV SDK with the license and DotNfcLibraryConfiguration object.

DotSdkInitializer object in the Samples project shows how to initialize IDV SDK with DotNfcLibraryConfiguration. DotSdk.initialize() method should be called on background thread. Route all calls to DotSdk.initialize() and DotSdk.deinitialize() through a single owner (as DotSdkInitializer does for initialize() in the Samples app), and let that owner perform the DotSdk.isInitialized() check that guards them. Otherwise two threads can both see isInitialized() return false, both call initialize(), and the second call throws (a check-then-act race). Reading DotSdk.isInitialized() on its own needs no such coordination, but the call is not lock-free: it blocks while an initialize() or deinitialize() is running on another thread, so reading it on the main thread (for example in a Fragment’s onViewCreated()) while initialization is in progress can freeze the UI. Read it before you start initialization, or track your own initialization state and observe that instead. Only the check-then-initialize/deinitialize sequence must not run concurrently.

Keep in mind that if you try to use any component without initialization, it will throw an exception. Also be aware that while the app is in background, the system may kill the process to free resources. In such a case, you need to reinitialize the SDK when the app is brought back to the foreground. As explained above, route this check-and-reinitialize through the single owner and observe your own initialization state instead of reading DotSdk.isInitialized() on the main thread while an initialization may be running. You can trigger this from your Fragment’s onViewCreated(). This technique is implemented in the Samples project.

Deinitialization

Deinitialization is optional. IDV SDK keeps its native models in process-scoped memory that the operating system reclaims automatically when the process is terminated, so DotSdk.deinitialize() is not required for correctness and is not needed to avoid memory leaks.

Its only purpose is to release that memory footprint earlier, before the process ends, when you know IDV SDK will not be used again for a while. Reloading the models on the next DotSdk.initialize() is expensive, so deinitialize sparingly: at most once, at a quiescent point when leaving the flow (for example when the user finishes or cancels onboarding). Do not deinitialize within the lifecycle of individual Android components (onDestroy(), configuration changes such as screen rotation, or background-to-foreground transitions) - doing so causes repeated, costly deinitialize/initialize cycles. When in doubt, skip deinitialization.

DotSdk.deinitialize() must be called on a background thread. After deinitializing, call DotSdk.initialize() again before using IDV SDK components.

Components

Overview

IDV Android NFC provides a non-UI component for NFC reading. You may build your own UI using the IDV Android NFC functionality.

List of Non-UI Components

NFC TRAVEL DOCUMENT READER: The component for reading NFC enabled travel documents.
FLAT TAG STRUCTURE PARSER: The component for parsing flat tag structure in a data group as defined in Doc 9303.

List of UI Components

UI NFC TRAVEL DOCUMENT READER: A visual component for reading NFC enabled travel documents.

Non-UI Components

NFC Travel Document Reader

The NfcTravelDocumentReader interface provides NFC reading functionality.

Create a NfcTravelDocumentReader:

val certificates = CertificatesFactory.create(inputStream)
val configuration = NfcTravelDocumentReader.Configuration(
    authorityCertificates = certificates,
    //…
)
val nfcTravelDocumentReader = NfcTravelDocumentReaderFactory.create(configuration)

To read NFC data, call the following method on the background thread:

val result = nfcTravelDocumentReader.read(tag, password)

Tag represents NFC Tag discovered by NfcAdapter. Password is read either from the Machine Readable Zone or it is the value of Card Access Number.

In case, when server-side authentication of the chip is required, use the read() method with activeAuthenticationChallenge argument. If the Active Authentication protocol is supported by the chip, it will be used for the authentication of the chip and the response (signature) will be returned in NfcTravelDocumentReaderResult data class.

val result = nfcTravelDocumentReader.read(tag, password, activeAuthenticationChallenge)

Flat Tag Structure Parser

The FlatTagStructureParser interface parses a byte array into a flat map of data elements.

Create a FlatTagStructureParser:

val flatTagStructureParser = FlatTagStructureParserFactory.create()

To parse a Data Group value, call the following method:

val elements: Map<Short, ByteArray> = flatTagStructureParser.parse(bytes)

Following data structure is expected as an input:

ELEMENT_1_TAG, ELEMENT_1_LENGTH, ELEMENT_1_VALUE, ..., ELEMENT_N_TAG, ELEMENT_N_LENGTH, ELEMENT_N_VALUE

Such a value is parsed into this map:

Table 1. Map of Data Elements
Tag	Value
`ELEMENT_1_TAG`	`ELEMENT_1_VALUE`
…	…
`ELEMENT_N_TAG`	`ELEMENT_N_VALUE`

For example, let the Data Group value be:

\u005C\u0002\u005F\u005B\u005F\u005B\u0008SPECIMEN

Then the resulting map is as follows:

Table 2. Example of a map of Data Elements
Tag	Length	Value
`0x5C`	`0x02`	`0x5F_5B`
`0x5F_5B`	`0x08`	`SPECIMEN` (shown as text for readability)

Some country authorities may use this structure in the Optional Details. This data is present in TravelDocument.optionalDetails as a result of the NFC reading.

UI Components

UI NFC Travel Document Reader

A ready-to-use component for incorporating NFC reading capabilities into your application. It includes a set of UI elements to guide the user through the NFC reading process.

This component is based on a Fragment from AndroidX. In order to use it, an abstract NfcTravelDocumentReaderFragment must be subclassed.

The NfcTravelDocumentReaderFragment requires a configuration. To provide configuration data, you should override the provideConfiguration() method in your subclass implementation. This method should return an instance of the NfcTravelDocumentReaderFragment.Configuration data class with the desired parameters.

Override the onSucceeded method to handle successful NFC document reading. Similarly, override the onFailed method to manage reading failures.

The reading process of the NFC Travel Document is tied to the fragment’s lifecycle. To cancel the reading process, simply transition the fragment to the destroyed state, for example, by navigating to another fragment.

UI of the fragment can be customized. There are two options for customization:

Overwriting resources
Providing custom view

Overwriting Resources

You can partially customize the UI by replacing the component’s default resources with your own. The following resources are expected by the component:

Strings

You can override the string resources and provide alternative strings for supported languages using the standard Android localization mechanism.

<string name="dot_nfc_nfc_travel_document_reader_reading_subhead">Please keep both device and document still.</string>
<string name="dot_nfc_nfc_travel_document_reader_reading_title">Hold still</string>
<string name="dot_nfc_nfc_travel_document_reader_searching_subhead">Slide your phone gently on the surface of the document until we find the right position.</string>
<string name="dot_nfc_nfc_travel_document_reader_searching_title">Searching for NFC chip…</string>

Styles

Text views can be styled by overriding the parent style in the application. To customize the appearance of text views, you can override the following styles:

<style name="Dot.Title" parent="TextAppearance.AppCompat.Title" />
<style name="Dot.Subhead" parent="TextAppearance.AppCompat.Subhead" />

Drawables

You can also override the following drawable resources.

R.drawable.dot_nfc_nfc_travel_document_reader_reading
R.drawable.dot_nfc_nfc_travel_document_reader_searching

The type of R.drawable.dot_nfc_nfc_travel_document_reader_searching must be AnimatedVectorDrawable.

Providing a custom view

For full customization, you can pass a custom layout via constructor or you can supply a custom view by overriding the onCreateView method. If you choose this option, you must also override the onSearchingStarted and onReadingStarted methods to ensure your UI reflects the appropriate state during the document searching and reading processes.

Improved SDK initialization and deinitialization documentation.

9.5.0 - 2026-06-30

Changed

Renamed product to IDV (Identity Verification).

9.4.2 - 2026-06-05

Technical release. No changes.

9.4.1 - 2026-06-05

Technical release. No changes.

9.4.0 - 2026-05-29

Technical release. No changes.

9.3.0 - 2026-05-06

Technical release. No changes.

9.2.4 - 2026-04-27

Technical release. No changes.

9.2.3 - 2026-04-23

Technical release. No changes.

9.2.2 - 2026-04-01

Technical release. No changes.

9.2.1 - 2026-03-20

Technical release. No changes.

9.2.0 - 2026-02-27

Technical release. No changes.

9.1.0 - 2026-02-12

Changed

Target Android API level to 36.

9.0.2 - 2026-01-22

Changed

Minimum Kotlin Gradle plugin version to 1.7.0.
AdditionalPersonalDetails.address can now contain empty strings if they are present in the travel document.
Data Authentication now supports signatures that use non-standard signature algorithm identifiers.

9.0.1 - 2026-01-08

Technical release. No changes.

9.0.0 - 2025-12-16

Added

Class DotSdk.Configuration.
Class Libraries.
Class DotNfcLibraryConfiguration.
Class CommonConfiguration.
Property NfcTravelDocumentReaderFragment.Configuration.common.

Changed

Class NfcTravelDocumentReaderException to NfcTravelDocumentReader.ReadException.
Class NotConnectedException to NfcTravelDocumentReader.NotConnectedException.
Class AccessControlExpection to NfcTravelDocumentReader.AccessControlException.
Class ChipAuthenticationException to NfcTravelDocumentReader.ChipAuthenticationException.
Class NfcTravelDocumentReaderFragment.Configuration is no longer @Serializable.

Removed

Class DotSdkConfiguration. Use DotSdk.Configuration instead.
Class Logger.
Constructor of NfcTravelDocumentReaderFragment.Configuration with nfcKey argument.
Class NfcKey. Use com.innovatrics.dot.nfc.access.Password instead.
Method NfcTravelDocumentReader.read(tag: Tag, nfcKey: NfcKey, activeAuthenticationChallenge: ByteArray?). Use method NfcTravelDocumentReader.read(tag: Tag, password: Password, activeAuthenticationChallenge: ByteArray?) instead.
Method NfcTravelDocumentReader.read(tag: Tag, nfcKey: NfcKey, activeAuthenticationChallenge: ByteArray?, listeners: Listeners). Use method NfcTravelDocumentReader.read(tag: Tag, password: Password, activeAuthenticationChallenge: ByteArray?, listeners: Listeners) instead.
Class NfcTravelDocumentReaderConfiguration. Use NfcTravelDocumentReader.Configuration instead.
Method NfcTravelDocumentReaderFactory.create(configuration: NfcTravelDocumentReaderConfiguration). Use method NfcTravelDocumentReaderFactory.create(configuration: NfcTravelDocumentReader.Configuration) instead.
Property NfcTravelDocumentReaderFragment.Configuration.sessionToken. Use com.innovatrics.dot.core.ui.configuration.CommonConfiguration instead.

IDV Android NFC library

v9.6.0#

v9.6.0