SDK for Android 

Introduction 

The IDEMIA Verify SDK for Android provides customers with the resources to customize the SDK to their preferred user-experience and integrate it within an existing mobile application. The IDEMIA Mobile ID Verify App works in conjunction with the IDEMIA Mobile ID App allowing verifiers to authenticate the user's physical ID or digital credential (i.e. drivers license or identity card).

You can use the SDK to:

• Create and design your preferred user-experience and UI while leveraging the IDEMIA Verify functionalities

  You can build a custom mobile application that implements your user-experience design and leverages all of the SDK functionalities allowing you to apply your branding and preferred user flow. You maintain complete control over the display and functionality of the application.

• Embed IDEMIA Verify into an existing application

  You can automatically integrate an existing mobile application with IDEMIA by adding the SDK frameworks, which removes the need to use and maintain an additional application to leverage the Mobile ID's functionalities.

Get Started 

Skills Required 

The integration tasks should be done by developers with knowledge of:

• Android Studio
• Java/Kotlin for Android
• Android SDK
• Android operating system

Resources Required 

Integrations may be performed on PC Windows, Linux, or Macintosh.

• Android Studio Flamingo 2022.2.1 or above
• Android SDK tools: preferred latest version (release 31 or above)
• JDK: preferred latest version (8 or above)
• Android device (emulator is not supported)
• Minimum SDK version is 30 (Android 11)

Other Requirements 

Components 

The SDK is made up of the following components:

• IDVerifyTerminal acts as the entry point for initializing device engagement. It sends the request to the Mobile ID credential holder, receives the response, and sends the parsed model back to the calling app. It exposes the following APIs to the caller/client with the help of the concrete class IDVerifyClient.

SDK Core APIs

• version

Kotlin
1//Use IDVerifyTerminal.version to read Verify SDK version. e.g. 
2Log.d(TAG, "SDK Version=${IDVerifyTerminal.version}")

• getClient

Kotlin
1/**
2 * Create and return verify SDK V1 client using this function.
3 *
4 * @param configs configurations for verify sdk to initialize
5 * @param actContext; activity context from app.. We have allowed to pass as Context instead of
6 * Activity  explicitly because some features can even work with app context however for features
7 * like NFC, WifiAware it strictly require Activity context; therefore it is recommended to
8 * use Activity context when creating SDK client from your app.. It is also recommended that
9 * your app maintain a singleton object of SDK to avoid any concurrency issues.
10 *
11 * @return  `IDVerifyClient` object as IDVerifyTerminal
12 */
13fun getClient(configs: VSDKConfigs,actContext:Context): IDVerifyTerminal

• getClientV2

Kotlin
1/**
2 * Create and return verify SDK V2 client using this function..
3 *
4 * @param configs configurations for verify sdk to initialize
5 * @param actContext; activity context from app.. We have allowed to pass as Context instead of
6 * Activity  explicitly because some features can even work with app context however for features
7 * like NFC, WifiAware it strictly require Activity context; therefore it is recommended to
8 * use Activity context when creating SDK client from your app.. It is also recommended that
9 * your app maintain a singleton object of SDK to avoid any concurrency issues.
10 *
11 * @return `IDVerifyClientV2` object to access the v2 APIs..
12 */
13fun getClientV2(configs: VSDKConfigs, actContext:Context): IDVerifyClientV2

• loadCertificates

Kotlin
1/**
2 * Load certificates from a given location from device storage path
3 * @param vical file path from device storage if accessible directly.
4 * defaults to null if not supplied and fallback to load vical from assets/vical folder if available  
5 * @param callback async callback to return success or error
6 */
7
8fun loadCertificates(path: String?=null,callback: SuccessCallback<Int>?)

• initDeviceEngagement

Kotlin
1/**
2 * perform device engagement using QR code / NFC
3 * @param apiConfigs apiConfigs to configure QR code/NFC flow etc.
4 * Uses:
5val apiConfigs = ApiConfigs.Builder()
6.withData(scannedData) // for qr code device engagement
7//OR .withConfigs().useNfcHandover().buildConfigs() //for nfc device engagement
8.build()
9
10 * @param deviceEngagementCallback callback to return the DeviceEngagement model
11 * and/or other events during engagement.
12 * Usage:
13<p>
14sdkClintV2.initDeviceEngagement(apiConfigs,object:DeviceEngagementCallback(){
15//override the interface methods here
16})
17</p>
18 */
19fun initDeviceEngagement(apiConfigs: ApiConfigs?, callback: DeviceEngagementCallback<in ResponseItem?>)

