eKYC Biometric SDK Integration Guide

eKYC Biometric SDK Integration Guide Complete implementation guide for Android applications

Table of Contents

Prerequisites

Step 1: Add the SDK to Your Project

Step 2: Initialize the SDK

Step 3: Advanced Usage

Step 4: Integration in Activity/Fragment

Step 5: Testing and Troubleshooting

Configuration Options

Security Notes

Prerequisites

Android API Level 24 (Android 7.0) or higher

Java 8 or higher

Android Studio 4.0 or higher

Valid eKYC credentials (Client ID and Client Secret)

¹ Add the SDK to Your Project

1.1 Add the AAR File

Create a libs folder in your app module directory and copy the provided AAR file:

your-app/ 
├── src/ 
├── libs/ // Create this folder 
│ └── remote-release.aar 
└── build.gradle

1.2 Update Module-level build.gradle

android {

compileSdk 35

defaultConfig {

minSdk 24

targetSdk 34

}

compileOptions {

sourceCompatibility JavaVersion.VERSION_1_8

targetCompatibility JavaVersion.VERSION_1_8

}

}

dependencies {

// Add the SDK AAR

implementation files('libs/remote-release.aar')

// Required dependencies

implementation 'androidx.appcompat:appcompat:1.6.1'

implementation 'com.google.android.material:material:1.9.0'

// JSON parsing

implementation 'com.google.code.gson:gson:2.10.1'

implementation 'io.gsonfire:gson-fire:1.8.0'

// HTTP client

implementation 'com.squareup.retrofit2:retrofit:2.9.0' implementation 'com.squareup.retrofit2:converter-gson:2.9.0' implementation 'com.squareup.okhttp3:okhttp:4.12.0'

implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'

// Legacy WebSocket support

implementation 'org.java-websocket:Java-WebSocket:1.5.1'

// Security/Cryptography

implementation 'org.bouncycastle:bcprov-jdk15to18:1.73' implementation 'org.bouncycastle:bcpkix-jdk15to18:1.73'

// Coroutines for async operations

implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7

// Date/time utilities

implementation 'org.threeten:threetenbp:1.3.5'

// Swagger annotations

implementation 'io.swagger:swagger-annotations:1.5.18' }

1.3 Update Permissions

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" /> 
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" / >
 <uses-permission android:name="android.permission.WAKE_LOCK" /> 

² Initialize the SDK

2.1 Basic Setup

Create a service class to manage the Remote Biometric SDK:

import ke.go.ecitizen.remote.api.EKYCRemoteBiometrics; 
import ke.go.ecitizen.remote.config.RemoteBiometricConfig; import ke.go.ecitizen.remote.models.BiometricDevice; 
import ke.go.ecitizen.remote.models.BiometricCaptureResult; 
public class BiometricService { 
 private static final String TAG = "BiometricService"; 
 // Your eCitizen credentials 
 private static final String CLIENT_ID = "your_client_id";  private static final String CLIENT_SECRET = "your_client_secret";  private static final String SERVER_URL = "https://test.ekyc.pesaflow 
 private EKYCRemoteBiometrics remoteBiometrics; 
 private Context context; 
 public BiometricService(Context context) { 
this.context = context; 
this.remoteBiometrics = EKYCRemoteBiometrics.getInstance();  } 
 public void initializeService() { 
 // Create configuration 
RemoteBiometricConfig config = new RemoteBiometricConfig.Builder( .setClientId(CLIENT_ID) 
.setClientSecret(CLIENT_SECRET) 
.setServerUrl(SERVER_URL) 
.setEnvironment(RemoteBiometricConfig.Environment.DEVELOPMENT .build();
 // Initialize the service 
remoteBiometrics.initialize( 
context, 
config, 
createDeviceProvider(), 
createCaptureProvider(), 
createEventListener() 
).thenCompose(v -> { 
// Start the service with your workstation ID 
return remoteBiometrics.startService("YOUR_WORKSTATION_ID"); }).thenRun(() -> { 
Log.i(TAG, "Remote biometric service started successfully"); }).exceptionally(throwable -> { 
Log.e(TAG, "Failed to start service", throwable); 
return null; 
}); 
 } 
} 

2.2 Implement Device Provider

The Device Provider manages your connected biometric devices:

private EKYCRemoteBiometrics.DeviceProvider createDeviceProvider() {  return new EKYCRemoteBiometrics.DeviceProvider() { 
@Override 
public List<BiometricDevice> getConnectedDevices() { 
// Return your actual connected devices 
List<BiometricDevice> devices = new ArrayList<>(); 
// Example: Add your fingerprint scanners 
devices.add(new BiometricDevice("scanner1", "SecuGen Hamster  devices.add(new BiometricDevice("scanner2", "DigitalPersona U 
return devices; 
} 
@Override 
public void onDeviceStatusChanged(String deviceId, boolean isConn Log.i(TAG, "Device " + deviceId + " status: " + (isConnected  // Handle device status changes 
} 
 }; 
} 

2.3 Implement Capture Provider

The Capture Provider handles biometric data capture:

private EKYCRemoteBiometrics.CaptureProvider createCaptureProvider() {  return new EKYCRemoteBiometrics.CaptureProvider() { 
@Override 
public CompletableFuture<String> captureFromDevice(String deviceI Log.i(TAG, "Capturing from device: " + deviceId); 
return CompletableFuture.supplyAsync(() -> { 
try { 
// Implement your actual biometric capture logic here 
// This should interface with your biometric device S 
// Example for fingerprint capture: 
byte[] fingerprintData = captureFingerprint(deviceId) 
// Convert to Base64 string as required by the SDK 
return Base64.encodeToString(fingerprintData, Base64 
} catch (Exception e) { 
throw new RuntimeException("Capture failed: " + e.get 
} 
}); 
} 
@Override 
public void onCaptureStarted(String deviceId) { 
Log.i(TAG, "Capture started on device: " + deviceId); 
// Show UI feedback to user 
} 
@Override 
public void onCaptureCompleted(String deviceId, String captureDat Log.i(TAG, "Capture completed on device: " + deviceId); 
// Hide capture UI, show success 
} 
@Override 
public void onCaptureFailed(String deviceId, String error) { Log.e(TAG, "Capture failed on device: " + deviceId + ", erro // Show error message to user 
} 
 }; 
} 
// Example method - implement based on your biometric device SDK private byte[] captureFingerprint(String deviceId) { 
 // Your biometric device integration code here 
 // Return the raw biometric data as byte array 
 throw new UnsupportedOperationException("Implement based on your biom } 

2.4 Implement Event Listener

The Event Listener handles SDK events and status updates:

private EKYCRemoteBiometrics.BiometricEventListener createEventListener()  return new EKYCRemoteBiometrics.BiometricEventListener() { @Override 
public void onServiceConnected() { 
Log.i(TAG, "✅ Remote biometric service connected"); 
// Update UI to show service is ready 
} 
@Override 
public void onServiceError(String error) { 
Log.e(TAG, "❌ Service error: " + error); 
// Show error message to user 
} 
@Override 
public void onDevicesReceived(List<BiometricDevice> devices) { Log.i(TAG, "�� Received " + devices.size() + " devices"); // Update device list in UI 
} 
@Override 
public void onCaptureRequested(String deviceId, String requestId) Log.i(TAG, "�� Capture requested for device: " + deviceId); // Start capture process for the specified device 
} 
@Override 
public void onCaptureResultSent(BiometricCaptureResult result) { Log.i(TAG, "�� Capture result sent successfully"); 
// Show success message 
} 
@Override 
public void onServiceRecovering(String reason) { 
Log.w(TAG, "�� Service recovering: " + reason); 
// Show recovery status to user 
} 
@Override 
public void onServiceDegraded(String reason) { 
Log.w(TAG, "⚠️ Service degraded: " + reason); 
// Inform user of limited functionality 
} 
@Override 
public void onServiceRecovered() { 
Log.i(TAG, "✅ Service fully recovered"); 
// Update UI to show full functionality restored 
}
@Override 
public void onServiceDegradationChanged(String level, String mess Log.w(TAG, "�� Degradation level: " + level + " - " + message handleDegradationLevel(level, message); 
} 
@Override 
public void onLocalFallbackRecommended(String operation, String Log.i(TAG, "�� Use local fallback for: " + operation); 
handleLocalFallback(operation, reason); 
} 
 }; 
} 

³ Advanced Usage

3.1 Handle Service Degradation

private void handleDegradationLevel(String level, String message) {  switch (level) { 
case "none": 
// Full functionality available 
showStatusMessage("✅ Service fully operational"); 
break; 
case "partial": 
// Some features may be slower 
showStatusMessage("⚠️ Service running with minor limitations break; 
case "significant": 
// Reduced functionality 
showStatusMessage("⚠️ Service running with significant limita break; 
case "complete": 
// Use local fallback only 
showStatusMessage("❌ Remote service unavailable - using loca break; 
 } 
} 
private void handleLocalFallback(String operation, String reason) {  if (remoteBiometrics.shouldUseFallback(operation)) { 
Log.i(TAG, "Using local fallback for: " + operation); 
 // Implement local-only operation
 } 
} 

3.2 Monitor Service Status

public void checkServiceStatus() { 
 if (remoteBiometrics.isServiceRunning()) { 
String status = remoteBiometrics.getServiceStatus(); 
Log.i(TAG, "Service Status: " + status); 
if (remoteBiometrics.isRecovering()) { 
Log.i(TAG, "Recovery State: " + remoteBiometrics.getRecoveryS Log.i(TAG, "Recovery Attempts: " + remoteBiometrics.getRecove } 
if (remoteBiometrics.isDegraded()) { 
Log.i(TAG, "Degradation Level: " + remoteBiometrics.getDegrad Log.i(TAG, "Degradation Message: " + remoteBiometrics.getDeg } 
 } 
} 

3.3 Proper Cleanup

public void stopService() { 
 if (remoteBiometrics != null && remoteBiometrics.isServiceRunning())  remoteBiometrics.stopService(); 
Log.i(TAG, "Remote biometric service stopped"); 
 } 
} 
// Call this in your Activity/Service onDestroy() 
@Override 
protected void onDestroy() { 
 super.onDestroy(); 
 stopService(); 
} 

⁴ Integration in Activity/Fragment

4.1 Basic Activity Integration

public class MainActivity extends AppCompatActivity {  private BiometricService biometricService; 
 @Override 
 protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); 
setContentView(R.layout.activity_main); 
 // Initialize biometric service 
biometricService = new BiometricService(this); 
biometricService.initializeService(); 
 } 
 @Override 
 protected void onDestroy() { 
super.onDestroy(); 
if (biometricService != null) { 
biometricService.stopService(); 
} 
 } 
} 

⁵ Testing and Troubleshooting

5.1 Enable Debug Logging

RemoteBiometricConfig config = new RemoteBiometricConfig.Builder()  .setClientId(CLIENT_ID) 
 .setClientSecret(CLIENT_SECRET) 
 .setServerUrl(SERVER_URL) 
 .build(); 

5.2 Common Issues

Network Connectivity: Ensure device has internet access Credentials: Verify Client ID and Client Secret are correct Device Integration: Make sure your biometric device SDK is properly integrated

Permissions: Check that all required permissions are granted

5.3 Error Handling

// Check service status regularly

// Check service status regularly 
private void monitorService() { 
 Handler handler = new Handler(Looper.getMainLooper());  Runnable statusChecker = new Runnable() { 
@Override 
public void run() { 
if (remoteBiometrics.isServiceRunning()) { 
// Service is healthy 
updateServiceStatusUI("Connected"); 
} else { 
// Service may need restart 
updateServiceStatusUI("Disconnected"); 
} 
handler.postDelayed(this, 30000); // Check every 30 seconds } 
 }; 
 handler.post(statusChecker); 
} 

Configuration Options

Environment Settings

// Development Environment 
.setEnvironment(RemoteBiometricConfig.Environment.DEVELOPMENT) .setServerUrl("https://test.ekyc.pesaflow.com") 
// Production Environment  
.setEnvironment(RemoteBiometricConfig.Environment.PRODUCTION) .setServerUrl("https://ekyc.pesaflow.com")

Support

For technical support and questions:

Check the SDK logs for detailed error information Ensure all dependencies are properly included Verify network connectivity and credentials

eKYC Biometric SDK Integration Guide