> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/mobile-sdk/native/android/integration-guide.md). # Integration Guide This document provides a step-by-step guide to installing, integrating, and initializing the BlockID SDK in any Android application. **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: 28 / Android OS 9 or higher * Android Studio Panda 2 | 2025.3.2 or higher * Android Gradle Plugin: Version 9.0.0 or higher * Device Support: All devices running Android 9.0 or higher {% hint style="info" %} **Note:** The BlockID SDK currently supports Android OS versions up to 16.x. {% endhint %} ### Integration Overview This section explains the step-by-step guide on how to set up and integrate the BlockID SDK in an Android application. 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. {% hint style="info" %} **Note:** The screenshots in this section were taken using Android Studio Panda 2 on Mac. {% endhint %} #### 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, select the Empty Activity project template. 4. In the **New Project** window, specify the following details. Use the sample screenshot below to fill in the fields. | 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 28 (Android 9.0 "Oreo"), as the BlockID SDK supports API 28 onwards. | 5. Click **Finish** and wait until the project is configured completely. #### Step 2: Add BlockID SDK After you create the project, integrate the BlockID SDK. Add the latest version of the BlockID SDK 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.
```` ```java // Add BlockIDSDK dependency implementation 'com.onekosmos.blockid.sdk:blockidsdk:1.30.60.6A980573' ```` ``` ``` 2. Open your `settings.gradle` file and add the following block. {% hint style="info" %} **Note:** * Starting with Release v1.30.50, the SDK artifact repository has migrated from to . * Update your settings.gradle accordingly. {% endhint %} ```java dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven { url 'https://artifactory.1kosmos.net/artifactory/maven-releases-local' credentials { username = 'developer' password = 'xK9#mPw2$vLq7nBz!' } } maven { url "https://jitpack.io" } } } ``` #### Step 3: Java Compatibility The SDK is not binary compatible with applications that target Java 11. In order to use this and future releases, you must upgrade applications to target Java 17. Refer to the code snippet below. Below is a snippet for reference: ```java android { compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } ``` #### Step 4: Update Android Manifest BlockID SDK provides scanning features for various documents, so the application must enable and request camera permission. Because BlockID SDK support starts with Android API 28, ensure the application requests runtime permissions for the camera (and others, as per project requirements). Complete the steps below to enable camera permission. Follow the steps below to enable camera permission. **4.1 Update Application Tag** The BlockID SDK ensures that no data leaves its secure enclave. To enforce this, application developers must add the following attribute to the `` tag in the app's AndroidManifest.xml file. ```xml 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 // Add NFC permission for RFID Scanning // other permissions ... ``` **4.3 Request Camera Permission** Request camera permissions within your application code: ```java 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' ``` * Add the following configuration to resolve `bouncycastle` dependency conflicts: ``` android { ... } configurations.configureEach { resolutionStrategy.eachDependency { DependencyResolveDetails details -> if (details.requested.group == 'org.bouncycastle') { details.useVersion '1.84' } if (details.requested.group == 'com.fasterxml.jackson.core') { details.useVersion '2.19.2' } } } ``` * 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' exclude 'META-INF/FastDoubleParser-LICENSE' exclude 'META-INF/FastDoubleParser-NOTICE' exclude 'META-INF/DISCLAIMER' exclude 'META-INF/io.netty.versions.properties' } } ``` #### 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.** { *; }` #### Step 7: Gradle Properties Add the following line to the `gradle.properties` file: ```java android.enableJetifier=true ``` #### Step 8: Application Deployment Deploy your Android application as usual after integrating the BlockID SDK, as it requires no additional deployment steps. ### **Initial SDK Setup** You have now added the BlockID SDK to your application. To access its features, you need to provide the License Key, Wallet, and Tenant details. {% hint style="info" %} Note: To access the SDK, contact your 1Kosmos representative. {% endhint %} {% hint style="warning" %} Set the information in the following sequence only, and do NOT change it. {% endhint %} #### Step 1: Initialize SDK Initialize the Android BlockID SDK to ensure all 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: ```java BlockIDSDK.initialize(); ``` #### Step 2: Set License Key Set the license key each time the application launches. 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: ```java BlockIDSDK.getInstance().setLicenseKey("") ``` #### Step 3: Initialize Wallet Before registering a tenant, a temporary application wallet must be created. An application can have only one wallet, so create the temporary wallet only **once**. Add the following code to initialize the temporary wallet: ```java BlockIDSDK.getInstance().initiateWallet(); ``` #### Step 4: Register Tenant Tenant can be represented as a value or an object on which API calls can be registered. The application must register a tenant only once. If an existing tenant is set, the application will load it after validating the license key. SDK will only allow tenant registration IFF the license key is set. The tenant object is represented using the BIDTenant class and can be created using the code below. ```java BIDTenant bidTenant = new BIDTenant("your_tenant_tag", "your_community", "your_dns_url"); ``` After BIDTenant object is created, tenant registration API must be called. Add below code to register tenant with BlockID SDK. ```java BlockIDSDK.getInstance().registerTenant(bidTenant, BIDTenantRegistryCallback); ``` The registered tenant details will be used when APIs are executed to enroll documents or retrieve a public key. When this function executes, the Ethereum wallet is created, and a Distributed Identifier and 12 Mnemonic phrases (recovery phrases) become available to the user. #### Step 5: Commit Wallet After successful tenant registration, call the commit wallet method. The method must be invoked **only once**: ```java 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: * Lock the SDK * When the application moves to the background. * When the application displays the login screen. * The SDK’s lock status should be checked before calling any enrollment APIs. {% hint style="info" %} For more information on the methods used in this section, see the [API Reference Guide](/mobile-sdk/native/android/api-reference.md) for Android. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.1kosmos.com/mobile-sdk/native/android/integration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.