SecuGen Biometric SDK Integration Guide

This guide explains how to integrate and use the SecuGen Biometric SDK in your Android application when provided with the AAR files.

Prerequisites

• Android API Level 24 (Android 7.0) or higher
• Java 8 or higher
• Android Studio 4.0 or higher
• SecuGen fingerprint device (HU10, HU20, FDU series)

Step 1: Add the SDK to Your Project

1.1 Add the AAR File

1. Create a libs folder in your app module directory if it doesn't exist:

   your-app/
   ├── src/
   ├── libs/           # Create this folder
   └── build.gradle
   

2. Copy the provided AAR file to the libs folder:

   your-app/libs/biometrics-sdk.aar
   

📋 Note: The SecuGen SDK (FDxSDKProFDAndroid.jar) is already bundled inside the AAR - no separate JAR needed!

1.2 Update Module-level build.gradle

Add the following to your app's build.gradle file:

android {
    compileSdk 35
    
    defaultConfig {
        minSdk 24
        targetSdk 34
    }
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    
    packagingOptions {
        pickFirst '**/*.so'
    }
}

dependencies {
    // Add the SDK AAR
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    
    // Required dependencies
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.9.0'
    
    // JSON parsing
    implementation 'com.google.code.gson:gson:2.10.1'
    
    // HTTP client
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'org.java-websocket:Java-WebSocket:1.5.1'
    
    // Security/Cryptography
    implementation 'org.bouncycastle:bcprov-jdk15to18:1.73'
    implementation 'org.bouncycastle:bcpkix-jdk15to18:1.73'
}

Step 2: Add Permissions

Add the following permissions to your AndroidManifest.xml:

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

<uses-feature 
    android:name="android.hardware.usb.host" 
    android:required="false" />

2.1 Add USB Device Filter

Create res/xml/device_filter.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <usb-device vendor-id="1162" />
</resources>

Add to your Activity in AndroidManifest.xml:

<activity android:name=".MainActivity" android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    
    <intent-filter>
        <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
    </intent-filter>
    <meta-data 
        android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
        android:resource="@xml/device_filter" />
</activity>

Step 3: Initialize the SDK

3.1 Basic Initialization

import ke.go.ecitizen.core.EcitizenSDK
import ke.go.ecitizen.core.EcitizenInterface
import ke.go.ecitizen.data.DataListener

class MainActivity : AppCompatActivity() {
    private lateinit var sdk: EcitizenSDK
    private var isDeviceReady = false
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        // Initialize SDK
        sdk = EcitizenSDK.getInstance()
        
        // Initialize SecuGen device
        initializeDevice()
    }
    
    private fun initializeDevice() {
        sdk.initializeSecuGenDeviceAsync(this, object : EcitizenInterface.SecuGenReadyListener {
            override fun onSecuGenDeviceReady() {
                runOnUiThread {
                    isDeviceReady = true
                    Log.d("SDK", "SecuGen device ready")
                    // Enable your capture button here
                }
            }
        })
    }
}

Step 4: Capture Fingerprints

4.1 Start Biometric Capture

private fun startFingerprint() {
    if (!isDeviceReady) {
        showError("Device not ready")
        return
    }
    
    val dataListener = object : DataListener {
        override fun onDataReceived(data: JSONObject) {
            handleResult(data)
        }
        
        override fun onError(e: Exception) {
            showError("Capture failed: ${e.message}")
        }
    }
    
    sdk.startBiometricCapture(
        idNumber = "12345678",
        requestCode = "REQ001",
        accessToken = "your_access_token",
        clientID = "your_client_id",
        embeddedToken = "REQ001",
        dataListener = dataListener
    )
}

4.2 Handle Results

private fun handleResult(data: JSONObject) {
    try {
        val event = data.getString("event")
        when (event) {
            "match_result" -> {
                val resultData = data.getJSONObject("data")
                val isMatch = resultData.getBoolean("match")
                val status = resultData.getString("status")
                
                if (isMatch) {
                    showSuccess("Fingerprint matched!")
                } else {
                    showError("No match found")
                }
            }
            "secugen_capture_complete" -> {
                Log.d("SDK", "Capture completed, processing...")
            }
        }
    } catch (e: Exception) {
        showError("Error processing result: ${e.message}")
    }
}

private fun showSuccess(message: String) {
    Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
}

private fun showError(message: String) {
    Toast.makeText(this, message, Toast.LENGTH_LONG).show()
}

Step 5: Handle USB Permissions

5.1 Request USB Permission

private fun requestUSBPermission() {
    val usbManager = getSystemService(Context.USB_SERVICE) as UsbManager
    val deviceList = usbManager.deviceList
    
    deviceList.values.forEach { device ->
        if (device.vendorId == 1162 && !usbManager.hasPermission(device)) {
            val permissionIntent = PendingIntent.getBroadcast(
                this, 0,
                Intent("com.yourpackage.USB_PERMISSION"),
                PendingIntent.FLAG_IMMUTABLE
            )
            usbManager.requestPermission(device, permissionIntent)
        }
    }
}

Common Issues

Device Not Detected

• Check USB permissions are granted
• Verify device_filter.xml has correct vendor ID (1162)
• Ensure USB cable is properly connected

Build Errors

• Verify the AAR file is in libs/ folder (biometrics-sdk.aar)
• Check pickFirst '**/*.so' is in packagingOptions
• Add ProGuard rules for release builds

Network Issues

• Verify INTERNET permission
• Check your access token is valid
• Ensure network connectivity

Supported Devices

• SecuGen HU10 Series
• SecuGen HU20 Series
• SecuGen HU20A Series
• SecuGen FDU03, FDU04, FDU05, FDU06, FDU07, FDU08, FDU08A, FDU09A, FDU10A

API Reference

Main Methods

// Initialize device
sdk.initializeSecuGenDeviceAsync(context, readyListener)

// Start capture
sdk.startBiometricCapture(idNumber, requestCode, accessToken, clientID, embeddedToken, dataListener)

// Check if device is ready
sdk.isSecuGenDeviceReady()

Events

• match_result - Fingerprint matching result
• secugen_capture_complete - Capture completed
• fingerprint_device_state - Device state changes

---

That's it! Your SecuGen integration should now be working. For more detailed examples, see the included documentation files.