Android SDK Integration

Integration guide for the eKYC Android SDK, version 1.1.9. Written in Kotlin; the entry point is the CakeEkyc class.

Build Specifications

What	Description
Gradle	7.4
minSdkVersion	21
targetSdkVersion	33
Kotlin	1.7.10

Add Dependencies

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")
}

Initialize and Configure

Build a Config, then obtain the singleton through CakeEkyc.getInstance, which returns a 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" or "en"
    withBaseUrl(baseUrl)
    withToken(TokenProvider.from("<ACCESS_TOKEN>"))
    withLogger(logger)
}.build()

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

Take NID Card

takeNID captures the card, uploads it, checks sanity and tampering, then extracts the card info. Results arrive on the listener.

// capture both sides
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)

Passing the other side

val frontSide: EkycImage

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

Errors

Field	Type	Description
EkycError.UserCanceledError	40001	User pressed back.
EkycError.TimeoutError	40000	Timeout.
EkycError.CameraError	40003	Opening the camera failed.
EkycError.PermissionNotGranted	40002	Permissions were not granted.
EkycError.QualityFailed	60000 / 60001	NID_SANITY_FAILED or NID_TAMPERING_FAILED.
EkycError.UnexpectedError	50000	Runtime exception.

Take Faces

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)

Quality failures here carry FACE_SANITY_FAILED (60002) or FACE_LIVENESS_FAILED (60003).

Custom Loading UI

During upload, quality checks and OCR the SDK shows a loading UI. Pass your own View to TakeNIDConfig.loadingView or TakeFaceConfig.loadingView to replace it.

Upload Image

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 is also accepted: ekyc.upload(data = byteArray, label = label, metaData = metaData).

See Mobile SDK Overview § Image Labels for the permitted label values, and Upload Image for the underlying API.

Individual API Calls

Each maps to a API endpoint and returns Result<EkycResponse<T>>.

// Sanity — both sides, or pass only one 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")

Method	API
checkNIDSanity	Verify ID Card Sanity
checkNIDTampering	Detect ID Card Tampering
readNIDInfo	Read ID Card Info
checkFaceSanity	Verify Face Sanity
checkLiveness	Verify Face Liveness
compareFaces	Compare Faces

Next Steps

• Android SDK Reference — every public class, property and method
• Mobile SDK Overview — concepts shared across platforms