android

Unforgettable SDK for Android

A Kotlin library for integrating Unforgettable account recovery into your Android applications.

Installation

Gradle (Kotlin DSL)

Add JitPack repository and dependency to your build.gradle.kts:

repositories {
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.rarimo.unforgettable-sdk:android:1.0.0")
}

Gradle (Groovy)

Add to your build.gradle:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.rarimo.unforgettable-sdk:android:1.0.0'
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.rarimo.unforgettable-sdk</groupId>
    <artifactId>android</artifactId>
    <version>1.0.0</version>
</dependency>

Usage

Creating a Recovery URL

import com.rarimo.unforgettable.*

val sdk = UnforgettableSDK(
    UnforgettableSdkOptions(
        mode = UnforgettableMode.CREATE,
        factors = listOf(RecoveryFactor.FACE, RecoveryFactor.IMAGE, RecoveryFactor.PASSWORD),
        walletAddress = "0x1234567890abcdef",
        group = "my-organization", // Optional
        customParams = mapOf("theme" to "dark", "lang" to "en") // Optional
    )
)

val recoveryUrl = sdk.getRecoveryUrl()
println("Recovery URL: $recoveryUrl")

Restoring an Account

import com.rarimo.unforgettable.*
import kotlinx.coroutines.*

val sdk = UnforgettableSDK(
    UnforgettableSdkOptions(
        mode = UnforgettableMode.RESTORE,
        factors = listOf(RecoveryFactor.FACE, RecoveryFactor.PASSWORD)
    )
)

val recoveryUrl = sdk.getRecoveryUrl()

// After the user completes the recovery process...
lifecycleScope.launch {
    try {
        val recoveredData = sdk.getRecoveredData()
        println("Recovery Key: ${recoveredData.recoveryKey}")
    } catch (e: UnforgettableSDKError) {
        println("Error during recovery: $e")
    }
}

Available Recovery Factors

enum class RecoveryFactor(val value: Int) {
    FACE(1),
    IMAGE(2),
    PASSWORD(3),
    GEOLOCATION(4)
}

API

UnforgettableSDK

The main SDK class.

Initialization

UnforgettableSDK(options: UnforgettableSdkOptions)

Parameters:

• options: Configuration options for the SDK

Methods

getRecoveryUrl()

Generates the recovery URL to present to the user.

fun getRecoveryUrl(): String

Returns: The recovery URL as a string

getRecoveredData()

Retrieves the recovered data from the API (suspending function).

suspend fun getRecoveredData(): RecoveredData

Returns: The recovered data including the recovery key

Throws: UnforgettableSDKError on failure

getRecoveredKey()

Retrieves only the recovered key (suspending function).

suspend fun getRecoveredKey(): String

Returns: The recovered key as a string

Throws: UnforgettableSDKError on failure

UnforgettableSdkOptions

Configuration options for the SDK.

data class UnforgettableSdkOptions(
    val mode: UnforgettableMode,
    val appUrl: String = UNFORGETTABLE_APP_URL,
    val apiUrl: String = UNFORGETTABLE_API_URL,
    val factors: List<RecoveryFactor> = emptyList(),
    val walletAddress: String? = null,
    val group: String? = null,
    val customParams: Map<String, String>? = null
)

Parameters:

• mode: Either UnforgettableMode.CREATE or UnforgettableMode.RESTORE
• appUrl: The Unforgettable app URL (default: https://unforgettable.app)
• apiUrl: The Unforgettable API URL (default: https://api.unforgettable.app)
• factors: Optional list of recovery factors to use
• walletAddress: Optional wallet address to associate with the recovery
• group: Optional group identifier for organizing recovery keys
• customParams: Optional custom URL parameters to pass to the recovery app

Error Types

CryptoError

Errors related to cryptographic operations:

• KeyGenerationFailed
• EncryptionFailed
• DecryptionFailed
• InvalidPublicKey
• EncodingFailed
• DecodingFailed

UnforgettableSDKError

Errors related to SDK operations:

• NetworkError(cause: Throwable)
• InvalidResponse
• NotFound
• DecodingError(cause: Throwable)
• CryptoError(cause: Throwable)

LocationHashError

Errors related to URL hash parsing:

• InvalidParameters
• InvalidFactorId(factorId: String)
• NonIntegerFactor(factor: String)

Android Permissions

Add to your AndroidManifest.xml:

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

Requirements

• Android SDK 21+ (Android 5.0 Lollipop)
• Kotlin 1.9+
• Java 17+

ProGuard

If you use ProGuard, add these rules to your proguard-rules.pro:

# Keep SDK classes
-keep class com.rarimo.unforgettable.** { *; }

# Keep serialization classes
-keepclassmembers class com.rarimo.unforgettable.** {
    @kotlinx.serialization.* <fields>;
}

License

MIT License - see LICENSE file for details

Homepage

https://unforgettable.app