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(
    autoSelfieEnabled = true,
    manualCaptureButtonTimeOut = 34000,
    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)

SelfieCaptureConfig Parameters

Parameter Name	Type	Default Value	Description
autoSelfieEnabled (✨ New!)	Boolean	false	Enables automatic selfie capture.
manualCaptureButtonTimeOut (✨ New!)	Long	60000	Timeout duration (in ms) for the manual capture button.
manualCaptureButtonInnerColor	Color	Color(0xFFFFFFFF)	Inner color of the manual capture button.
manualCaptureButtonOuterColor	Color	Color(0xFFFFFFFF)	Outer color of the manual capture button.
manualCaptureButtonLoaderColor	Color	Color(0xFFFCFCFC)	Loader/spinner color displayed inside the manual capture button.
primaryButtonBackgroundColor	Color	Color(0xFF3B82F6)	Background color for the primary button (e.g., "Continue" or "Capture").
secondaryButtonColor	Color	Color(0xFF6B7280)	Color for secondary or less prominent buttons.
appFontColor	Color	Color.White	Default font color used across the screen.
appBackgroundColor	Color	Color(0xFF1F2937)	Background color of the entire Selfie Capture screen.
overlayBackgroundColor	Color	Color(0x80000000)	Semi-transparent overlay background color behind the oval frame.
ovalBorderColor	Color	Color(0xFFFFFFFF)	Border color of the oval frame.
instructionText	String	"Lütfen yüzünüzü oval çerçeve içine yerleştirin"	Instruction text shown to the user.
permissionDeniedTitle	String	"İzinler Gerekli"	Title displayed in the permission denied dialog.
permissionDeniedMessage	String	"Selfie çekebilmek için lütfen kamera iznini verin. Konum izni opsiyoneldir ancak daha iyi hizmet için önerilir."	Message displayed when camera permission is denied.
retryButtonText	String	"Tekrar Dene"	Text for the retry button.
settingsButtonText	String	"Ayarlar"	Text for the settings button.

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)

PinScreenConfig Parameters

Parameter Name	Type	Default Value	Description
pinLength	Int	4	Number of digits for the PIN.
title	String	"Enter PIN"	Title text displayed on the screen.
subtitle	String	"Please enter your security PIN"	Subtitle or instruction text for the user.
backgroundColor	Color	Color(0xFFFFFFFF)	Background color of the PIN screen.
titleColor	Color	Color(0xFF111827)	Color of the title text.
subtitleColor	Color	Color(0xFF4B5563)	Color of the subtitle text.
pinDotFilledColor	Color	Color(0xFF000000)	Color of a filled PIN dot.
pinDotEmptyColor	Color	Color(0xFFD1D5DB)	Color of an empty PIN dot.
keypadButtonBackgroundColor	Color	Color(0xFFF3F4F6)	Background color of keypad buttons.
keypadButtonNumberColor	Color	Color(0xFF111827)	Color of numbers on keypad buttons.
keypadButtonBorderColor	Color	Color(0xFF9CA3AF)	Border color of keypad buttons.
deleteButtonContentColor	Color	Color(0xFFB41919)	Color of the delete button icon or text.
deleteButtonBackgroundColor	Color	Color(0xFFF3F4F6)	Background color of the delete button.
deleteButtonBorderColor	Color	Color(0xFF9CA3AF)	Border color of the delete button.

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