Android SDK 集成指南

概述

Width Identity SDK 爲 Android 應用提供即插即用的身份驗證流程。支持 KYC 和 KYB 工作流，包括證件採集、活體檢測與審覈。SDK 在獨立的 Activity 中運行；你只需添加一個依賴、調用一個入口，SDK 即返回單一結果。

系統要求

安裝

步驟 1：添加 Maven 倉庫

在 settings.gradle.kts 中。Width 倉庫提供 SDK 及其由 Width 託管的傳遞依賴（com.width.risksec、com.width.camera）；其餘依賴（AndroidX / Kotlin / Ktor / CameraX）從 Google + Maven Central 解析。

SDK 內置的證件採集引擎由各自的廠商託管，不在 Width 的 Maven 上，所以它們的倉庫也要加上 — 構建期必須有，哪怕某個採集商在你的流程裏用不到。下面兩個廠商倉庫塊請原樣照抄。

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://maven.width.com/repository/sdk-releases/") }
        google()
        mavenCentral()

        // Document-capture provider repository (bundled transitively; required to resolve)
        maven {
            url = uri("https://cdn.veriff.me/android/")
            content { includeGroup("com.veriff") }
        }
        // Document-reader provider repository (bundled transitively; required to resolve)
        maven {
            url = uri("https://maven-master.regulaforensics.com/RegulaDocumentReader/")
            content {
                includeGroup("com.regula.documentreader")
                includeGroup("com.regula.documentreader.core")
                includeGroup("com.regula.common")
            }
        }
    }
}

步驟 2：添加依賴

在應用級 build.gradle.kts 中。單個座標即可傳遞引入相機、活體及配套庫 — 無需 BOM，也無需額外座標。

dependencies {
    implementation("com.width.identity:sdk-activity:1.0.11")
}

步驟 3：必需的構建配置

下面兩項配置加在你自己的 App 模塊上，不是 SDK 側的事。不加，構建直接失敗 — 兩項都不需要改你的任何源碼。

必須開啓 core library desugaring（把新版 Java 標準庫的能力降級到舊 Android 版本上可用的編譯期處理）。內置的 AWS Rekognition 活體引擎帶的 Amplify AAR 在元數據裏聲明瞭 requires core library desugaring，AGP 會在 App 側強制校驗（checkReleaseAarMetadata / checkDebugAarMetadata），與你的 minSdk 是多少無關。在 App 模塊加上：

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

AGP 9 上必須加 android.uniquePackageNames=false。 AWS 活體引擎傳遞引入的兩個產物（com.google.ai.edge.litert:litert-support 與 litert-support-api，都是 1.4.1）聲明瞭同一個庫命名空間 org.tensorflow.lite.support — 這是上游的打包缺陷。AGP 9 的清單合併會校驗命名空間唯一性，衝突就以 Validation failed, exiting 中斷構建。在項目的 gradle.properties 里加上：

# gradle.properties
android.uniquePackageNames=false

快速開始

SDK 提供兩種等價的入口風格 — 按你的調用點選擇即可。兩者驅動完全相同的驗證界面，並返回單一結果。

直接輸入（ActivityResultContract）

import com.width.identity.activity.CredentialsConfig
import com.width.identity.activity.CustomerConfig
import com.width.identity.activity.ThemeConfig
import com.width.identity.activity.UILanguage
import com.width.identity.activity.Verification
import com.width.identity.activity.VerificationInput
import com.width.identity.activity.VerificationResult

class MainActivity : ComponentActivity() {

    private val launcher =
        registerForActivityResult(Verification()) { result ->
            when (result) {
                is VerificationResult.Completed ->   // .APPROVED / .REJECTED / .REVIEW
                    Log.i(TAG, "done: ${result.executionId} ${result.decision}")
                is VerificationResult.Waiting ->
                    Log.i(TAG, "waiting: ${result.executionId}")
                is VerificationResult.Dismissed ->
                    Log.i(TAG, "dismissed: ${result.executionId ?: "(no execution)"}")
                is VerificationResult.Cancelled ->
                    Log.i(TAG, "cancelled: ${result.executionId}")
                is VerificationResult.Failed ->
                    Log.w(TAG, "failed: ${result.code} ${result.message}")
            }
        }

    private fun startVerification() {
        val input = VerificationInput(
            credentials = CredentialsConfig(
                domain   = "YOUR_DOMAIN",
                sdkToken = "YOUR_SDK_TOKEN",
            ),
            customer = CustomerConfig(
                // Both customerId and email are required and must be non-blank.
                customerId = "user-123",
                email      = "user@example.com",
            ),
            theme = ThemeConfig(themeMode = "SYSTEM"),   // optional: "SYSTEM" / "LIGHT" / "DARK"
            eventType = "KYC_EVENT",   // optional: "KYC_EVENT" / "KYB_EVENT" to skip in-SDK selection; omit to let the user pick
            language = UILanguage.ZH,  // optional: UILanguage.EN (default) / .ZH; omit = English (does not follow device locale)
        )
        launcher.launch(input)
    }
}

Builder 入口（Compose）

鏈式構造器（fluent builder）把啓動所需的輸入串成一條鏈裝配起來 — 依次給出 access token、憑據、申請人，再按需掛上 handler，最後 build 並啓動，返回單一的 WIDTHCompletionResult。先用 WIDTHVerification 契約在 composition 中註冊 launcher，再在調用點構建並啓動。

