Android SDK

Maven Central (Recommended)

Add the SDK to your build.gradle.kts file. The SDK is published to Maven Central, so ensure you have the repository configured:

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.keverd:sdk:1.0.0")
}

AAR File (Alternative)

If you prefer to use a local AAR file, download it and add it to your project's libs directory (typically located at app/libs/). Then add the following dependencies:

Note: The SDK requires several dependencies. When using the AAR file, you must include all required dependencies manually. The SDK uses Retrofit for networking, Kotlin Coroutines for asynchronous operations, and Gson for JSON serialization.

dependencies {
    implementation(files("libs/keverd-sdk.aar"))
    
    // Required dependencies
    implementation("androidx.core:core-ktx:1.10.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    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.google.code.gson:gson:2.10.1")
}

Permissions

Add these permissions to your AndroidManifest.xml file. These permissions are required for the SDK to collect device and network information:

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

1. Initialize the SDK

Initialize the SDK in your Application class. This ensures the SDK is initialized once when your app starts, following the singleton pattern. The SDK uses the application context internally to prevent memory leaks.

Important: The apiBaseUrl must use HTTPS. The SDK will throw an IllegalArgumentException if you provide an HTTP URL. The default API endpoint is https://api.keverd.com.

import com.keverd.sdk.Config
import com.keverd.sdk.KeverdFingerprint

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        val config = Config(
            apiBaseUrl = "https://api.keverd.com",
            apiKey = "your-api-key-here",
            consentRequired = true
        )
        
        KeverdFingerprint.init(this, config)
    }
}

2. Request Consent (if required)

If consentRequired is set to true in your configuration (which is the default), you must obtain explicit user consent before data collection can proceed. This is important for GDPR, CCPA, and other privacy regulations.

How it works: When you call submit() without consent, the SDK will return Result.ConsentRequired. You should then show a consent dialog to the user. Once consent is granted, call setConsent(true) and then retry the submission.

val sdk = KeverdFingerprint.init(context, config)

// Show consent dialog to user
showConsentDialog { granted ->
    sdk.setConsent(granted)
    
    if (granted) {
        submitFingerprint(userId)
    }
}

3. Submit Fingerprint

Submit fingerprint data and receive a risk score. The submit() method is a suspend function, so it must be called from a coroutine scope (typically lifecycleScope in Activities or viewModelScope in ViewModels).

Threading: Data collection and network calls run on Dispatchers.IO to avoid blocking the main thread. The callback (onResult) is automatically switched to Dispatchers.Main, so you can safely update the UI from within the callback.

Performance: Data collection typically completes in under 50ms, and the total time (including network request) is typically under 100ms. The SDK uses connection, read, and write timeouts of 30 seconds each.

import kotlinx.coroutines.launch

fun submitFingerprint(userId: String) {
    val sdk = KeverdFingerprint.init(context, config)
    
    lifecycleScope.launch {
        sdk.submit(userId) { result ->
            when (result) {
                is Result.Success -> {
                    val riskScore = result.score
                    val requestId = result.requestId
                    
                    // Handle success
                    if (riskScore > 0.7) {
                        showSecurityAlert()
                    } else {
                        proceedWithTransaction()
                    }
                }
                
                is Result.Error -> {
                    Log.e("KeverdSDK", "Error: \${result.error}", result.throwable)
                    showError(result.error)
                }
                
                is Result.ConsentRequired -> {
                    requestUserConsent()
                }
            }
        }
    }
}

Network Errors

Network errors occur when the device cannot connect to the API or when the request times out. The SDK uses 30-second timeouts for connection, read, and write operations.

is Result.Error -> {
    when {
        result.error.contains("timeout", ignoreCase = true) -> {
            // Handle timeout - retry with exponential backoff
            retryWithBackoff()
        }
        result.error.contains("network", ignoreCase = true) -> {
            // Handle network connectivity issues
            showNetworkError()
        }
        else -> {
            // Handle other network errors
            Log.e("KeverdSDK", "Network error: \${result.error}", result.throwable)
        }
    }
}

