DOT Android NFC library

v8.5.2

Introduction

DOT 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

DOT Android NFC has the following requirements:

Minimum Android API level 21
Minimum Kotlin Gradle plugin version 1.6.0 (if used)

Distribution

Maven Repository

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

In order to integrate DOT Android NFC into your project, the first step is to include the Innovatrics maven repository and Google repository to your top level build.gradle file.

build.gradle

allprojects {
    repositories {
        maven {
            url 'https://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependency on DOT Android NFC library in the module’s build.gradle file. Dependencies of this library will be downloaded alongside the library.

build.gradle

dependencies {
    //…
    implementation "com.innovatrics.dot:dot-nfc:$dotVersion"
    //…
}

Licensing

In order to use DOT 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:

build.gradle

defaultConfig {
    applicationId "com.innovatrics.dot.sample"
    //…
}

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

DOT 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

DOT 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 DOT SDK with the license and DotNfcLibrary object.

InitializeDotSdkUseCase class in the Samples project shows how to initialize DOT SDK with DotNfcLibrary. DotSdk.initialize() method should be called on background thread.

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. We recommend to check the SDK initialization status (using DotSdk.isInitialized() method) in your Fragment’s onViewCreated(). This technique is implemented in the Samples project.

Deinitialization

When a process (e.g. onboarding) using the DOT Android NFC has been completed, it is usually a good practice to free the resources used by it.

You can perform this by calling DotSdk.deinitialize(). If you want to use the DOT Android NFC components again after that point, you need to call DotSdk.initialize() again. This shouldn’t be performed within the lifecycle of individual Android components.

Logging

Although logging is disabled by default, it can be enabled explicitly by using the following method from the com.innovatrics.dot.core.Logger class.

Logger.setLoggingEnabled(true)

The appropriate place for this call is within the onCreate() method of your subclass of android.app.Application. Each TAG of a log message starts with the prefix dot-nfc:.

This setting enables logging for all DOT Android libraries.

Keep in mind that logging should be used just for debug purposes as it might produce a lot of log messages.

Components

Overview

DOT Android NFC provides a non-UI component for NFC reading. You may build your own UI using the DOT 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 travelDocument = 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 TravelDocument data class.

val travelDocument = 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_searching_title">Searching for NFC chip…</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_reading_title">Hold still</string>
<string name="dot_nfc_nfc_travel_document_reader_reading_subhead">Please keep both device and document still.</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.

Technical release. No changes.

8.5.1 - 2024-10-28

Technical release. No changes.

8.5.0 - 2024-10-24

Technical release. No changes.

8.4.0 - 2024-09-11

Added

Interface Password.
Class Password.MachineReadableZone.
Class Password.CardAccessNumber.
Methods NfcTravelDocumentReader.read() with password argument.
Property NfcTravelDocumentReaderFragment.Configuration.password.

Changed

Deprecated NfcKey, use Password.MachineReadableZone instead.
Deprecated NfcTravelDocumentReader.read() methods with nfcKey argument, use methods with password argument instead.
Deprecated constructor of NfcTravelDocumentReaderFragment.Configuration with nfcKey argument.

8.3.3 - 2024-09-05

Technical release. No changes.

8.3.2 - 2024-09-05

Added

Method NfcTravelDocumentReader.cancel().
Method NfcTravelDocumentReaderFragment.onSearchingStarted().
Method NfcTravelDocumentReaderFragment.onReadingStarted().

Changed

Drawable resource dot_nfc_nfc_travel_document_reader_searching.

DOT Android NFC library

v8.5.2#

v8.5.2