Native Integration Guide

This document provides a step by step guide on how to install, integrate and initialize the BlockID SDK into any Android applications.

Prerequisites

Integrating the BlockID SDK into an Android application requires several general and platform-specific dependencies. Developers should review the following requirements:

General

• A basic understanding of Android application development
• At least one compatible Android mobile device

Technical

• Android API Level: 26 (Android 8.0 Oreo) or higher
• Android Studio: Ladybug Feature Drop (version 2024.2.2) or higher
• Android Gradle Plugin: Version 8.8.0 or higher
• Device Support: All devices running Android 8.0 (API 26) or higher

tip

The BlockID SDK currently supports Android OS versions up to 15.x.

Integration Overview

This section explains the step by step guide on how to setup and integrate the BlockID SDK in an Android application.

tip

The examples below demonstrate how to integrate the BlockID SDK into a new Android project. The same steps apply when integrating the SDK into an existing application.

note

The screenshots in this section were taken using Android Studio Ladybug on a Windows machine.

Step 1: Create a New Application

1. Open Android Studio.

2. In the Welcome Screen, click New Project.

   

3. In the New Project screen, select the required project template and press Next. In this example, an Empty Activity project template is selected.

   

4. In the New Project window that is displayed, specify the following details. You can use the sample screenshot below to specify the field details.

   Field	Description
   Name	Specify an application name. Example: BlockID Demo
   Package name	Specify a package to which the application belongs.
   Save location	Specify the location where you want to save the project.
   language	Specify the project language. This is an optional field.
   Minimum SDK	Specify the minimum supported SDK version. Use API 26 (Android 8.0 "Oreo"), as the BlockID SDK supports API 26 and above.

   

5. Click Finish and wait until the project is being configured completely.

   

Step 2: Add BlockID SDK

Once the project is created, the next step is to integrate the BlockID SDK. The latest version of the BlockID SDK can be added using a Gradle dependency.

1. Open your Android Studio project and navigate to the app-level build.gradle file. Add the following line to the dependencies block.

// Add BlockIDSDK dependency
implementation 'com.onekosmos.blockid.sdk:blockidsdk:1.20.50.687538CD'

2. Open your settings.gradle file and add the following block.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://nexus-1k-nonprod.1kosmos.net/repository/maven-releases/'
            credentials {
                username = "developer"
                password = "q5k#06ZcjSo#"
            }
        }
        maven { url "https://jitpack.io" }
        maven {
            url 'http://www.baka.sk/maven2'
            allowInsecureProtocol = true
        }
    }
}

Step 3: Java Compatibility

caution

The BlockID SDK is not binary compatible with applications targeting Java 11

To use the SDK you must upgrade your applications to target Java 17.

Below is a snippet for reference:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

Step 4: Update Android Manifest

The BlockID SDK provides scanning features for various identity documents, which require access to the device's camera. Since the SDK supports Android API level 26 and above, your application must be configured to request runtime permissions for the camera (and any other permissions required by your project).

Follow the steps below to enable camera permission.

4.1 Update Application Tag

The BlockID SDK ensures that no data is shared outside its own secure enclave. To enforce this, application developers must add the following attribute to the <application> tag in the app's AndroidManifest.xml file.

tools:replace="android:allowBackup,android:label,android:theme"

4.2 Add Permissions in Android Manifest

Add the following permissions to the application's AndroidManifest.xml file.

// Add camera permission
<uses-permission android:name="android.permission.CAMERA" />

// Add NFC permission for RFID Scanning
<uses-permission android:name="android.permission.NFC" />

// other permissions ...
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

4.3 Request Camera Permission

Request camera permissions within your application code:

ActivityCompat.requestPermissions(this, new String[] { Manifest.permission.{your_permission}}, PERMISSION_REQUEST_CODE );

Step 5: Add Gradle Dependencies

Since the BlockID SDK depends on other libraries, you must add the following dependencies to your project.

5.1 Application Level Dependencies

The following section lists all the dependencies—along with their respective purposes—that must be added to the application-level build.gradle file:

• Add the following configuration to the build.gradle file.

  // Secure shared preference
  implementation 'androidx.security:security-crypto:1.1.0-alpha06'
  
  // Fingerprint and biometric
  implementation 'androidx.biometric:biometric:1.1.0'
  
  // Network call
  implementation 'com.github.amitshekhariitbhu.Fast-Android-Networking:android-networking:1.0.4'
  
  // LiveID
  implementation 'com.google.guava:guava:32.0.1-jre'
  