• prepareConnection

Kotlin
1/**
2 * Initialize and setup connection components as per`ConnectionConfigs` configurations supplied.
3 * This API is available in `IDVerifyClientV2` only and must be called explicitly if SDK client
4 * is created using `IDVerifyTerminal.getClientV2`.
5 */
6
7fun prepareConnection(apiConfigs: ConnectionConfigs, callback: PrepareConnectionCallback?)

• sendRequest

Kotlin
1/**
2 * send request to Mobile ID based on the use case selected by user in Verify application
3 * @param apiConfigs: configurations and optional Mobile ID request params
4 * @param callback: callback to send progress and response data back to app
5 *
6 * 1. create Mobile ID request based on supplied Use Case or parameters/configs
7 * 2. onCreate communication channel (BLE/NFC/wifiAware ...) as per engagement data
8 * 3. send request to Mobile ID on communication channel
9 */
10fun sendRequest(apiConfigs: ApiConfigs? = ApiConfigs.Builder().build(),
11                callback: ICallback<in ResponseItem?, in ProgressItem>)

• cancelRequest

Kotlin
1/**
2 * cancel any transaction/running session with Mobile ID. overload to default cancellation
3 * return true if transaction is cancelled successfully
4 */
5fun cancelRequest(): Boolean

• terminateConnection

Kotlin
1/**
2 * Terminate the current connection to let user call prepareConnection again. this API is available
3 * in IDVerifyClientV2 only.
4 */
5fun terminateConnection(): Boolean

• terminateSession

Kotlin
1/**
2 * Terminate/Close the connection, wipe out session data and ready to process next transaction from
3 * user. This API is available in IDVerifyClientV2 only and equivalent to `cancelRequest` API of V1.
4 */
5fun terminateSession(): Boolean

• isRequestOngoing

Kotlin
1/**
2 * Check whether a transaction is already setup and in-progress state. Integrator can use this
3 * api to check a running transaction and cancel (if needed using `cancelRequest`) before
4 * starting a fresh transaction.
5 * Normally this api may not be used because once the transaction is complete verify SDK will return
6 * to initial state, however in case of some negative test cases it may be useful to check before
7 * starting a new transaction.
8 */
9fun isRequestOngoing(): Boolean

User Permissions 

When designing your app, you need to consider that your Android app must handle end-user permissions to protect the resources on the target mobile device. You have to verify that the end-user grant the following permissions to the app:

1. Camera permission (for QR code scanning using Camera)
2. Location permission (when BLE client mode and WiFiAware use cases)
3. Nearby devices permission required for WiFiAware use case (android 13 and above)

The end-user must grant access when using an Android version higher than 2.3 (Android 6.0 Marshmallow). The SDK will throw an exception or error, if the required permissions are not granted.

Sample Project 

Download the IDEMIA Verify Sample App – Android using below URL:

https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-release/com/idemia/android/idverify/4.1.0/Sample/

Create Your Own App 

Follow the steps mentioned below to Integrate the VerifySDK in your App:

Step 1: Add the Verify Library dependencies in your Android project 

To create your own app, you must add the VerifySDK libraries to your project. There are two ways of doing this:

Option A: Import VerifySDK from mi-artifactory

** Import VerifySDK from mi-artifactory**

1. Add the following configs in gradle.properties as shown in the snippet:

Groovy
1artifactory_remoteUrl=https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-release
2artifactory_username=<username>
3artifactory_password=<password>

2. Add the following dependency in your project/build.gradle as shown in the snippet:

Groovy
1buildscript {
2
3    repositories {
4        google()
5        jcenter()
6        maven {
7            url "https://plugins.gradle.org/m2/"
8        }
9        //required below maven block to sync verify SDK artifact from mi-artifactory
10        maven {
11            url "${artifactory_remoteUrl}"
12            credentials {
13                username = "${artifactory_username}"
14                password = "${artifactory_password}"
15            }
16        }
17      
18    }
19    ...
20  }
21  ...
22
23  allprojects {
24       repositories {
25          ...
26          maven { url 'https://github.com/c-rack/cbor-java' }
27          maven {
28              url "${artifactory_remoteUrl}"
29              credentials {
30                  username = "${artifactory_username}"
31                  password = "${artifactory_password}"
32              }
33          }
34
35      }
36      project.ext{
37          sdkVersionName='4.1.0'
38          sdkVersionCode=xxxx //use latest release version number for v4.1.0 from mi-artifactory
39
40      }
41
42    }