API Errors

API errors occur when the server returns an error response (4xx or 5xx status codes). Common API errors include invalid API key, rate limiting, and server errors.

is Result.Error -> {
    when {
        result.error.contains("401", ignoreCase = true) || 
        result.error.contains("unauthorized", ignoreCase = true) -> {
            // Invalid or expired API key
            Log.e("KeverdSDK", "API key error: \${result.error}")
            // Prompt user to check API key configuration
        }
        result.error.contains("429", ignoreCase = true) || 
        result.error.contains("rate limit", ignoreCase = true) -> {
            // Rate limit exceeded
            Log.w("KeverdSDK", "Rate limit exceeded: \${result.error}")
            // Implement exponential backoff
        }
        result.error.contains("500", ignoreCase = true) -> {
            // Server error - retry after delay
            Log.e("KeverdSDK", "Server error: \${result.error}")
            retryAfterDelay()
        }
        else -> {
            Log.e("KeverdSDK", "API error: \${result.error}", result.throwable)
        }
    }
}

Data Collection Errors

Data collection errors can occur if required permissions are missing or if there's an issue accessing device information. The SDK handles these gracefully and continues with available data.

is Result.Error -> {
    if (result.error.contains("permission", ignoreCase = true)) {
        // Missing required permission
        requestMissingPermission()
    } else {
        // Other data collection errors
        Log.e("KeverdSDK", "Collection error: \${result.error}", result.throwable)
        // SDK will still attempt to submit with available data
    }
}

Best Practices

• Always check the error message and handle different error types appropriately
• Log errors with the throwable for debugging purposes
• Implement retry logic with exponential backoff for transient errors (network, 5xx)
• Don't retry on client errors (4xx) unless the error message indicates it's safe to do so
• Show user-friendly error messages for network and permission errors
• Monitor error rates and patterns to identify issues early

Initialization

• Initialize the SDK in your Application class's onCreate() method
• Use the application context, not an activity context, to prevent memory leaks
• Store your API key securely (e.g., in BuildConfig, environment variables, or a secure storage solution)
• Never commit API keys to version control
• Use different API keys for development, staging, and production environments

Consent Management

• Always request consent before data collection if consentRequired is true
• Show a clear, user-friendly consent dialog explaining what data is collected and why
• Respect user's choice - if consent is declined, do not attempt to collect data
• Store consent status if needed for future sessions (the SDK does not persist consent across app restarts)
• Allow users to revoke consent at any time by calling setConsent(false)

Permission Handling

• Request READ_PHONE_STATE permission at runtime on Android 6.0+
• Explain why the permission is needed before requesting it
• Handle permission denial gracefully - the SDK will still work without SIM data
• Check permission status before calling submit() if SIM data is critical for your use case

Risk Score Usage

• Use risk scores to make security decisions, not as the sole factor
• Combine risk scores with other signals (e.g., login history, device trust, user behavior)
• Implement graduated security measures based on risk levels (0-29: allow, 30-49: soft challenge, 50-69: hard challenge, 70-100: block)
• Log risk scores and decisions for auditing and analysis
• Monitor risk score distributions to identify anomalies or issues
• Use the requestId to correlate events and debug issues

Performance

• Call submit() from a coroutine scope (lifecycleScope or viewModelScope)
• Don't block the main thread - the SDK handles threading automatically
• Avoid calling submit() too frequently (e.g., on every screen transition)
• Consider caching risk scores for a short period to avoid redundant API calls
• Implement retry logic with exponential backoff for failed requests

Security

• Always use HTTPS for API endpoints (enforced by the SDK)
• Store API keys securely and never expose them in client-side code if possible
• Use ProGuard or R8 to obfuscate your code and protect API keys
• Monitor API key usage and rotate keys regularly
• Implement certificate pinning if required by your security policy
• Review and update dependencies regularly for security patches