Tích hợp Android SDK

Hướng dẫn tích hợp eKYC Android SDK, phiên bản 1.1.9. Viết bằng Kotlin; entry point là class CakeEkyc.

Yêu cầu build

Thông tin	Mô tả
Gradle	7.4
minSdkVersion	21
targetSdkVersion	33
Kotlin	1.7.10

Thêm dependency

dependencies {
    val core_version = "1.0.0"
    val ui_version = "1.0.2"
    val image_quality_version = "1.0.3"
    val ekyc_version = "1.1.8"

    // Core
    implementation("vn.cake.ekyc.sdk:ekyc-core:$core_version")
    // UI
    implementation("vn.cake.ekyc.sdk:ekyc-ui:$ui_version")
    // Image quality
    implementation("vn.cake.ekyc.sdk:image-quality:$image_quality_version")
    // Ekyc
    implementation("vn.cake.ekyc.sdk:ekyc:$ekyc_version")
}

Khởi tạo và cấu hình

Dựng một Config, sau đó lấy singleton thông qua CakeEkyc.getInstance, hàm này trả về một Future.

private val logger = object : Logger {
    override fun info(log: String) {}
    override fun error(log: String) {}
    override fun warning(log: String) {}
}

private val baseUrl: String = "<BASE_URL>"

val config = Config.Builder().apply {
    withLanguage("vi")                                   // "vi" hoặc "en"
    withBaseUrl(baseUrl)
    withToken(TokenProvider.from("<ACCESS_TOKEN>"))
    withLogger(logger)
}.build()

val ekycFuture = CakeEkyc.getInstance(applicationContext, config, executor)
val cakeEkyc = ekycFuture.get()

Chụp thẻ NID

takeNID chụp thẻ, tải lên, kiểm tra sanity và giả mạo, rồi trích xuất thông tin thẻ. Kết quả đến qua listener.

// chụp cả hai mặt
val cardSides = listOf(CardSide.Front, CardSide.Back)

val config = TakeNIDConfig(
    cardType = CardType.CCCD,
    cardSides = cardSides,
    requiredReview = true,
    autoCaptureEnable = true,
    requiredScanQR = false,
    captureOnly = false,
    loadingView = customLoadingView
)

val listener = object : NIDCapturingListener {
    override fun onEvent(event: EkycEvent) {}
    override fun onError(error: EkycError) {}
    override fun onSuccess(result: NIDCardResult) {}
}

cakeEkyc.takeNID(activity, config, listener)

Truyền mặt còn lại

val frontSide: EkycImage

ekyc.takeNID(
    activity,
    TakeNIDConfig(
        cardSides = listOf(CardSide.Back),
        otherSideImages = mapOf(CardSide.Front to frontSide)
    ),
    listener
)

Lỗi

Trường	Kiểu	Mô tả
EkycError.UserCanceledError	40001	Người dùng nhấn back.
EkycError.TimeoutError	40000	Timeout.
EkycError.CameraError	40003	Mở camera thất bại.
EkycError.PermissionNotGranted	40002	Các quyền chưa được cấp.
EkycError.QualityFailed	60000 / 60001	NID_SANITY_FAILED hoặc NID_TAMPERING_FAILED.
EkycError.UnexpectedError	50000	Runtime exception.

Chụp khuôn mặt

val config = TakeFaceConfig(captureOnly = false, loadingView = customLoadingView)

val listener = object : FaceCapturingListener {
    override fun onEvent(event: EkycEvent) {}
    override fun onError(error: EkycError) {}
    override fun onSuccess(result: SelfieResult) {}
}

cakeEkyc.takeFaces(activity, config, listener)

Lỗi chất lượng ở đây mang FACE_SANITY_FAILED (60002) hoặc FACE_LIVENESS_FAILED (60003).

Giao diện loading tùy chỉnh

Trong lúc tải lên, kiểm tra chất lượng và OCR, SDK hiển thị một giao diện loading. Truyền View của riêng bạn vào TakeNIDConfig.loadingView hoặc TakeFaceConfig.loadingView để thay thế nó.

Tải ảnh lên

val uploadResult = ekyc.upload(image = bitmap, label = label, metaData = metaData)

val imageId = when (uploadResult) {
    is Result.Success -> uploadResult().data?.imageId
    is Result.Fail -> throw uploadResult.error
}

ByteArray cũng được chấp nhận: ekyc.upload(data = byteArray, label = label, metaData = metaData).

Xem Tổng quan Mobile SDK § Nhãn ảnh để biết các giá trị label được phép, và Tải ảnh lên để biết API bên dưới.

Các lệnh gọi API riêng lẻ

Mỗi lệnh ánh xạ đến một endpoint của API và trả về Result<EkycResponse<T>>.

// Sanity — cả hai mặt, hoặc chỉ truyền một imageId
val sanityResult = ekyc.checkNIDSanity(
    imageId = frontNIDImageId,
    imageId2 = backNIDImageId,
    cardType = "vn.national_id",
    specialTypeId = ""
)

val tamperingResult = ekyc.checkNIDTampering(
    imageId = frontNIDImageId,
    imageId2 = backNIDImageId,
    cardType = "vn.national_id",
    level = ""
)

val nidCardResult = ekyc.readNIDInfo(
    imageId = frontNIDImageId,
    imageId2 = backNIDImageId,
    cardType = "vn.national_id"
)

val faceSanityResult  = ekyc.checkFaceSanity(imageId = "face_image_id_after_upload")
val faceLivenessResult = ekyc.checkLiveness(imageIds = listOf("face_image_id_after_upload"))
val comparedResult     = ekyc.compareFaces(imageId1 = "face_1", imageId2 = "face_2")

Phương thức	API
checkNIDSanity	Xác minh ID Card Sanity
checkNIDTampering	Phát hiện giả mạo thẻ ID
readNIDInfo	Đọc thông tin thẻ ID
checkFaceSanity	Xác minh sanity khuôn mặt
checkLiveness	Xác minh liveness khuôn mặt
compareFaces	So sánh khuôn mặt

Bước tiếp theo

• Tài liệu tham chiếu Android SDK — mọi class, thuộc tính và phương thức công khai
• Tổng quan Mobile SDK — các khái niệm dùng chung giữa các nền tảng