3. Add following dependency in app/build.gradle as shown in the snippet:

Groovy
1dependencies {
2    implementation("com.idemia.android:idverify:${project.ext.sdkVersionName}-${project.ext.sdkVersionCode}@aar") {
3        transitive = true
4    }
5  ... 
6}

4. If you have been using Option B and now moving to Option A, then you may need to delete the previous .aar file from your app/libs directory

**Option B: Import VerifySDK as .aar file **

Below steps 1-4 are only applicable if you intend to integrating verify using physical .aar file by copying it to your app/libs/ directory. (Note: this is not a recommended method due to additional steps involved and may cause runtime issues if there is any version mismatch for supporting dependencies)

1. Download the latest .aar file from artifactory path:

Language not specified
1https://mi-artifactory.otlabs.fr/artifactory/verify-sdk-release/com/idemia/android/idverify/4.1.0-xxxx/

2. Copy idverify-4.1.0-.aar into your project app/libs directory

3. Add below line in app/build.gradle

   Groovy
   1dependencies {
   2   implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
   3   ...
   4 }

4. Include the supporting dependencies in app/build.gradle in your Reader App to work, as shown in the snippet:

Groovy
1dependencies {
2    //additional dependencies required for idemia id.verify sdk
3     implementation "co.nstant.in:cbor:0.9"
4     implementation "org.bouncycastle:bcprov-jdk15to18:1.76"
5     implementation("org.bouncycastle:bcpkix-jdk15to18:1.76")
6     implementation "com.google.code.gson:gson:2.8.9"
7  }

Additional Steps to Compile and Build your Android project

Following steps are common for both Option A or Option B.

1. Add the required permissions to the project:

XML
1<!-- required camera for QR code scanning-->
2        <uses-permission android:name="android.permission.CAMERA"/>
3        <uses-feature android:name="android.hardware.camera.any" />
4        <!-- Request legacy Bluetooth permissions on older devices. -->
5        <!-- required for BLE data transfer-->
6        <uses-permission android:name="android.permission.BLUETOOTH"
7            android:maxSdkVersion="30"/>
8        <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
9            android:maxSdkVersion="30"/>
10        <!--BLE permissions for Android 12-->
11        <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
12    
13        <!-- Needed only if your app makes the device discoverable to Bluetooth
14             devices. -->
15        <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
16    
17        <!-- Needed only if your app communicates with already-paired Bluetooth
18             devices. -->
19        <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
20    
21        <!-- required for wifiaware and BLE scanning -->
22        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
23        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
24        <!--Required for online use cases -->
25        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
26        <uses-permission android:name="android.permission.INTERNET" />
27        <!-- required for wifiaware data transfer-->
28        <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
29        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
30        <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>
31        <uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" android:usesPermissionFlags="neverForLocation"/>
32        <!-- required for nfc data transfer-->
33        <uses-permission android:name="android.permission.NFC"/>

2. In order to allow your app to install in devices which do not support a certain feature, below lines can be added just below the permissions:

XML
1<!-- Do not install in devices which do not have Camera -->
2    <uses-feature android:name="android.hardware.camera" android:required="true"/>
3    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
4    <!-- allow app to install in devices which do not have NFC support so that 
5    they can still use other features e.g QR code and WifiAware use-cases -->
6    <uses-feature android:name="android.hardware.nfc" android:required="false"/>
7    <!-- allow app to install in devices which do not have wifiAware support so that 
8        they can still use other features e.g QR code and NFC use-cases -->
9    <uses-feature android:name="android.hardware.wifi.aware" android:required="false"/>

Note: It is not recommended to have all three configs with required="false". Normally if all three use cases (QR Code, NFC handover/transfer, WifiAware Transfer) are supported in your app then you may want to let users install your app regardless of their device supports or not NFC and/or WifiAware; for that you can add required="false" for WifiAware and NFC and required="true" for Camera.

3. Gradle Sync and build!

Step 2: Integrate QR Code + BLE/NFC/WiFi Use case 

1. Initialize the VerifySDK configurations by calling VSDKConfigs.Builder().build() in your activity/fragment.

2. Create the VerifySDK client object to call the SDK APIs as shown in the snippet:

Kotlin
1val config = VSDKConfigs.Builder().build()
2   mSdkClient = IDVerifyTerminal.getClientV2(config,actContext)
3// OR mSdkClient = IDVerifyTerminal.getClient(config,actContext) //call `getClient` to use legacy client