• Add the following configuration to resolve bouncycastle dependency conflicts:

  android {
  ...
  }
  
  configurations.configureEach {
      resolutionStrategy.eachDependency { DependencyResolveDetails details ->
          if (details.requested.group == 'org.bouncycastle') {
              details.useTarget 'org.bouncycastle:bcprov-jdk15to18:1.70'
          }
      }
  }

• Add the following block to resolve META-INF file conflicts:

  android {
  ...
  
  packagingOptions {
     exclude 'META-INF/rxjava.properties'
     exclude 'lib/x86_64/darwin/libscrypt.dylib'
     exclude 'lib/x86_64/freebsd/libscrypt.so'
     exclude 'lib/x86_64/linux/libscrypt.so'
     exclude 'META-INF/INDEX.LIST'
     exclude 'META-INF/LICENSE.md'
     exclude 'META-INF/DEPENDENCIES'
     exclude 'META-INF/NOTICE.md'
     exclude 'AndroidManifest.xml'
  }
  }

Step 6: Enable Proguard

Add the following rules to the proguard-rules.pro file if you want to obfuscate your application code.

-keep class com.onekosmos.blockid.sdk.** { *; }

-keep public class org.** { *; }

-keep class net.sqlcipher.** { *; }

-keep class net.sqlcipher.database.** { *; }

Step 7: Gradle Properties

Add the following line to the gradle.properties file:

android.enableJetifier=true

Step 8: Application Deployment

Deploy your Android application as usual after integrating the BlockID SDK, as it does not require any additional deployment steps.

Initial SDK Setup

The BlockID SDK has now been added to your application. To access its features, you need to provide the License Key, Wallet, and Tenant details.

note

To access the SDK, reach out to your 1Kosmos representative.

caution

The information must be set in the following sequence only and MUST NOT be changed.

Step 1: Initialize SDK

The BlockID SDK must be initialized to ensure all its key components are properly set up and functioning. Other SDK functions should only be called after the initialization process is complete.

Add the following line to your application code to initialize the BlockID SDK:

BlockIDSDK.initialize(<the_context>);

Step 2: Set License Key

tip

The license key must be set each time the application is launched.

Whenever the license key is set, the SDK internally checks whether:

• the given license key is valid
• the application is authorized to use the provided license key

Add the following code to your application to set the license key:

BlockIDSDK.getInstance().setLicenseKey("<your_license_key>")

Step 3: Initialize Wallet

Before registering a tenant, a temporary application wallet must be created. An application can only have one wallet, so the temporary wallet must be created ONLY once.

Add the following code to initialize the temporary wallet:

BlockIDSDK.getInstance().initiateWallet();

Step 4: Register Tenant

4.1 About Tenant

The tenant represents the value or object on which API calls can be registered.

There are two types of tenants:

• Root Tenant: Stores details about enrolled user biometric information and digital assets.
• Client Tenant: Stores the user's enrolled persona.

A root tenant can also store a user's persona, but a client tenant cannot be used to store biometric data or digital assets.

The application is expected to register a tenant only once. If an existing tenant is set, the application will load it after validating the license key.

The SDK will allow a tenant to be registered only after the license key is set.

The tenant object is represented using the BIDTenant class and can be created using the following code:

BIDTenant bidTenant = new BIDTenant("your_tenant_tag", "your_community", "your_dns_url");

4.2 Register Tenant

After creating the BIDTenant object, the tenant registration API must be called:

BlockIDSDK.getInstance().registerTenant(bidTenant, BIDTenantRegistryCallback);

The tenant details are used during document enrollment and when retrieving a public key. When this function is executed, an Ethereum wallet is created, and a Distributed Identifier (DID) along with 12 recovery mnemonic phrases will be made available to the user.

Step 5: Commit Wallet

Upon successful tenant registration, the commit wallet method must be called. The method must be invoked only once:

BlockIDSDK.getInstance().commitApplicationWallet();

The commit wallet method is the final step in setting up the BlockID SDK within an Android application.

SDK Security

As the attack surface of an API is broader than that of a standalone application, the BlockID SDK implements a locking mechanism to prevent unauthorized access.

For security purposes, the following points must be implemented in the application:

• The SDK should be locked when the application moves to the background.
• The SDK should be locked when the application displays the login screen to users.
• The SDK’s lock status should be checked before calling any enrollment APIs.

tip

For more information on the methods used in this section, see API Reference Guide for Android.