Usage

Sample Flows

BioMatch Register Flow

This section outlines the typical flow for registering a user using the BioMatch SDK.

1. Obtain the token of a verified profile.
2. Configure the SDK with the retrieved token and server URL.
3. Call the PIN Fragment to display the PIN entry screen.
4. After the PIN callback is triggered, call PIN Enable to register the PIN for the verified profile.

BioMatch Auth/Payment Flow

This section outlines the typical flow for performing authentication or payment using the BioMatch SDK.

1. Obtain a general token independent of any specific profile.
2. Display the Selfie Fragment to capture the user’s face.
3. After the Selfie Fragment is completed, navigate to the PIN Fragment.
4. Once the PIN callback is triggered, call the Selfie upload function, passing the user-entered PIN as a parameter.
5. Use the result of the upload callback to determine whether the authentication or payment was successful.

Initial Configuration

Basic Setup

After preparing your project, configure the BioMatch SDK in your Application class or MainActivity.
This step initializes the SDK with your server URL and authentication token so it can perform facial recognition and PIN verification.

import ai.amani.biomatch.sdk.AmaniBioMatchSDK
import android.app.Application

class App :Application(){

    override fun onCreate() {
        super.onCreate()

        AmaniBioMatchSDK.configure(
            context = this,
            server = "SERVER_URL",
            token = "TOKEN",
        )
    }
}

Fragment Implementations

Selfie Capture

The SDK returns a Fragment for capturing selfies. Embed it in your XML layout to allow users to capture their face for verification.

val selfieFragment = AmaniBioMatchSDK.Selfie().start(
    config = SelfieCaptureConfig(
    manualCaptureButtonInnerColor = Color.BLUE,
    manualCaptureButtonOuterColor = Color.BLUE,
    manualCaptureButtonLoaderColor = Color.BLUE,
    primaryButtonBackgroundColor = Color(0xFF3B82F6),
    secondaryButtonColor = Color(0xFF6B7280),
    appFontColor = Color.White,
    appBackgroundColor = Color(0xFF1F2937),
    overlayBackgroundColor = Color(0x80000000),
    ovalBorderColor = Color(0xFF3B82F6),
    instructionText = "Please position your face inside the oval frame",
    permissionDeniedTitle = "Permissions Required",
    permissionDeniedMessage = "To take a selfie, please grant camera permission. Location permission is optional but recommended for better service.",
    retryButtonText = "Try Again",
    settingsButtonText = "Settings"),
    onCaptureCompleted = { filePath ->
        // Handle captured selfie file path
    }
)

// Add the fragment to your container
yourFragmentNavigateMethod(selfieFragment)

PIN Verification

After capturing a selfie, use the PIN Fragment to verify the user's PIN. This ensures that both the face and PIN are verified for security.

val pinFragment = AmaniBioMatchSDK.PIN().start(
    config = PinScreenConfig(
        pinLength = 4,
        title = "Enter PIN",
        subtitle = "Please enter your security PIN",
        backgroundColor = Color.WHITE,
        titleColor = Color.parseColor("#1F2937"),
        subtitleColor = Color.parseColor("#6B7280"),
        pinDotFilledColor = Color.parseColor("#3B82F6"),
        pinDotEmptyColor = Color.parseColor("#E5E7EB"),
        keypadButtonBackgroundColor = Color.parseColor("#F9FAFB"),
        keypadButtonNumberColor = Color.parseColor("#1F2937"),
        deleteButtonContentColor = Color.parseColor("#EF4444"),
        keypadButtonBorderColor = Color.parseColor("#E5E7EB")
    ),
    onPinComplete = { pin ->
        // Process the entered PIN
        enablePinVerification(pin)
    }
)

// Add the fragment to your container
yourFragmentNavigateMethod(pinFragment)

SDK Operations

This section covers operations you can perform with the SDK after the user has interacted with the Fragments.
It includes enabling PIN verification and uploading selfies for authentication or payment flows.

Enable PIN Verification

To enable the PIN, it must belong to a verified profile. Make sure the user’s profile is already verified before calling this.
This method should be called after the PIN Fragment completes and the PIN data is obtained.

Optionally, you can pass a PIN value from your own PIN screen if you have a custom implementation.

AmaniBioMatchSDK.PIN().enable(
        pin,
        callback = object : PINCallback {
            override fun onSuccess() {
                // PIN successfully enabled
                yourFragmentNavigateMethod("success_screen")
            }

            override fun onError(exception: Exception) {
                // Handle PIN enable error
                showError("PIN enable failed: ${exception.message}")
            }
        }
    )

Upload Selfie with PIN

The upload method uploads the selfie together with the user’s PIN for verification or payment flows.
Only the PIN is passed as a parameter; the selfie data is handled internally by the SDK.
This method must only be called after the Selfie Fragment has successfully completed, because the SDK needs the captured selfie internally to perform the upload. Calling it before the selfie is captured may result in errors or invalid uploads.

AmaniBioMatchSDK.Selfie().upload(
    pin = "USER_PIN",
    callback = object : SelfieCallback {
        override fun onSuccess() {
            // Selfie upload successful
            yourFragmentNavigateMethod("payment_success")
        }

        override fun onError(exception: Exception) {
            // Handle upload error
            showError("Selfie upload failed: ${exception.message}")
        }
    }
)