Getting Started

This guide will help you install and get started with Unforgettable SDK.

Requirements

Web / React / React Native

• Node.js 18+ or modern browser with Web Crypto API support
• TypeScript 5.0+ (optional but recommended)

Android

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

iOS

• iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+
• Swift 5.9+
• Xcode 15.0+

Installation

Choose your platform and install the SDK:

Web / JavaScript / TypeScript

npm

npm install @rarimo/unforgettable-sdk

yarn

yarn add @rarimo/unforgettable-sdk

pnpm

pnpm add @rarimo/unforgettable-sdk

React

npm

npm install @rarimo/unforgettable-sdk-react

yarn

yarn add @rarimo/unforgettable-sdk-react

pnpm

pnpm add @rarimo/unforgettable-sdk-react

React Native

npm

npm install @rarimo/unforgettable-sdk

yarn

yarn add @rarimo/unforgettable-sdk

Android

Gradle (Kotlin)

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

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

Gradle (Groovy)

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

dependencies {
    implementation 'com.github.rarimo.unforgettable-sdk:android:0.8.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>0.8.0</version>
</dependency>

Permissions: Add to AndroidManifest.xml:

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

iOS

Swift Package Manager:

Add the package dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/rarimo/unforgettable-sdk", from: "0.8.0")
]

Or add via Xcode:

1. File → Add Package Dependencies
2. Enter: https://github.com/rarimo/unforgettable-sdk
3. Select version 0.8.0+

Quick Start

Let's create a simple recovery flow where users can set up a new private key.

Step 1: Initialize the SDK

Web / JavaScript / TypeScript

import { UnforgettableSdk, RecoveryFactor } from '@rarimo/unforgettable-sdk'

const sdk = new UnforgettableSdk({
  mode: 'create',
  factors: [RecoveryFactor.Face, RecoveryFactor.Image, RecoveryFactor.Password],
})

React

import UnforgettableQrCode from '@rarimo/unforgettable-sdk-react'
import { RecoveryFactor } from '@rarimo/unforgettable-sdk'

function App() {
  const handleSuccess = (privateKey: string) => {
    console.log('Recovery successful!', privateKey)
  }

  return (
    <UnforgettableQrCode
      mode="create"
      factors={[RecoveryFactor.Face, RecoveryFactor.Image, RecoveryFactor.Password]}
      onSuccess={handleSuccess}
    />
  )
}

Android

import com.rarimo.unforgettable.UnforgettableSDK
import com.rarimo.unforgettable.UnforgettableSdkOptions
import com.rarimo.unforgettable.UnforgettableMode
import com.rarimo.unforgettable.RecoveryFactor

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

iOS

import UnforgettableSDK

let sdk = UnforgettableSDK(
    mode: .create,
    factors: [.face, .image, .password]
)

Step 2: Generate Recovery URL

Web / JavaScript / TypeScript

const recoveryUrl = await sdk.getRecoveryUrl()
console.log('Recovery URL:', recoveryUrl)
// Display this as a QR code for users to scan

React

The UnforgettableQrCode component handles this automatically! It generates the URL and displays it as a QR code.

Android

val recoveryUrl = sdk.getRecoveryUrl()
// Load this URL in a WebView
webView.loadUrl(recoveryUrl)

iOS

let recoveryUrl = try await sdk.getRecoveryUrl()
// Load this URL in a WKWebView
if let url = URL(string: recoveryUrl) {
    webView.load(URLRequest(url: url))
}

Step 3: Poll for Recovered Key

Web / JavaScript / TypeScript

import { NotFoundError } from '@rarimo/unforgettable-sdk'

async function pollForKey() {
  const maxAttempts = 60
  let attempts = 0

  while (attempts < maxAttempts) {
    try {
      const recoveryKey = await sdk.getRecoveredKey()
      console.log('✅ Recovery successful!', recoveryKey)
      return recoveryKey
    } catch (error) {
      if (error instanceof NotFoundError) {
        attempts++
        await new Promise(resolve => setTimeout(resolve, 3000))
      } else {
        throw error
      }
    }
  }
  
  throw new Error('Recovery timeout')
}

pollForKey()

React

The UnforgettableQrCode component handles polling automatically! Just provide an onSuccess callback.

Android

import kotlinx.coroutines.delay

suspend fun pollForKey(): String {
    val maxAttempts = 60
    var attempts = 0
    
    while (attempts < maxAttempts) {
        try {
            return sdk.getRecoveredKey()
        } catch (e: UnforgettableSDKError.NotFound) {
            attempts++
            delay(3000)
        }
    }
    
    throw Exception("Recovery timeout")
}

iOS

func pollForKey() async throws -> String {
    let maxAttempts = 60
    var attempts = 0
    
    while attempts < maxAttempts {
        do {
            return try await sdk.getRecoveredKey()
        } catch UnforgettableSDKError.notFound {
            attempts += 1
            try await Task.sleep(nanoseconds: 3_000_000_000)
        }
    }
    
    throw NSError(domain: "Recovery", code: -1, 
                  userInfo: [NSLocalizedDescriptionKey: "Recovery timeout"])
}

Next Steps

Explore platform-specific guides for detailed examples and advanced features:

• Web - QR code implementation for browsers
• React - Hooks and components
• React Native - WebView integration
• Android - Native Android implementation
• iOS - Native iOS implementation

Key Concepts

Before diving deeper, understand these core concepts:

• Mode: Either create (for setting up a new key) or restore (for recovering an existing key)
• Recovery Factors: The methods users can choose to create/restore their key (Face, Image, Password)
• Recovery URL: A secure link that users scan/open to complete the recovery process
• Data Transfer: The encrypted communication between your app and Unforgettable.app
• QR Code (Web): Web apps display QR codes for users to scan with mobile devices
• WebView (Mobile): Mobile apps open the recovery URL in a WebView for in-app recovery