Tích hợp iOS SDK

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

Yêu cầu build

Thông tin	Mô tả
Xcode	16.0+
Phiên bản iOS mục tiêu	13+
Swift	5

Thiết lập dependency

Thêm các file *.framework vào target của bạn, sau đó khai báo quyền camera:

<key>NSCameraUsageDescription</key>
<string>Camera access helps us give you a better experience</string>

Thêm các pod sau:

pod 'TensorFlowLiteSwift', '2.6.0'
pod 'GoogleMLKit/FaceDetection', '6.0.0'
pod 'PromisesSwift', '~> 2.3.1'
pod 'SnapKit', '~> 5.0.1'

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

CakeEkycSdk.getInstance trả về một Future<CakeEkycSdk, Never>.

let config = CESConfig.Builder()
    .withBaseUrl(url: "<BASE_URL>")
    .withToken(tokenProvider: tokenProvider)
    .withLanguage(language: .vi)
    .withLogger(logger: logger)
    .build()

self.cancelable = CakeEkycSdk.getInstance(config: config)
    .receive(on: DispatchQueue.main)
    .sink { [weak self] ekycSdk in
        self?.ekycSdk = ekycSdk
    }

Chụp thẻ NID

Tuân thủ CESNidCapturingDelegate và gọi takeNid.

class YourUIViewController: UIViewController, CESNidCapturingDelegate {
    func onSuccess(result: CESNidCardResult) {}

    func onError(error: CESError) {}

    func onEvent(event: CESEkycEvent) {}

    private func startTakeNid() {
        guard let ekycSdk else { return }
        let config = CESTakeNidConfig(
            cardType: .cccd,
            cardSides: [.front, .back],
            requiredReview: true,
            autoCaptureEnable: true,
            requiredScanQR: false,
            captureOnly: false,
            loadingView: loadingView
        )
        ekycSdk.takeNid(hostViewController: self, config: config, delegate: self)
    }
}

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

let frontSide: CESEkycImage

ekyc.takeNid(
    hostViewController: self,
    config: CESTakeNidConfig(
        cardSides: [CESCardSide.back],
        otherSideImages: [CESCardSide.front: frontImage]
    ),
    delegate: self
)

Lỗi

Trường	Kiểu	Mô tả
CESError.userCancelled	40001	Người dùng nhấn back.
CESError.timeoutError	40000	Timeout.
CESError.permissionNotGranted	40002	Các quyền chưa được cấp.
CESError.qualityFailed	60000 / 60001	kErrorCodeNidSanityFailed hoặc kErrorCodeNidTamperingFailed.
CESError.unexpectedError	50000	Runtime exception.

INFO

iOS SDK không có mã lỗi riêng cho camera. 40003 (CameraError) chỉ tồn tại trên Android và Flutter — lỗi camera trên iOS xuất hiện dưới dạng unexpectedError.

Chụp khuôn mặt

class YourUIViewController: UIViewController, CESFaceCapturingDelegate {
    func onSuccess(result: CESSelfieResult) {}

    func onError(error: CESError) {}

    func onEvent(event: CESEkycEvent) {}

    private func startFace() {
        guard let ekycSdk else { return }
        let config = CESTakeFaceConfig(captureOnly: false, loadingView: loadingView)
        ekycSdk.takeFaces(hostViewController: self, config: config, delegate: self)
    }
}

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

Giao diện loading tùy chỉnh

Truyền UIView của riêng bạn vào CESTakeNidConfig.loadingView hoặc CESTakeFaceConfig.loadingView để thay thế màn hình loading của SDK trong lúc tải lên và kiểm tra chất lượng.

Tải ảnh lên

let uploadResult = ekycSdk.upload(image: image, label: label, metaData: metaData)
switch uploadResult {
case .success(data: let uploadResponse):
    debugPrint("success: \(uploadResponse.data?.imageId)")
case .fail(error: let error):
    debugPrint("fail: \(error)")
default: fatalError()
}

Data cũng được chấp nhận: ekycSdk.upload(data: data, label: label, metaData: metaData).

Xem Tổng quan Mobile SDK § Nhãn ảnh để biết các giá trị label được phép.

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

Mỗi lệnh nhận một params struct và trả về CESResult<CESEkycResponse<T>>.

// Sanity — cả hai mặt, hoặc chỉ truyền image cho một mặt
let params = CESCheckNidSanityParams(
    image: frontNIDImageId,
    image2: backNIDImageId,
    cardType: "vn.national_id",
    specialTypeId: ""
)
let sanityResult = ekycSdk.checkNidSanity(params: params)

switch sanityResult {
case .success(data: let sanityResponse):
    debugPrint("success: \(sanityResponse.data?.cardSanityData)")
case .fail(error: let error):
    debugPrint("fail: \(error)")
default: fatalError()
}

let tamperingResult = ekycSdk.checkNidTampering(params: CESCheckNidTamperingParams(
    image: frontNIDImageId, image2: backNIDImageId, cardType: "vn.national_id", level: nil))

let readNidResult = ekycSdk.readNidInfo(params: CESNidReadInfoParams(
    image: frontNIDImageId, image2: backNIDImageId, cardType: "vn.national_id"))

let faceSanity   = ekycSdk.checkFaceSanity(params: CESFaceSanityParams(image: "face_image_id"))
let faceLiveness = ekycSdk.checkFaceLiveness(params: CESFaceLivenessParams(images: ["face_image_id"]))
let compared     = ekycSdk.compareFaces(params: CESFaceCompareParams(image1: "face_1", image2: "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
checkFaceLiveness	Xác minh liveness khuôn mặt
compareFaces	So sánh khuôn mặt

INFO

CESFaceLivenessParams nhận images: [String] — truyền một mảng, không phải một image đơn lẻ.

Bước tiếp theo

• Tài liệu tham chiếu iOS 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