Alaqan Mini SDK
for Android

Introduction

The Alaqan Mini SDK enables Android applications to integrate palm vein biometric authentication using the Alaqan Mini hardware device. The SDK provides a secure, easy-to-use interface for user registration and identification through contactless palm recognition technology.

Use Cases

• Point of Sale (POS) authentication
• Banking and financial services
• Access control systems
• Time and attendance tracking
• Identity verification

Requirements

Hardware

Software

Network

• Active internet connection required for SDK operations
• Minimum bandwidth: 1 Mbps recommended

Installation

app/
├── libs/
│   └── alaqan-mini-sdk-1.0.0.aar
├── src/
└── build.gradle

android {
    defaultConfig {
        minSdk 24
        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a'
        }
    }
}

dependencies {
    implementation files('libs/alaqan-mini-sdk-1.0.0.aar')
}

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

<manifest>
    <uses-feature android:name="android.hardware.usb.host" android:required="true" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application>
        <activity android:name=".MainActivity">
            <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>
    </application>
</manifest>

Quick Start

Here's a minimal example to get you started with the Alaqan Mini SDK:

class MainActivity : AppCompatActivity(), AlaqanMiniListener {
    private lateinit var sdk: AlaqanMiniSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        sdk = AlaqanMiniSDK.getInstance()
        val errorCode = sdk.initialize(this, "YOUR_API_KEY")
        if (errorCode != 0) { Log.e("Alaqan", "Init failed: $errorCode"); return }
        sdk.setListener(this)
    }

    override fun onResume() { super.onResume(); sdk.connect() }
    override fun onPause() { super.onPause(); sdk.disconnect() }
    override fun onDestroy() { super.onDestroy(); sdk.destroy() }

    override fun onDeviceConnected() {
        Log.d("Alaqan", "Device connected: ${sdk.serialNumber}")
    }

    override fun onIdentifyFinish(result: IdentifyResult) {
        when (result.status) {
            IdentifyStatus.SUCCESS -> Log.d("Alaqan", "Identified: ${result.userId}")
            IdentifyStatus.NOT_FOUND -> Log.d("Alaqan", "Not recognized")
        }
    }
}

SDK Architecture

Lifecycle Management

The SDK follows Android lifecycle best practices. All callbacks are delivered on the main (UI) thread.

API Reference

Initialization

initialize()

Initializes the SDK with the application context and API credentials.

fun initialize(context: Context, apiKey: String): Int

Returns: Int — Error code (0 if successful)

Connection Management

connect()

Initiates connection to the Alaqan Mini device.

fun connect(): Boolean

disconnect()

Disconnects from the Alaqan Mini device.

fun disconnect()

isConnected

val isConnected: Boolean

Device Information

val serialNumber: String?     // e.g., "GX4TYQWH3D"
val firmwareVersion: String?  // e.g., "1.2.3"

Registration

startRegister()

Starts the palm registration process for a new user. The SDK captures 3 palm images.

fun startRegister(): Boolean

Callbacks: onRegisterProgress(), onCaptureFeedback(), onRegisterFinish()

stopRegister()

fun stopRegister()

Identification

startIdentify()

Starts the palm identification process.

fun startIdentify(): Boolean

Callbacks: onCaptureFeedback(), onIdentifyFinish()

stopIdentify()

fun stopIdentify()

Configuration

setTimeout()

fun setTimeout(operationType: OperationType, timeoutMs: Long)

Callbacks & Listeners

interface AlaqanMiniListener {
    fun onDeviceConnected()
    fun onDeviceDisconnected()
    fun onRegisterProgress(progress: RegisterProgress)
    fun onRegisterFinish(result: RegisterResult)
    fun onIdentifyFinish(result: IdentifyResult)
    fun onCaptureFeedback(feedback: CaptureFeedback)
    fun onError(error: AlaqanError)
}

Data Models

data class RegisterResult(
    val status: RegisterStatus,  // SUCCESS, DUPLICATE, FAILED, CANCELLED, TIMEOUT
    val userId: String?,
    val errorCode: Int?,
    val errorMessage: String?
)

data class IdentifyResult(
    val status: IdentifyStatus,  // SUCCESS, NOT_FOUND, FAILED, CANCELLED, TIMEOUT
    val userId: String?,
    val confidence: Float?,     // 0.0-1.0
    val errorCode: Int?,
    val errorMessage: String?
)

data class CaptureFeedback(
    val status: CaptureStatus,
    val guidance: CaptureGuidance?,  // MOVE_CLOSER, MOVE_FARTHER, CENTER_PALM, etc.
    val qualityScore: Float
)

Error Codes

Connection (1000-1099)

Registration (2000-2099)

Identification (3000-3099)

Network (4000-4099)

License (6000-6099)

General (9000-9099)

Best Practices

Error Handling

override fun onError(error: AlaqanError) {
    when (error.code) {
        in 1000..1099 -> handleConnectionError(error)
        in 2000..2099 -> handleRegistrationError(error)
        in 3000..3099 -> handleIdentificationError(error)
        in 4000..4099 -> handleNetworkError(error)
        in 6000..6099 -> handleLicenseError(error)
        else -> handleGeneralError(error)
    }
}

Troubleshooting

Device Not Detected

Symptoms: onDeviceConnected() never called, ERROR_DEVICE_NOT_FOUND

• Verify Alaqan Mini is properly connected
• Check USB OTG is enabled on the Android device
• Verify device_filter.xml contains correct VID/PID values
• Try a different USB cable

USB Permission Denied

Symptoms: ERROR_USB_PERMISSION_DENIED

• Ensure USB permission dialog is shown and accepted
• Check that your Activity handles USB intents correctly
• Clear app data and try again

SDK Initialization Fails

Symptoms: initialize() returns non-zero

• Verify API key is correct
• Ensure active internet connection
• Check that API key has not expired
• Check logcat for detailed error messages

Sample Implementation

Contact Alaqan support for a complete sample project with full source code.

Support