import androidx.activity.compose.rememberLauncherForActivityResult
import com.width.identity.activity.WIDTHCompletionResult
import com.width.identity.activity.WIDTHDayNightMode
import com.width.identity.activity.WIDTHMobileSDK
import com.width.identity.activity.WIDTHVerification

@Composable
fun VerifyButton() {
    val launcher = rememberLauncherForActivityResult(WIDTHVerification()) { result ->
        when (result) {
            is WIDTHCompletionResult.SuccessTermination ->   // see status table
                Log.i(TAG, "done: ${result.status} ${result.executionId}")
            is WIDTHCompletionResult.AbnormalTermination ->
                Log.w(TAG, "failed: ${result.exception.code} ${result.exception.message}")
        }
    }

    Button(onClick = {
        WIDTHMobileSDK.Builder()
            .withAccessToken("YOUR_SDK_TOKEN")                 // RiskSec sdkToken (encodes appId/apiKey)
            .withCredentials(domain = "YOUR_DOMAIN")           // only domain is client-supplied
            .withApplicant(customerId = "user-123", email = "user@example.com")
            .withEventType("KYC_EVENT")                        // optional; "KYC_EVENT"/"KYB_EVENT" to skip in-SDK selection
            .withForcedDayNightMode(WIDTHDayNightMode.NIGHT)   // optional; omit to follow the system
            .withHandlers(onEvent = myLogger)                  // optional; see Event logging
            .withLauncher(launcher)
            .build()
            .launch()
    }) { Text("Verify") }
}

這只是另一種入口寫法，不是另一條啓動路徑：builder 在底層裝配出原生的 VerificationInput，跑的仍是同一套流程。withAccessToken 傳的就是 sdkToken，租戶的 appId / apiKey 已經編碼在這個 token 裏、由 SDK 在設備上解密；客戶端只需要通過 withCredentials 傳 domain，通過 withApplicant 傳申請人身份。

withEventType 可選（"KYC_EVENT" / "KYB_EVENT"）— 傳了就直接進入對應流程、跳過 SDK 內的選擇頁；不傳則由用戶自己選。

事件日誌（可選）

註冊一個 SdkEventLogger 即可將 SDK 生命週期事件（INFO / WARN / ERROR）接入你自己的管道（Crashlytics、Timber、DataDog 等）。回調觸發前已脫敏已知的 PII（個人身份信息）。SdkEventLogger 是函數式接口，任何需要它的位置都可以傳入 lambda。

import com.width.identity.activity.SdkLogLevel
import com.width.identity.activity.SdkLogging

SdkLogging.setLogger { level, tag, message, throwable ->
    when (level) {
        SdkLogLevel.INFO  -> Log.i(tag, message)
        SdkLogLevel.WARN  -> Log.w(tag, message, throwable)
        SdkLogLevel.ERROR -> Log.e(tag, message, throwable)
    }
}

該 logger 是全局且可選的；調用 SdkLogging.setLogger(null) 即可停止轉發。也可以通過 withHandlers(onEvent = ...) 在 builder 上就地註冊同一個 logger。

配置參考

VerificationInput

CredentialsConfig

CustomerConfig

公開 API

com.width.identity.activity 是唯一對客戶開放的包 — 其餘都是內部實現，在你的應用裏引用會直接編譯報錯。

UILanguage

不傳 language 就是英文 — SDK 不會跟隨設備語言。第三方採集頁面另有限制：Veriff 只有在設備聯網、且租戶的集成開啓了中文時才顯示中文，否則仍是英文；Regula 只支持簡體中文。

結果處理

直接輸入的 VerificationResult

VerificationResult 是一個密封類，包含五種變體：

Builder 的 WIDTHCompletionResult

status 是 WIDTHStatus：Approved、FinallyRejected、Pending（人工審覈）、Incomplete（可恢復 / 已 dismissed）、Cancelled（已銷燬）。exception 是 WIDTHException：Init、Network、Api、Permission、Workflow、Unknown 之一 — 每個都暴露 code 與 message。

主題定製

ThemeMode

通過 ThemeConfig 設置模式，或在 Builder 入口覆蓋日間/夜間。兩者省略時均跟隨系統設置。

ThemeConfig(themeMode = "SYSTEM")   // "SYSTEM" / "LIGHT" / "DARK"

// On the Builder entry point — omit to follow the system:
.withForcedDayNightMode(WIDTHDayNightMode.NIGHT)

恢復與生命週期

恢復驗證時，使用相同的 customerId 調用 launcher.launch(...)，SDK 會自動檢測進行中的工作流。

權限

SDK 與其內置的採集引擎聲明瞭所需的全部權限，並會自動合併進你的應用 — 你無需聲明或申請它們：

<!-- WIDTH identity SDK core -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Added transitively by the capture / liveness engine -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />

<!-- Added transitively by the document-reader engine -->
<uses-permission android:name="android.permission.FLASHLIGHT" />

ProGuard / R8：SDK 內置了混淆規則，無需額外配置。

故障排查

集成說明

請按上文獲取軟件包訪問權限並完成安裝。SDK 構建版本及所用憑證須與目標 WIDTH 環境保持一致。