Notes:

• IDVerifyTerminal.getClientV2() is recommended for new integrators for better control over SDK APIs.
• Use DebugCallback with enableDebug to get the logs via a callback and save them in the file, as shown in the snippet:

Kotlin
1val config = VSDKConfigs.Builder(this)
2  .enableDebug(LogLevel.DEBUG,debugCallback = object:DebugCallback{
3    override fun didReceiveLogs(logs: DLog) {
4      //save or print logs here
5    }
6  })
7  ...
8  .build()

Note: The above is useful in scenarios when logcat strips some logs because they are too big, for example, if response HEX with end-user image becomes too big to print in logcat.

• Enabling debug verbose logs in the production app may adversely affect the transaction speed and overall performance of the Verify SDK for Android.
• It is recommended that integrator should use the LogLevel properties carefully to configure limited logs in production flavour.
• Default LogLevel will be NONE if enableDebug is not configured with at least one LogLevel
• If you want full debug logs except PIIs then use DEBUG_NO_PII
• DEBUG and VERBOSE may include PIIs hence should be avoided in production release
• Supported LogLevel are:

Language not specified
1TRANSACTION_TIME : Only transaction time event logs shall be printed on console and returned to`debugCallback.didReceiveLogs()`
2                     These logs shall be persisted in runtime memory during the transaction and shall be dumped
3                     to console in a time sorted order (FIFO) once the transaction concludes. 
4  
5  TROUBLESHOOTING : Only minimal troubleshooting logs (e.g. exceptions and errors) shall be printed on console and 
6                    returned to `debugCallback.didReceiveLogs()`.
7                    These logs would be helpful to troubleshoot the failures cases during transactions.
8  
9  DEBUG : All debug logs include PIIs are returned or printed in console  
10    
11  DEBUG_NO_PII : All except PII logs shall be returned to `debugCallback.didReceiveLogs()` LogLevel.DEBUG_NO_PII has highest priority 
12                 if multiple logLevel values are configured via `enableDebug` vararg param. (excluding LogLevel.NONE- in case of NONE is found, 
13                 all other configs shall be ignored and all logs shall be disabled)
14  
15  VERBOSE : Allow all logs (transaction_time, troubleshooting, and Debug) including PIIs  
16  
17  NONE : No logs shall be printed. LogLevel.NONE has highest priority if multiple  
18         logLevel values are configured via `enableDebug` vararg param

2.1. Call loadCertificates() api to load IACA certificates from given path. This step is necessary for a successful transaction since Verify SDK will validate the mDL response against the certificates from supplied path.

Kotlin
1mSdkClient?.loadCertificates(path=<directory_path/vical>,object : SuccessCallback<Int> {
2        override fun onSuccess(response: Int?) {
3            Log.d("HomeFragment","*Certificate Loading, loaded cert count:$response")
4          
5        }
6        override fun onError(error: IError?) {
7            Log.d("HomeFragment","*Certificate Loading error: ${error?.errorCode}")        
8        }
9    })

How to create directory structure for hosting vical files for your Reader app?

• Copy download vical files at some app private location which should be accecisble at runtime
• Create new directory vical/ inside assets and copy iaca files for each environment as per below structure.

• assets/vical
  • Dev
    • iaca.vical
    • iaca.vical.pem
  • UAT
    • iaca.vical
    • iaca.vical.pem
  • PROD
    • iaca.vical
    • iaca.vical.pem

Note:

• The vical file and corresponding IACA file to validate vical coseSign1 should be named exactly as in above sample
• For example, if vical file name is "myiaca.vical" then IACA should be named "myiaca.vical.pem"

How To configure vical from app/assets directory?

• Create 'assets/vical' folder inside app/main or app/flavorName/
• Copy iaca and corresponding IACA cert per environment similar to structure defined above.
• Set value for path to null while calling loadCertificates api and verifySDK shall fallback to use assets/vical path

Kotlin
1.loadCertificates(path=null,callback=object :SuccessCallback<Int>{
2      override fun onSuccess(response: Int?) {
3       //Log.d("HomeFragment","*Certificate Loading, loaded cert count:$response")
4      }
5
6      override fun onError(error: IError?) {
7        //Log.d("HomeFragment","*Certificate Loading error: ${error?.errorCode}")
8      }
9
10    })

Note:

• loadCertificates() api should be called only once on application launch when SDK object is created first; no need to be called for each transaction.

