Welcome to the Digiboost Android SDK Sample App! This guide will walk you through a simple 3-step journey to integrate the Digiboost Android SDK V2 into your application.
The Digiboost SDK enables secure document verification and digital identity services in your Android app. Follow this guide to get up and running in minutes.
Please find the Documentation Link.
Visit our Website Surepass.io.
- Android Studio (latest version recommended)
- Minimum SDK: 26
- Target SDK: 33+
- Java/Kotlin support
- GitHub account (for accessing SDK repository)
Before integrating the SDK, you need to obtain an authentication token from the Digiboost API.
Contact your sales manager to receive:
- Digilocker initialize endpoint URL
- Authorization Bearer Token (required for API access)
- Access permissions
π₯ Watch Video Tutorial For Generating SDK Token .
We provide two environments for different stages of development:
| Environment | Base URL | Usage |
|---|---|---|
| UAT (Testing) | https://sandbox.surepass.app |
For development and testing |
| Production | https://kyc-api.surepass.app |
For live applications |
For UAT Environment:
curl --location 'https://sandbox.surepass.app/api/v1/digilocker/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_GOT_FROM_SALES_MANAGER' \
--data '{
"data": {
"signup_flow": true,
"auth_type": "app",
"logo_url": "YOUR BRAND LOGO URL",
"voice_assistant_lang": "en",
"voice_assistant": false,
"retry_count": 2,
"skip_main_screen": false
}
}'For Production Environment:
curl --location 'https://kyc-api.surepass.app/api/v1/digilocker/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_GOT_FROM_SALES_MANAGER' \
--data '{
"data": {
"signup_flow": true,
"auth_type": "app",
"logo_url": "YOUR BRAND LOGO URL",
"voice_assistant_lang": "en",
"voice_assistant": false,
"retry_count": 2,
"skip_main_screen": false
}
}'| Parameter | Type | Required | Description | Default Value |
|---|---|---|---|---|
signup_flow |
boolean | β Required | This parameter should always be true for SDK initialization |
true |
auth_type |
string | β Required | Authentication type - must be set to "app" for SDK integration |
"app" |
logo_url |
string | β Optional | Your branding logo URL - customize with your own logo | None |
voice_assistant_lang |
string | β Optional | Voice assistant language. Possible options: "en" (English), "hi" (Hindi) |
"en" |
voice_assistant |
boolean | β Optional | Enable/disable voice assistant functionality | false |
retry_count |
integer | β Optional | Number of allowed retries during dropout prevention | 2 |
skip_main_screen |
boolean | β Optional | Whether to show the first intro screen or skip it | true |
Basic Configuration (Minimal):
{
"data": {
"signup_flow": true,
"auth_type": "app"
}
}Custom Branding with Voice Assistant:
{
"data": {
"signup_flow": true,
"auth_type": "app",
"logo_url": "https://yourcompany.com/logo.png",
"voice_assistant_lang": "hi",
"voice_assistant": true,
"retry_count": 3,
"skip_main_screen": false
}
}You'll receive a response like this:
{
"data": {
"client_id": "digilocker_cntWpMxWHbcvgghtyvxw",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiry_seconds": 600.0
},
"status_code": 200,
"message_code": "success",
"message": "Success",
"success": true
}Important:
- Copy the
tokenvalue - you'll need this for Step 3! - The token expires in 600 seconds (10 minutes) by default
- Store the
client_idif needed for tracking purposes
The Digiboost SDK is hosted on GitHub Packages. You need a Personal Access Token to access it.
π₯ Watch Video Tutorial For Generating PAT Token
- Go to GitHub.com and log in
- Click your profile picture (top-right corner)
- Select Settings from the dropdown menu
- Scroll down to the bottom of the left sidebar
- Click Developer settings
- Click Personal access tokens in the left sidebar
- Click Tokens (classic)
- Click the Generate new token button
- Select Generate new token (classic)
- Note: Enter a descriptive name like "Digiboost SDK Access"
- Expiration: Choose your preferred expiration (30 days, 60 days, etc.)
- Scopes: Check the following permissions:
- β
read:packages(Download packages from GitHub Package Registry) - β
repo(Full control of private repositories) - if needed
- β
- Click Generate token at the bottom
- IMPORTANT: Copy the token immediately - GitHub won't show it again!
- Store it securely (you'll need it for project configuration)
Update settings.gradle:
pluginManagement {
repositories {
google()
mavenCentral()
jcenter()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
jcenter()
mavenCentral()
// GitHub Packages repository for Digiboost SDK
maven {
url = "https://maven.pkg.github.com/surepassio/digiboost-sample-app"
credentials {
username = "YOUR_GITHUB_USERNAME" // Replace with your GitHub username
password = "YOUR_PAT_TOKEN" // Replace with your PAT token from Step 2.5
}
}
}
}
rootProject.name = "Digiboost Sample App"
include ':app'Update build.gradle (app level):
android {
compileSdk 33
defaultConfig {
minSdk 26 // Required minimum SDK
targetSdk 33
// ... other config
}
// ... other configuration
}
dependencies {
// Digiboost SDK dependency
implementation 'io.surepass.sdk:digiboost-android-sdk:1.0.1'
// ... your other dependencies
}Sync your project after making these changes.
Now let's integrate the SDK into your application with proper initialization and response handling.
class MainActivity : AppCompatActivity() {
private lateinit var binding: ActivityMainBinding
private lateinit var digiboostActivityResultLauncher: ActivityResultLauncher<Intent>
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityMainBinding.inflate(layoutInflater)
setContentView(binding.root)
// Register for activity result before onCreate completes
registerActivityForResult()
// Set up button click listener
setupSdkLaunch()
}
private fun setupSdkLaunch() {
binding.btnGetStarted.setOnClickListener {
// Use the token from Step 1
val token = "YOUR_TOKEN_FROM_STEP_1" // Replace with actual token
val env = "PREPROD" // or "PROD" for production
openDigiboostActivity(env, token)
}
}
}private fun openDigiboostActivity(env: String, token: String) {
try {
val intent = Intent(this, InitSdk::class.java).apply {
putExtra("token", token)
putExtra("env", env)
}
digiboostActivityResultLauncher.launch(intent)
} catch (e: Exception) {
Log.e("MainActivity", "Error launching Digiboost SDK: ${e.message}")
// Handle error appropriately
}
}private fun registerActivityForResult() {
digiboostActivityResultLauncher = registerForActivityResult(
ActivityResultContracts.StartActivityForResult()
) { result ->
when (result.resultCode) {
RESULT_OK -> {
val data = result.data
if (data != null) {
val digiboostResponse = data.getStringExtra("signedResponse")
Log.d("MainActivity", "Digiboost Response: $digiboostResponse")
handleSuccessResponse(digiboostResponse)
} else {
Log.w("MainActivity", "No data received from Digiboost SDK")
}
}
RESULT_CANCELED -> {
Log.i("MainActivity", "User cancelled Digiboost SDK")
handleCancelledResponse()
}
else -> {
Log.e("MainActivity", "Unexpected result code: ${result.resultCode}")
handleErrorResponse("Unexpected result")
}
}
}
}
private fun handleSuccessResponse(response: String?) {
response?.let {
// Process the signed response
showResponse(it)
// Parse and handle the response according to your app's needs
}
}
private fun handleCancelledResponse() {
// Handle user cancellation
Toast.makeText(this, "Document verification cancelled", Toast.LENGTH_SHORT).show()
}
private fun handleErrorResponse(error: String) {
// Handle error cases
Toast.makeText(this, "Error: $error", Toast.LENGTH_SHORT).show()
}
private fun showResponse(response: String?) {
// Display response in your UI
// You can show it in a dialog, text view, or navigate to a results screen
AlertDialog.Builder(this)
.setTitle("Verification Complete")
.setMessage("Response: $response")
.setPositiveButton("OK", null)
.show()
}After successful verification through the SDK, you can download the Aadhaar document using the Download Aadhaar API.
Use the client_id received from the SDK success response to download the Aadhaar document.
For UAT Environment:
curl --location 'https://sandbox.surepass.app/api/v1/digilocker/download-aadhaar' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_GOT_FROM_SALES_MANAGER' \
--data '{
"client_id": "CLIENT_ID_FROM_SDK_SUCCESS_RESPONSE"
}'For Production Environment:
curl --location 'https://kyc-api.surepass.app/api/v1/digilocker/download-aadhaar' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_GOT_FROM_SALES_MANAGER' \
--data '{
"client_id": "CLIENT_ID_FROM_SDK_SUCCESS_RESPONSE"
}'| Parameter | Type | Required | Description |
|---|---|---|---|
client_id |
string | β Required | The client ID received from the SDK success response after verification |
Success Response:
{
"data": {
"aadhaar_pdf": "base64_encoded_pdf_data",
"aadhaar_xml": "base64_encoded_xml_data",
"name": "John Doe",
"aadhaar_number": "XXXX-XXXX-1234",
"date_of_birth": "01-01-1990",
"gender": "M",
"address": {
"house": "123",
"street": "Main Street",
"landmark": "Near Park",
"locality": "Central Area",
"vtc": "City Name",
"district": "District Name",
"state": "State Name",
"pincode": "123456"
}
},
"status_code": 200,
"message_code": "success",
"message": "Aadhaar downloaded successfully",
"success": true
}Error Response:
{
"data": null,
"status_code": 400,
"message_code": "error",
"message": "Invalid client_id or verification not completed",
"success": false
}Here's how you can implement the Download Aadhaar API call in your Android app:
private fun downloadAadhaar(clientId: String) {
val apiUrl = if (isProduction) {
"https://kyc-api.surepass.app/api/v1/digilocker/download-aadhaar"
} else {
"https://sandbox.surepass.app/api/v1/digilocker/download-aadhaar"
}
val requestBody = JSONObject().apply {
put("client_id", clientId)
}
val request = Request.Builder()
.url(apiUrl)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer $YOUR_API_TOKEN")
.post(requestBody.toString().toRequestBody("application/json".toMediaType()))
.build()
client.newCall(request).enqueue(object : Callback {
override fun onResponse(call: Call, response: Response) {
if (response.isSuccessful) {
val responseBody = response.body?.string()
handleAadhaarDownloadSuccess(responseBody)
} else {
handleAadhaarDownloadError("API Error: ${response.code}")
}
}
override fun onFailure(call: Call, e: IOException) {
handleAadhaarDownloadError("Network Error: ${e.message}")
}
})
}
private fun handleAadhaarDownloadSuccess(responseJson: String?) {
try {
val jsonResponse = JSONObject(responseJson ?: "")
val data = jsonResponse.getJSONObject("data")
// Extract user information
val name = data.getString("name")
val aadhaarNumber = data.getString("aadhaar_number")
val dateOfBirth = data.getString("date_of_birth")
val gender = data.getString("gender")
// Extract documents (base64 encoded)
val aadhaarPdf = data.getString("aadhaar_pdf")
val aadhaarXml = data.getString("aadhaar_xml")
// Extract address
val address = data.getJSONObject("address")
val fullAddress = "${address.getString("house")}, ${address.getString("street")}, " +
"${address.getString("locality")}, ${address.getString("vtc")}, " +
"${address.getString("district")}, ${address.getString("state")} - ${address.getString("pincode")}"
// Process the downloaded data
Log.d("AadhaarDownload", "Name: $name, Aadhaar: $aadhaarNumber")
// Save or display the documents
saveAadhaarDocuments(aadhaarPdf, aadhaarXml)
} catch (e: Exception) {
Log.e("AadhaarDownload", "Error parsing response: ${e.message}")
}
}
private fun saveAadhaarDocuments(pdfBase64: String, xmlBase64: String) {
try {
// Decode base64 and save PDF
val pdfBytes = Base64.decode(pdfBase64, Base64.DEFAULT)
val pdfFile = File(filesDir, "aadhaar_document.pdf")
pdfFile.writeBytes(pdfBytes)
// Decode base64 and save XML
val xmlBytes = Base64.decode(xmlBase64, Base64.DEFAULT)
val xmlFile = File(filesDir, "aadhaar_data.xml")
xmlFile.writeBytes(xmlBytes)
Log.d("AadhaarDownload", "Documents saved successfully")
} catch (e: Exception) {
Log.e("AadhaarDownload", "Error saving documents: ${e.message}")
}
}
private fun handleAadhaarDownloadError(error: String) {
Log.e("AadhaarDownload", "Download failed: $error")
Toast.makeText(this, "Failed to download Aadhaar: $error", Toast.LENGTH_SHORT).show()
}- Client ID Source: The
client_idmust be obtained from the SDK success response after verification - Data Format: PDF and XML data are base64 encoded and need to be decoded before use
- Security: Store the downloaded data securely according to your compliance requirements
- API Response: The response includes both document files and extracted user information
- Error Handling: Always implement proper error handling for network requests
- Permissions: Ensure your app has appropriate storage permissions if saving files locally
You can customize the SDK's appearance by modifying your app's colors.xml:
File: res/values/colors.xml
<resources>
<color name="black">#FF000000</color>
<color name="white">#FFFFFFFF</color>
<color name="background_color">#B82C5A</color>
<!-- Add this line to customize Digiboost SDK theme -->
<color name="surepass_color">#FF9800</color> <!-- Replace with your brand color -->
</resources>After making changes:
- Clean and rebuild your project
- The SDK will automatically use your custom theme color
Solution:
- Verify your GitHub username and PAT token in
settings.gradle - Ensure your PAT token has
read:packagespermission - Check your internet connection
Solution:
- Generate a new token using Step 1
- Tokens expire after the specified time (usually 10 minutes)
Solution:
- Ensure your
minSdkis set to 26 or higher - Update your
build.gradleaccordingly
Solution:
- Verify the token format is correct
- Check that all dependencies are properly synced
- Ensure you've registered the activity result launcher before
onCreatecompletes
Try Our Sample App
- Build and run your application
- Tap the "Get Started" button (or your trigger button)
- Verify the SDK launches successfully
- Complete a test verification to ensure the full flow works
- Check the logs for the response data
If you encounter any issues:
- Check the troubleshooting section above
- Contact your sales manager for API-related issues
- Contact Tech Support at [email protected]
- Review the logs for detailed error messages
This sample application is provided as-is for integration testing purposes.
β¨ You're all set! Your Digiboost SDK integration is complete.