Biometrik

v1.0.0

Biometrik allows to perform the bio-authentication on Compose Multiplatform applications leveraging the native APIs provided by each platform

Architecture

• Android under the hood uses the BiometricPrompt APIs
• iOs and native macOs under the hood uses the local authentication APIs
• JVM under the hood uses the native APIs provided by the different OSs:
  • On Windows uses the Windows Hello APIs
  • On Linux uses the Polkit APIs
  • OnMacOs uses the local authentication APIs
• Web under the hood uses the WebAuthn APIs

Integration

Implementation

Version catalog

[versions]
biometrik = "1.0.0"

[libraries]
biometrik = { module = "io.github.n7ghtm4r3:Biometrik", version.ref = "biometrik" } 

Gradle

• Add the dependency

  dependencies {
      implementation 'io.github.n7ghtm4r3:Biometrik:1.0.0'
  }

  Gradle (Kotlin)

  dependencies {
      implementation("io.github.n7ghtm4r3:Biometrik:1.0.0")
  }

  Gradle (version catalog)

  dependencies {
      implementation(libs.biometrik)
  }

Setup

Android

To correctly integrate Biometrik on the android target you need to following these simple steps:

AppCompact implementation

The native BiometricPrompt api requires that the activity which request the authentication must be an AppCompatActivity activity, for this, you need to implement in your android's dependencies the following library:

sourceSets {

  androidMain.dependencies {

    ...
    implementation("androidx.appcompat:appcompat:1.7.1")
  }

}

Adapting the MainActivity

The next step is to adapt your MainActivity to extends the AppCompatActivity activity type:

// before it extended ComponentActivity instead
class MainActivity : AppCompatActivity() {

  ...

}

Configuring theme

The latest step is to change the theme of the MainActivity from the AndroidManifest file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

  <application
          android:allowBackup="true"
          android:icon="@mipmap/ic_launcher"
          android:label="@string/app_name"
          android:roundIcon="@mipmap/ic_launcher_round"
          android:supportsRtl="true"
          android:theme="@android:style/Theme.Material.Light.NoActionBar">
    <activity
            android:exported="true"
            android:theme="@style/Theme.AppCompat.DayNight.NoActionBar"
            android:name=".MainActivity">
      <intent-filter>
        <action android:name="android.intent.action.MAIN"/>

        <category android:name="android.intent.category.LAUNCHER"/>
      </intent-filter>
    </activity>
  </application>

</manifest>

In the example, the @style/Theme.AppCompat.DayNight.NoActionBar style has been used, but you can implement any theme as long as it is based on the Theme.AppCompat style

Wasm

To correctly integrate Biometrik on the wasm target you need to enable the handling of the native exceptions thrown by JavaScript. You can do this by adding the following compiler option:

compilerOptions {
  freeCompilerArgs.add("-Xwasm-attach-js-exception")
}

This ensures that JavaScript exceptions are properly caught and propagated through Kotlin’s exception handling system when targeting WebAssembly (WASM)

Usage

In your App.kt file you can simply integrate the following component and customize the authentication flow as you need:

BiometrikAuthenticator(
    appName = "MyApplication",
    title = "Indicative title displayed if the native dialogs allow it",
    reason = "An indicative reason why the user have to authenticate",
    onSuccess = {
        // non-UI action
        println("User logged in!")
        // UI action
        WelcomeScreen()
    },
    onFailure = {
        // non-UI action
        println("User failed to login...")
        // UI action
        OpsScreen()
    }
)

You can also allow the user to retry to authenticate using a custom state:

// create the custom state
val state = rememberBiometrikState()

// attach it to the component
BiometrikAuthenticator(
    state = state
    appName = "MyApplication",
    title = "Indicative title displayed if the native dialogs allow it",
    reason = "An indicative reason why the user have to authenticate",
    onSuccess = {
        // non-UI action
        println("User logged in!")
        // UI action
        WelcomeScreen()
    },
    onFailure = {
        // non-UI action
        state.reAuth() // retry to authenticate
        // UI action
        Button(
            onClick = {
                state.reAuth() // retry to authenticate
            }
        ) {
            Text(
                text = "Retry"
            )
        }
    }
)

Native engines

Warning

Any pull requests containing dynamic library output files will be rejected for security reasons.
If there are changes to the native engines, please edit the source code and create the pull request without including the output files. The maintainers will handle the compilation

If you need to apply changes to the native engines, follow the steps below depending on which engine you want to modify:

Windows

If you need to change the Windows's engine you can find the Visual Studio documented files project where you can apply your modification:

nativeengines
├── windows
    └── ... files ...

The requirements are:

• The minimum required version is Standard C++ 17 ISO (/std:c++17)
• Include the required windowsapp.lib library in the additional linker input dependencies

Linux

Currently, authentication on Linux is supported via Polkit. Biometric support may be considered in future releases.

To modify the native engine you can find its file on:

nativeengines
├── linux
    └── PolkitEngine.c

After applied the modification you needed, you can compile it with the below command:

gcc -fPIC -shared -o LinuxPolkitEngine.so  PolkitEngine.c $(pkg-config --cflags --libs polkit-gobject-1 gio-2.0 glib-2.0)

MacOs

To modify the native engine you can find its file on:

nativeengines
├── macos
    └── LocalAuthenticationEngine.m

After applied the modification you needed, you can compile it with the below command:

clang -framework Foundation -framework LocalAuthentication -shared -o LocalAuthenticationEngine.dylib LocalAuthenticationEngine.m

Place the dynamic libraries

Note

This step applies only for local usage, do not include the compiled libraries in a pull request, or it will be rejected

Once compiled, place the dynamic libraries in the appropriate platform-specific directories

resources
├── windows
│   └── WindowsHelloEngine.dll
├── linux
│   └── LinuxPolkitEngine.so
└── macos
    └── LocalAuthenticationEngine.dylib

Documentation

Check out the library documentation here!

Support

If you need help using the library or encounter any problems or bugs, please contact us via the following links:

• Support via email
• Support via GitHub

Thank you for your help!

Donations

If you want support project and developer

Crypto	Address	Network
	3H3jyCzcRmnxroHthuXh22GXXSmizin2yp	Bitcoin
	0x1b45bc41efeb3ed655b078f95086f25fc83345c4	Ethereum
	AtPjUnxYFHw3a6Si9HinQtyPTqsdbfdKX3dJ1xiDjbrL	Solana

If you want support project and developer with PayPal

Copyright © 2025 Tecknobit