3. Call the desired SDK API by supplying the necessary apiConfigs/request parameters and using callback to receive the results.

Kotlin
1* `mSdkClient.initDeviceEngagement(apiConfigs,callback)`
2* `mSdkClient.prepareConnection(connectionConfigs,callback)`
3* `mSdkClient.sendRequest(apiConfigs,callback)`
4* `mSdkClient.terminateConnection()`
5* `mSdkClient.terminateSession()`
6*

4. To scan the QR code follow the below steps to communicate with the Mobile ID App and display the results on the Verify App screen:

• Scan the QR code using Zxing or any other library and then call initDeviceEngagement API as shown in the snippet:

Kotlin
1fun onQRCodeScanned(scannedData: String?) {
2        doHandleScannedData(scannedData)
3    }

• Create the response callback for parsing engagement QR code data as shown in the snippet:

Kotlin
1open fun doHandleScannedData(scannedData: String?) {
2        if (!scannedData.isNullOrEmpty()) {
3            val nfcConfigsBuilder=NfcConfigs.Builder()
4            val apiConfigs = ApiConfigs.Builder()
5                .withData(scannedData)
6//                //OR useNfcHandover() as below commented section//for nfc device engagement
7//                .withConfigs().apply {
8//                    useNfcHandover()
9//                   /* use additional configs for nfcHandover if needed
10//                    * verify sdk will use default and best ppossible configs if no configs are 
11//                    * set using `setNfcConfigs` 
12//                    */ 
13//                   
14//                    nfcConfigsBuilder.enableReaderEngagement() //use this cofig to enable readerEngagement bytes ON for Nfc negotiated handover
15//                    nfcConfigsBuilder.enableWiFiACRecord(true) //use this to indicate support for WiFiAware
16//                    nfcConfigsBuilder.leRole(LeRole.MDOC_CENTRAL_ONLY) // use this to indicate preferred LE Role
17//                    //... // additional configs to fine tune based on underlying hardware/device/OS if needed 
18//                    setNfcConfigs(nfcConfigsBuilder.build())
19//                 }
20//                .buildConfigs()
21                .build()
22          mSdkClient?.initDeviceEngagement(apiConfigs, mDEParserCallback)
23        } else {
24            // QR scan failed! try again
25        }
26    }
27  /** Response callback for parse engagement QR code data */
28    private val mDEParserCallback = object : ResponseCallback<DeviceEngagementModel?> {
29        override fun onSuccess(deviceEngegmentModel: DeviceEngagementModel?) {
30             // deviceEngegmentModel received. perform next step
31             doPrepareConnection(deviceEngagementModel)
32             // OR for legacy client
33             // doStartDataTransfer(deviceEngagementModel)
34        }
35        override fun onError(error: IError?) {
36            handleError(error)
37        }
38    }

5. For V2 client call prepareConnection api before calling sendRequest else skip to step 5.1

Kotlin
1private fun doPrepareConnection(deModel: DeviceEngagementModel?) {
2   val connectionConfigs = ConnectionConfigs.Builder()
3         .withConfigs().apply {
4           setResponseTimeout(10000) //sdk will disconnect and return with error code 303 if transaction doesn't complete in this time
5           setConnectTimeout(10000) //sdk will return with error code 206 is connection not established withing this time         
6           //enableL2Cap() //to enable BLE l2cap if available and supported 
7           
8         }.buildConf()
9         .build()
10    mSdkClient?.prepareConnection(connectionConfigs,
11          object : PrepareConnectionCallback {
12              override fun onSuccess(response: ConnectionInfo?) {
13                   when (response?.connectionState) {
14                        ConnectionState.CONNECTED -> {
15                            doStartDataTransfer(deModel)
16                        }
17                        else -> {
18                            Log.d("MainActivity","prepareConnection: connectionState=${response?.connectionState}")
19                        }
20                      }
21                   }
22 
23              override fun onError(error: IError?) {
24                    handleError(error)
25              }
26            })
27    }

5.1. Send the request to the Mobile ID App to get the credential details. The sendRequest() method will return the response from the user's Mobile ID App. If you've received it successfully, then you can display all the attributes of the Mobile ID App response in your own result activity, as shown in the snippet:

