Alaqan Mini SDK
для Android

Введение

Alaqan Mini SDK позволяет Android-приложениям интегрировать биометрическую аутентификацию по венам ладони с использованием устройства Alaqan Mini.

Сценарии использования

• Аутентификация в POS-терминалах
• Банковские и финансовые услуги
• Системы контроля доступа
• Учёт рабочего времени
• Верификация личности

Требования

Аппаратное обеспечение

Программное обеспечение

Сеть

• Активное интернет-соединение для работы SDK
• Рекомендуемая пропускная способность: 1 Мбит/с

Установка

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>

Быстрый старт

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", "Ошибка: $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", "Подключено: ${sdk.serialNumber}")
    }

    override fun onIdentifyFinish(result: IdentifyResult) {
        when (result.status) {
            IdentifyStatus.SUCCESS -> Log.d("Alaqan", "Найден: ${result.userId}")
            IdentifyStatus.NOT_FOUND -> Log.d("Alaqan", "Не распознан")
        }
    }
}

Архитектура SDK

Жизненный цикл

Справочник API

Инициализация

initialize()

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

Возвращает: Код ошибки (0 — успех)

Подключение

connect()

fun connect(): Boolean

disconnect()

fun disconnect()

isConnected

val isConnected: Boolean

Информация об устройстве

val serialNumber: String?     // например, "GX4TYQWH3D"
val firmwareVersion: String?  // например, "1.2.3"

Регистрация

startRegister()

fun startRegister(): Boolean

Обратные вызовы: onRegisterProgress(), onCaptureFeedback(), onRegisterFinish()

stopRegister()

fun stopRegister()

Идентификация

startIdentify()

fun startIdentify(): Boolean

Обратные вызовы: onCaptureFeedback(), onIdentifyFinish()

stopIdentify()

fun stopIdentify()

Конфигурация

setTimeout()

fun setTimeout(operationType: OperationType, timeoutMs: Long)

Обратные вызовы

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 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...
    val qualityScore: Float
)

Коды ошибок

Подключение (1000-1099)

Регистрация (2000-2099)

Идентификация (3000-3099)

Сеть (4000-4099)

Лицензия (6000-6099)

Общие (9000-9099)

Лучшие практики

Обработка ошибок

Используйте диапазоны кодов ошибок для группированной обработки:

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)
    }
}

Устранение неполадок

Устройство не обнаружено

Симптомы: onDeviceConnected() не вызывается, ERROR_DEVICE_NOT_FOUND

• Проверьте подключение Alaqan Mini
• Убедитесь, что USB OTG включён
• Проверьте device_filter.xml на правильность VID/PID
• Попробуйте другой USB-кабель

Ошибка разрешения USB

Симптомы: ERROR_USB_PERMISSION_DENIED

• Убедитесь, что диалог разрешения USB отображается и принимается
• Проверьте правильность обработки USB-интентов в Activity
• Очистите данные приложения и попробуйте снова

Ошибка инициализации SDK

Симптомы: initialize() возвращает ненулевое значение

• Проверьте правильность API-ключа
• Убедитесь в наличии интернет-соединения
• Проверьте, не истёк ли срок действия API-ключа
• Проверьте logcat для получения подробных сообщений об ошибках

Пример реализации

Свяжитесь с поддержкой Alaqan для получения полного примера проекта.

Поддержка