Developer documentation

// settings.gradle.kts  ← repositories go HERE in modern Android projects
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/m2") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("ng.facededup:facededup:0.6.0")
}
// then: Android Studio → File → Sync Project with Gradle Files

// 1) Download the AAR (no auth):
//    https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/sdk/facededup-0.6.0.aar
// 2) Drop it in your app module's libs/ folder, then:
dependencies {
    implementation(files("libs/facededup-0.6.0.aar"))
    // AAR via files() carries no transitive deps — add them explicitly:
    implementation("androidx.core:core-ktx:1.13.1")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

// If you have the repo checked out as part of your Gradle build:
// settings.gradle.kts
include(":facededup")
project(":facededup").projectDir = file("path/to/facededup-liveliness/sdk/android/facededup")

// app/build.gradle.kts
dependencies { implementation(project(":facededup")) }

import ng.facededup.sdk.FacededupConfig
import ng.facededup.sdk.FacededupContract

// register in onCreate / as a class field
private val verify = registerForActivityResult(FacededupContract()) { r ->
    when {
        r == null   -> { /* user cancelled */ }
        r.passed   -> { /* verified: r.outcome / r.score / r.enrollmentId */ }
        else       -> { /* not verified: show r.outcome */ }
    }
}

// launch it — for a bank app, start STRAIGHT at the camera (no menu)
verify.launch(FacededupConfig(
    baseUrl  = "https://facededup.ai",
    password = "…",            // demo gate; swap for API key/session token in prod
    subjectId = "user-123",
    flow     = "liveness",    // camera-only liveness; omit/"select" to show the menu
    showSettings = false,     // hide the in-flow tester panel in production
))

// read the captured images off the result (for your own compare/storage)
val selfie = r.selfieImage?.image          // base64 JPEG, or null
val frames = r.livelinessImages            // List<FacededupImage> (4–8)

// In your app's Package.swift — point a binaryTarget straight at S3.
// No git URL, no token: SPM downloads the zip and verifies the checksum.
targets: [
    .binaryTarget(
        name: "FacededupLiveness",
        url: "https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/sdk/ios/FacededupLiveness-0.5.0.xcframework.zip",
        checksum: "700b13242960f45def6beca31547533fe67780a762ecb44b343ef8dffcf1a55c"
    ),
    .target(name: "YourApp", dependencies: ["FacededupLiveness"]),
]

// 1) Download + unzip (no auth):
//    https://swiftend-assets-348761024048.s3.eu-west-2.amazonaws.com/sdk/ios/FacededupLiveness-0.5.0.xcframework.zip
// 2) Drag FacededupLiveness.xcframework into your Xcode project.
// 3) Target ▸ General ▸ Frameworks, Libraries & Embedded Content →
//    set FacededupLiveness.xcframework to "Embed & Sign".
// That's it — no SPM, no CocoaPods, no GitHub.

import FacededupLiveness

let vc = FacededupVerificationController(config: .init(
    baseURL: URL(string: "https://facededup.ai")!,
    password: "…",            // demo gate; swap for API key/session token in prod
    subjectId: "user-123"
)) { result in
    if result.passed {
        // verified — result.outcome / result.score / result.enrollmentId
    } else {
        // not verified — show result.outcome
    }
}
present(vc, animated: true)

// Capture the session on-device and keep the frames — no submit yet.
// Equivalent to "skip API submission": returns the captured payload.
verify.launch(FacededupConfig(
    baseUrl   = "https://facededup.ai",
    subjectId = "user-123",
    offlineMode = true,        // capture & store, don't submit
))
// result.passed is null while offline; result.raw holds the stored job id.

// Later, when the device is back online — submit the stored frames to the
// same /v1/verify endpoint. Server scores it; you get the signed result.
curl -u :PASSWORD -X POST https://facededup.ai/v1/verify   -H "Content-Type: application/json"   -d @stored-job.json
// → { "outcome": "live", "score": 0.95, "result_token": "…" }

{
  "subject_id": "user-123",
  "purpose": "nin_token_issuance_liveness",
  "lawful_basis": "consent",
  "channel": "web",
  "accepted": true
}

{ "consent_id": "cn_a1b2c3", "accepted": true, "recorded_at": "2026-06-13T12:00:00Z" }

{
  "subject_id": "user-123",
  "consent_id": "cn_a1b2c3",
  "method": "face_liveness",
  "risk_level": "baseline",
  "tenant_id": "harrys-living"
}

{ "request_id": "rq_77f0", "method": "face_liveness", "risk_level": "baseline" }

{ "request_id": "rq_77f0" }

{
  "session_id": "se_4d2",
  "nonce": "Yk3…q9",
  "actions": ["blink", "turn_left", "smile"],
  "method": "face_liveness",
  "expires_at": "2026-06-13T12:00:20Z"
}

{
  "request_id": "rq_77f0",
  "session_id": "se_4d2",
  "nonce": "Yk3…q9",
  "frames": [
    { "image_b64": "<jpeg>", "proves_action": "blink" },
    { "image_b64": "<jpeg>", "proves_action": null }
  ],
  "audio_present": false
}

{
  "decision_id": "dc_9a1",
  "outcome": "live",            // live · referred · not_live
  "score": 0.95,
  "threshold": 0.6,
  "result_token": "<ed25519-signed, 120s TTL>",
  "checks": [ { "name": "active_challenge", "passed": true } ]
}

{
  "id_type": "nin",             // "nin" | "bvn"
  "id_number": "12345678901",
  "selfie_b64": "<jpeg>",
  "result_token": "<from /v1/verify>"
}

{
  "found": true, "decision": "match", "match_score": 92.4,
  "full_name": "Ada N.", "date_of_birth": "1991-04-17",
  "id_number_masked": "*******8901", "source": "NIMC",
  "authority_photo_b64": "<jpeg>", "spoof": false
}

{ "selfie_b64": "<jpeg>", "result_token": "<from /v1/verify>" }

{ "mrz": "P<NGAADA<<…\nL898902C36NGA9001…" }

{
  "mrz": "P<NGA…",
  "document_photo_b64": "<id photo jpeg>",
  "selfie_b64": "<live selfie jpeg>",
  "chip_verified": false,
  "result_token": "<from /v1/verify>"
}

{
  "address": "12 Marina St, Lagos Island, Lagos",
  "lat": 6.4541, "lon": 3.3947,   // device GPS at the location
  "accuracy_m": 12,
  "subject_id": "user-123"
}

{
  "decision": "match",            // match · refer · no_match · not_found
  "formatted": "12 Marina St, Lagos Island…",
  "distance_m": 38.4,
  "match_radius_m": 150,
  "geocode": { "lat": 6.4538, "lon": 3.3949, "source": "google" },
  "decision_id": "…"
}

{ "selfie_b64": "<jpeg>", "subject_id": "user-123", "country": "NG" }

{ "token": "<result_token>" }   // 200 = valid & first use; 409 = already redeemed