Kotlin
1private fun doStartDataTransfer(deModel: DeviceEngagementModel?) {
2      
3       val namespaceParamMap = getRequestedParamsMap() // make map of namespace to List<MIDRequestParam>
4
5       val apiConfigs = ApiConfigs.MIDRequestBuilder()
6                 .version("1.0")
7                 .withConfigs().apply {
8                    //verify sdk will disconnect and return with error code 303 if transaction doesn't complete in this time
9                    setResponseTimeout(20000)
10                    //verify sdk will return with error code 206 is connection not established withing this time 
11                    setConnectTimeout(10000)
12                    clearBLECache() // enable BLE cache to clear for every transaction to avoid connection issues
13                    //for wifiaware data transfer; since v2.4.0
14                    setNANConfigs(NANConfigs.Builder().apply {
15                        setSubscribeType(DEFAULT_NAN_SUBSCRIBE_TYPE)
16                        setTtlSec(15)
17                     }.build())
18                 }.buildConf()          
19              //add docType
20                 .addDocType(DOCTYPE_18013_5).apply {
21                          // pass all request params as Map<namespace->List<MIDRequestParam> 
22                           addParams(namespaceParamMap)
23                          //OR use namespace -> param overload to add all params one by one
24                           addParam("org.aamva.us", MIDRequestParam(REAL_ID))
25                           addParam("org.aamva.us", MIDRequestParam("<AttributeName>"))
26                           //OR use another overload to . duplicate params shall be removed if found
27                           addParams(DEFAULT_NAMESPACE_18013_5_1, namespaceParamMap.get(DEFAULT_NAMESPACE_18013_5_1))
28                           addParams(NAMESPACE_ORG_ISO_AAMVA, namespaceParamList.get(NAMESPACE_ORG_ISO_AAMVA))
29                           //OR this way
30                           addParams(
31                               "my.custom.namespace2", listOf(
32                                   MIDRequestParam("custom_param_nm21"),
33                                   MIDRequestParam("custom_param_nm22"),
34                                   MIDRequestParam("custom_param_nm23"),
35                                   MIDRequestParam("custom_param_nm21") //duplicate
36                               )
37                           )
38                           //OR use 3rd overload to pass params one by one
39                           .addParam("my.custom.namespace", MIDRequestParam("custom_param1"))
40                           // add requestInfo as map
41                           .addRequestInfo(
42                               infoMap = hashMapOf(
43                                   "reqKey1" to "reqVal1",
44                                   "reqKey2" to "reqVal2",
45                                   "reqKey3" to false,
46                                   "reqKey4" to 3334
47                               )
48                           )
49                           //or use other overload to add one by one
50                           .addRequestInfo("reqinfo1", "value1")
51                           .addRequestInfo("reqinfo2", "value2")
52                           .addRequestInfo("reqinfoLong", 180L)
53                           .addRequestInfo("reqinfoBool", true)
54                           .addRequestInfo("reqinfoBytArr", "sdkghdkgs".toByteArray())
55                           .addRequestInfo("reqinfoDouble", 3.7)
56                           .addRequestInfo("reqinfoFloat", 3.7F)
57                           // add as dataItem 
58                           .addRequestInfo(
59                               "reqinfoDataItem",
60                               CborBuilder().addArray().add(1).add("item2").add("item3").end().build()
61                                   .first()
62                           )
63
64                   }.buildDoc()
65             //add another docType
66                   .addDocType("my.cusom.docType.custom").apply {
67                       addParams(
68                           "my.custom.namespace2", listOf(
69                               MIDRequestParam("custom_param_nm21", true),
70                               MIDRequestParam("custom_param_nm22"),
71                               MIDRequestParam("custom_param_nm23"),
72                               MIDRequestParam("custom_param_nm21", true) //duplicate
73                           )
74                       )
75                           // add requestInfo as map
76                           .addRequestInfo(
77                               infoMap = hashMapOf(
78                                   "reqKey1" to "reqVal1",
79                                   "reqKey2" to "reqVal2",
80                                   "reqKey3" to false,
81                                   "reqKey4" to 3334
82                               )
83                           )
84                   }.buildDoc()
85              //(optional) setReaderAuthentication callback if needed
86                   .setReaderAuthCallback(readerAuthSigner,ReaderAuthAlgorithm.ALGO_SHA256WITHECDSA)
87             //(optional) Use setMultiRequestCallback to enable multiple requests-response exchanges within same session.  
88                    .setMultiRequestCallback(multiResCallback)
89                   .build()        
90
91        if (deModel?.isMDLAsPeripheral()) {
92             askLocationPermission() /* android.permission.ACCESS_COARSE_LOCATION to be added in AndroidManifest.
93             you may invoke all permission dialogs beforehand to avoid this check here*/
94             //mSdkClient?.sendRequest(apiConfigs, callback = mRequestCallback) //get permission and then call sendRequest
95         } else {
96             mSdkClient?.sendRequest(apiConfigs, callback = mRequestCallback)
97         }
98
99    }
100
101    fun getRequestedParamsMap(): java.util.HashMap<String, List<MIDRequestParam>> {
102      val paramMap= hashMapOf<String, List<MIDRequestParam>>()
103      paramMap.put(NAMESPACE_18013_5,listOf(
104        MIDRequestParam(FAMILY_NAME),
105        MIDRequestParam(GIVEN_NAME),
106        MIDRequestParam(BIRTHDATE),
107        MIDRequestParam(ISSUE_DATE),
108        MIDRequestParam(EXPIRY_DATE),
109        MIDRequestParam(ISSUING_COUNTRY),
110        MIDRequestParam(ISSUING_AUTHORITY),
111        MIDRequestParam(DOCUMENT_NUMBER),
112        MIDRequestParam(PORTRAIT),
113        MIDRequestParam(MGMT_LAST_UPDATE)))
114    
115        paramMap.put(NAMESPACE_ORG_ISO_AAMVA,listOf(MIDRequestParam(DHS_COMPLIANCE),
116        MIDRequestParam(DOMESTIC_DRIVING_PRIVILEGES)))
117    
118      return paramMap
119    }

