Tích hợp Android SDK

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

Yêu cầu build

Thông tin	Mô tả
Kotlin	1.7.10
minSdkVersion	21

Tích hợp

Giải nén cic-reader-*.zip vào một vị trí bạn có thể tham chiếu — root project, một Maven repo cục bộ, hoặc tương tự.

allprojects {
    repositories {
        maven { url "https://maven.google.com" }
        maven { url "https://jcenter.bintray.com" }
        maven { url "path/to/cic_reader" }  // Ví dụ: maven { url "${project.rootDir}/repo" }
    }
}

dependencies {
    implementation("vn.cake.ekyc.sdk:eid:1.x.x")
}

Khởi tạo

val config = CICConfig(
    "<BASE_URL>",
    true,
    60000,
    60000,
)

CICReadSDK.initialize(
    this,
    config,
    CICHeaderProvider {
        mapOf(
            "custom_header1" to "value1"
        )
    }
)

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
baseUrl	string	Có	—	Base URL cho các lệnh gọi API.
enableCheckNfcData	bool	Không	true	Xác minh dữ liệu NFC với Cake RAR.
readTimeout	int	Không	60000	Timeout đọc API tính bằng mili-giây.
writeTimeout	int	Không	60000	Timeout ghi API tính bằng mili-giây.
cacheScanStrategy	CICCacheScanStrategy	Không	NO_CACHE	Xem Tổng quan Mobile SDK § Cache khi server lỗi.

Đọc chip

Dùng MRZ — số CCCD 9 chữ số, ngày sinh, ngày hết hạn

Ném lỗi IllegalMRZException khi bất kỳ đầu vào nào sai.

class MainActivity : AppCompatActivity(), CICReadCallback {
    fun readCICData() {
        cicReader.readCICData(this,
            "xxxxxxxxx",  // 9 chữ số cuối của số CCCD
            "901212",     // ngày sinh, định dạng yyMMdd
            "301212",     // ngày hết hạn, định dạng yyMMdd
            "<ACCESS_TOKEN>",
            "ref_00000001",
            this)
    }

    override fun onResult(result: CICReadResult) {
        // Gửi kết quả về backend của bạn; không ghi log — nó chứa dữ liệu chip và verification key.
    }

    override fun onError(exception: CICException?) {
        Log.d("CICReader", exception)
    }

    override fun onCancel() {
        Log.d("CICReader", "on user cancel")
    }
}

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
activity	Activity	Có	—	Activity hiện tại.
idCard	string	Có	—	9 chữ số cuối của số CCCD.
dayOfBirth	string	Có	—	Ngày sinh, định dạng yyMMdd.
expiryDate	string	Có	—	Ngày hết hạn của thẻ, định dạng yyMMdd.
accessToken	string	Có	—	Access token của request.
refId	string	Có	—	Reference ID của giao dịch cần xác minh.

Dùng CAN — số CCCD 12 chữ số

cicReader.readCICData(this,
    "001xxxxxxxxx",  // số CCCD đầy đủ 12 chữ số
    "<ACCESS_TOKEN>",
    "ref_00000001",
    this)

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
activity	Activity	Có	—	Activity hiện tại.
idCard	string	Có	—	Số CCCD đầy đủ 12 chữ số.
accessToken	string	Có	—	Access token của request.
refId	string	Có	—	Reference ID của giao dịch cần xác minh.

Kết quả

CICReadResult mang theo các data group thô, cùng với các trường thông tin công dân đã phân tích khi enableCheckNfcData là true.

Dữ liệu chip

Trường	Kiểu	Mô tả
com	string	Thông tin phiên bản Unicode và danh sách các data group hiện có. Base64.
sod	string	Dữ liệu SOD từ lần quét NFC. Base64.
dg1	string	Thông tin cơ bản của cá nhân — thông tin MRZ. Base64.
dg2	string	Ảnh khuôn mặt công dân đã mã hóa. Base64.
dg13	string	Thông tin liên quan đến công dân. Base64.
dg14	string	Dùng cho cơ chế truy cập EAC. Base64.
dg15	string	Public key, dùng cho Passive Authentication. Base64.
cloneStatus	VerificationStatus	Clone status của thẻ. Xem Tổng quan Mobile SDK § Clone status.

Trường thông tin công dân — lấy từ API

Trường	Kiểu	Mô tả
idCardNo	string	Số định danh của công dân.
oldIdCardNumber	string	Số định danh cũ.
fullName	string	Họ và tên đầy đủ.
dateOfBirth	string	Ngày sinh.
dateOfExpiry	string	Ngày hết hạn của thẻ.
gender	string	Giới tính.
nationality	string	Quốc tịch.
ethnic	string	Dân tộc.
religion	string	Tôn giáo.
placeOfOrigin	string	Quê quán.
residenceAddress	string	Nơi thường trú.
personalSpecificIdentification	string	Đặc điểm nhận dạng cá nhân.
dateOfIssuance	string	Ngày cấp thẻ.
fatherName	string	Họ tên cha.
motherName	string	Họ tên mẹ.
spouseName	string	Họ tên vợ/chồng.
faceImage	string	Ảnh khuôn mặt. Base64.
isVerified	bool	Thẻ có được RAR xác minh hay không.
verificationKey	string	Verification key — truyền giá trị này vào Xác minh NFC.
requestId	string	Request ID của lần xác thực.

Xử lý lỗi

override fun onError(exception: CICException?) {
    Log.w("CICReader", exception)

    when (exception) {
        is CICException.ServerError -> { }
        is CICException.NetworkError -> { }
        // ....
    }
}

Trường	Kiểu	Mô tả
IllegalMRZException	600316	Phát hiện thông tin MRZ không hợp lệ.
IllegalCanException	600317	Phát hiện thông tin CAN không hợp lệ.
EstablishMessageChannelFailedException	600333	Thiết lập kênh message PACE thất bại.
NfcNotAvailableException	600032	NFC không khả dụng.
UnexpectedException	600503	Xảy ra lỗi không mong đợi.
ReadingDataFailedException	600666	Đọc dữ liệu từ CCCD thất bại.
NetworkError	601400	Xảy ra lỗi mạng.
ServerError	601503	Xảy ra lỗi server.
UnauthorizedError	601404	Người dùng không được phép truy cập tài nguyên.
NotFoundError	601408	Không tìm thấy tài nguyên được yêu cầu.
ApiError	601401	API trả về lỗi.
InvalidCardType	600396	Thẻ được quét không phải CCCD.

Hàm dựng sẵn

Trường	Kiểu	Mô tả
isNFCAvailable(context)	bool	Thiết bị có hỗ trợ đọc NFC hay không.
isNfcEnable(context)	bool	NFC có đang được bật hay không.
openNfcSetting(activity)	void	Mở màn hình cài đặt NFC của thiết bị.

Bước tiếp theo

• Tùy biến giao diện Android SDK — tùy biến giao diện màn hình quét
• Xác minh NFC — redeem verificationKey từ backend của bạn
• Tổng quan Mobile SDK — các khái niệm dùng chung giữa các nền tảng