Biometrics SDK Integration Guide

The RMS Techknowledgy Biometrics SDK brings touchless fingerprint verification to Android applications. Using only the device camera and AI-powered hand detection, it captures and verifies fingerprints without any dedicated scanning hardware. The SDK presents its own capture interface, guides the user through the scan, and returns a single result to your application — camera handling, permission prompts, and image processing are managed entirely by the SDK.

The SDK is written in Kotlin and can be used from both Kotlin and Java. Code samples for both languages are provided below.

Requirements

A typical app module configuration:

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    compileSdk 33
    defaultConfig {
        minSdk 24
        targetSdk 33
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions { jvmTarget = '1.8' }
}

Ensure that jvmTarget and the compileOptions Java version match; recent Gradle versions treat a mismatch as a build error.

For projects that do not use the plugins {} DSL, add the Kotlin classpath to the root build.gradle instead:

buildscript {
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.7.10"
    }
}

Installation

The SDK is distributed exclusively through JitPack. The repository is private, so the access token provided with your license is required.

Step 1: Add JitPack Repository

Add the JitPack repository to your project's settings.gradle:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://jitpack.io'
            credentials { username authToken }
        }
    }
}

Step 2: Add Dependency

Declare the dependency in your app module:

dependencies {
    implementation 'com.github.RMS-Techknowledgy-Private-Limited:biometrics-sdk:1.0.6'
}

Step 3: Sync Project

After a Gradle sync, the integration is complete. All of the SDK's transitive dependencies are resolved automatically.

Permissions

No permission configuration is required. The SDK's manifest declares the camera and internet permissions it needs, and Android merges them into your application at build time. The runtime camera prompt is also presented by the SDK on its own screen, so your application does not need to request it beforehand.

Quick Start

import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.biometrics.Biometrics
import com.biometrics.model.BiometricsResult

class MainActivity : AppCompatActivity() {

    // Register once, as a field or in onCreate. Registration must occur before
    // the activity is started, so it cannot be placed inside a click listener.
    private val biometrics = Biometrics.register(this) { result ->
        handleResult(result)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        findViewById<android.widget.Button>(R.id.verifyButton).setOnClickListener {
            biometrics.launch(
                token = "YOUR_AUTH_TOKEN",
                nicNumber = "3520212345671"
            )
        }
    }

    private fun handleResult(result: BiometricsResult) {
        when (result) {
            is BiometricsResult.Success -> {
                // The flow completed and a verdict was returned. Always check
                // `outcome` — Success alone does not indicate a match.
                when (result.outcome) {
                    "success"  -> { /* verified — proceed */ }
                    "no-match" -> { /* fingerprints did not match */ }
                    "error"    -> { /* processing problem — offer a retry */ }
                }
                // Store result.trnxId with your records. It is the reference
                // for any support or billing queries.
                result.fingers.forEach { f ->
                    Log.d("Biometrics", "${f.finger}: ${f.matchResult} (${f.matchScore})")
                }
            }
            is BiometricsResult.Error -> {
                Log.e("Biometrics", result.message)
            }
            is BiometricsResult.Cancelled -> {
                // The user closed the flow. No transaction was created.
            }
        }
    }
}

Registration from a Fragment works identically: Biometrics.register(fragment) { ... }.

The user selects which hand to scan within the SDK itself, so no parameters beyond the token and NIC number are required.

API Reference

Biometrics.register

Biometrics.register(activityOrFragment) { result -> } registers the result callback and returns a BiometricsLauncher. Call it once per Activity or Fragment, early in the lifecycle — a field initializer or onCreate are both appropriate.

BiometricsLauncher.launch

BiometricsLauncher.launch(token, nicNumber) starts the verification flow.

• token — the authentication token obtained from your backend. An invalid or expired token produces an Error result.
• nicNumber — the NIC/CNIC number against which the fingerprints are verified.

BiometricsResult

BiometricsResult is delivered exactly once per launch, on the main thread, as one of three types:

• Success — the flow completed and a verdict was returned. It carries:
  • trnxId — the transaction identifier. Store it; it is the reference for any follow-up enquiry.
  • outcome — "success", "no-match", or "error". This field holds the actual verdict.
  • fingers — a list of FingerMatchResult entries, one per attempted finger, each containing finger, matchResult, an optional matchScore, and an optional matchMessage.
• Error(message) — the flow could not be completed (for example, an invalid token or a network failure). No transaction was created.
• Cancelled — the user exited the flow.

Lifecycle Notes

• Register early; launch at any time afterwards. Registration must precede the Activity's or Fragment's started state, while launch may be called from any event — a button tap, a coroutine, or a React Native bridge method.
• Registering lazily (for example, inside onClick) raises LifecycleOwner is attempting to register while current state is RESUMED. Move the register call to a field initializer or to onCreate.
• Configuration changes are handled by the Activity Result API. Provided that register runs again in the re-created activity's onCreate — which it does when declared as a field — the result is delivered normally.
• For React Native and other hybrid frameworks: register the launcher when the host activity is created, retain the BiometricsLauncher reference, and expose a bridge method that calls launch.

Troubleshooting

Support

For tokens, licensing, or any matter not covered in this guide, contact your RMS Techknowledgy representative.