**Sample code for Reader Authentication callback implementation **

Language not specified
1Reader Authentication is an optional `setReaderAuthCallback` which can be used by the integrator to implement Reader Auth for their Verifier app.
2Below sample code spec illustrates how Reader Authentication callback can be implemented:
3    
4a. Add/Enable the callback in the RequestBuilder
5        
6```kotlin
7    val apiConfigs = ApiConfigs.MIDRequestBuilder()
8    .version("1.0")
9    .addDocType("my.cusom.docType.custom").apply {
10    addParams( … )
11    }.buildDoc()
12    …
13    .setReaderAuthCallback(readerAuthSignerCallback,readerAuthAlgorithm)
14    .build()
15
16```
17b. Implement the readerAuthSignerCallback at app side. ReaderAuthSignerCallback provides the interface to perform signing of readerAuthentication structure. Verify SDK will call doSignRequest with the readerAuthentication structure to sign by the integrator
18with the reader private key. They will sign the bytes using certificate private key and return ReaderAuthSign data model with generated signature, algorithm used to sign and a x509 certificate with the corresponding public key of the private key that the readerAuthenticationBytes structure is signed.  [Refer 9.1.4 mdoc reader authentication ISO/IEC FDIS 18013-5:2021(E) page 54]
19 
20```kotlin
21    val readerAuthAlgorithm = ReaderAuthAlgorithm.ALGO_SHA256WITHECDSA
22    val readerAuthSigner=object : ReaderAuthSignerCallback {
23    override fun doSignItemRequest(readerAuthenticationStructure: ByteArray?,docType:String): ReaderAuthSign? {
24        // Verify SDK provides some utility functions in VIDUtils which can be used or write your own logic to generate the signature
25        
26        val signatureBytes = VIDUtils.generateReaderAuthSignature(readerAuthAlgorithm, readerAuthPrivateKey, readerAuthenticationStructure)
27        val certItem=CborBuilder().add(x509Certificate).build().firstOrNull()
28        return ReaderAuthSign(signature = signatureBytes,x509Certificate = certItem)
29
30    }
31```
32c. List the required resources e.g cert, keys. at Integrator side.
331. Reader private key to sign the Reader Auth structure. the resulting signature and algorithm used to sign shall be included within the mdoc request to be sent to mdoc.
342. Reade Signer certificate containing the corresponding public key of the private key used in #a; which shall be sent to mdoc within the mdoc request. Integrator would submit a CSR to a valid CA to get a signer certificate.
353. Reader CA certificate from CA which shall be shared by Reader to mDoc Holder which they can uses for signer certificate trust path validation

** Sample code for multiReqCallback **

Kotlin
1val multiResCallback = object : MultiResponseCallback<ResponseItem?> {
2          override fun onMultiResponse(
3              response: ResponseItem?,
4              requestCallback: MultiRequestCallback
5          ): Boolean {
6            /*  
7             * 1. process the `response` and analyse or display if needed
8             * 2. check if new request is required to send: y/n
9             *  - if y. create a new request using ApiConfigs.MIDRequestBuilder() and send back using
10             *  `requestCallback.onNextRequest()`
11             *  - if n, return false and wait for onSuccess or onError with final response
12             */
13             handleMultiResponse(response,requestCallback)
14             return true
15          }
16  
17      }

