Skip to main content

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 NameTypeDefault ValueDescription
autoSelfieEnabled (✨ New!)BooleanfalseEnables automatic selfie capture.
manualCaptureButtonTimeOut (✨ New!)Long60000Timeout duration (in ms) for the manual capture button.
manualCaptureButtonInnerColorColorColor(0xFFFFFFFF)Inner color of the manual capture button.
manualCaptureButtonOuterColorColorColor(0xFFFFFFFF)Outer color of the manual capture button.
manualCaptureButtonLoaderColorColorColor(0xFFFCFCFC)Loader/spinner color displayed inside the manual capture button.
primaryButtonBackgroundColorColorColor(0xFF3B82F6)Background color for the primary button (e.g., "Continue" or "Capture").
secondaryButtonColorColorColor(0xFF6B7280)Color for secondary or less prominent buttons.
appFontColorColorColor.WhiteDefault font color used across the screen.
appBackgroundColorColorColor(0xFF1F2937)Background color of the entire Selfie Capture screen.
overlayBackgroundColorColorColor(0x80000000)Semi-transparent overlay background color behind the oval frame.
ovalBorderColorColorColor(0xFFFFFFFF)Border color of the oval frame.
instructionTextString"Lütfen yüzünüzü oval çerçeve içine yerleştirin"Instruction text shown to the user.
permissionDeniedTitleString"İzinler Gerekli"Title displayed in the permission denied dialog.
permissionDeniedMessageString"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.
retryButtonTextString"Tekrar Dene"Text for the retry button.
settingsButtonTextString"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 NameTypeDefault ValueDescription
pinLengthInt4Number of digits for the PIN.
titleString"Enter PIN"Title text displayed on the screen.
subtitleString"Please enter your security PIN"Subtitle or instruction text for the user.
backgroundColorColorColor(0xFFFFFFFF)Background color of the PIN screen.
titleColorColorColor(0xFF111827)Color of the title text.
subtitleColorColorColor(0xFF4B5563)Color of the subtitle text.
pinDotFilledColorColorColor(0xFF000000)Color of a filled PIN dot.
pinDotEmptyColorColorColor(0xFFD1D5DB)Color of an empty PIN dot.
keypadButtonBackgroundColorColorColor(0xFFF3F4F6)Background color of keypad buttons.
keypadButtonNumberColorColorColor(0xFF111827)Color of numbers on keypad buttons.
keypadButtonBorderColorColorColor(0xFF9CA3AF)Border color of keypad buttons.
deleteButtonContentColorColorColor(0xFFB41919)Color of the delete button icon or text.
deleteButtonBackgroundColorColorColor(0xFFF3F4F6)Background color of the delete button.
deleteButtonBorderColorColorColor(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}")
}
}
)