6. Obtain the response callback for parsing the engagement QR code data scan as shown in the snippet:

Kotlin
1/**
2     * Request callback for sendRequest SDK api to receive and display response data from Mobile ID
3     */
4    val mRequestCallback = object : RequestCallback<ResponseItem?, ProgressItem> {
5
6        override fun onSuccess(response: ResponseItem?) {
7            Log.e(TAG, "Mobile ID response:$response")
8            displayResponse(response as DLDataModel)
9        }
10
11        override fun onError(error: IError?) {
12            handleError(error = error as VSDKError)
13        }
14
15        override fun onProgress(progress: ProgressItem) {
16            Log.e(TAG,  progress.toString())
17        }
18
19    }

7. You can cancel/terminate a transaction any time if an error occurs in the app, or if the user cancels the transaction by tapping the Back button. Cancel a transaction by calling the cancelRequest() method as shown in the snippet:

Kotlin
1mSdkClient?.cancelRequest()
2    //OR V2 client call 
3    mSdkClient?.terminateSession()

7.1. To close a running connection and start another connection using prepareConnection use terminateConnection API

Kotlin
1// Available only in V2 client 
2    mSdkClient?.terminateSession()

Integrate NFC Handover + BLE/NFC/WiFi Use case 

1. Initialise NFC device Engagement

Kotlin
1val apiConfigs = ApiConfigs.Builder()
2      .withConfigs().apply {
3        useNfcHandover()
4        //setBLEMacAddress(bleMacAddress) for mac address connect use this option
5        setNfcConfigs(NfcConfigs.Builder().setPresenceCheckDelay(1000)
6          .addNfcDetectCallback(object:NfcConfigs.NfcDetectCallback{
7            override fun onTagDiscovered(tag: Tag?): Boolean {
8              // indicates new nfc tag is discovered. return true to process the tag
9              // you may add / display some progress indicator for user
10              // once the handover is done, feedback will be received in mDEParserCallback 
11              return true
12            }
13          })
14          .build())
15        //...
16      }.buildConfigs()
17      .build()
18    mSdkClient?.initDeviceEngagement(apiConfigs, mDEParserCallback)

2. After device engagement is complete, follow the same steps as described above

3. To configure NFC or Wifi as data transfer method add configs in ConnectionConfigs Builder.

Kotlin
1val connectionConfigs = ConnectionConfigs.Builder()
2         .withConfigs().apply {
3           setResponseTimeout(10000) //sdk will disconnect and return with error code 303 if transaction doesn't complete in 10 seconds
4           setConnectTimeout(10000) //sdk will return with error code 206 is connection not established withing 10 seconds         
5           useNfc() // or useWifi() // or connectAsmDocPeripheral() or connectAsmDocCentral
6         }.buildConf()
7         .build()

Note:

• By default BLE mDoc Central mode is the preferred mode if multiple modes are available from mDL holder
• From Reader side verify SDK allows the integrator to configure the preferred connection mode, however if configured mode is not available, VerifySDK will try to connect using whichever mode is available with mDL holder

Request Parameters 

The following table provides a list of attributes which can be configured for sendRequest API.

Expected Results 

QR code

Below are expected response from the sendRequest API with the expected data type.

Deprecations and Deletions 

• Deprecated APIs/Methods/Properties from previous versions are removed

ProGuard Rules 

The following code snippets should be added in the app ProGuard Rules file.

• SDK obfuscation rules:

Language not specified
1-keep public class idemia.verify.sdk.** {
2    public protected *;
3}
4-keep class org.bouncycastle.**{*;}

Release Notes 

• Refer CHANGELOG.md for full release notes history.

IACA certificate file format support 

• Supports following formats for IACA certificates - (.pem, .crt, .der).

Elliptic Curve Support 

ISO-18013-5 Specification Support 

Additions & Updates 

• Session auto close when status code 20 received in response
• Fix reader flags to support Type4: NfcA/NfcB tags
• Bug fixes and Improvements

Error Codes 

Test Samples 

QR + BLE Sample 

The following screen shows a scan of the QR code in the Mobile ID App.

Note: This screenshot is only for device engagement QR code testing. The full QR + BLE scenario will only work with a real device with the IDEMIA Mobile ID App installed.