Tổng quan Mobile SDK

CICReader SDK đọc chip không tiếp xúc bên trong CCCD Việt Nam và trả về cả data group thô lẫn thông tin định danh công dân đã được phân tích. SDK có bản cho Android, iOS và Flutter, cùng một JavaScript bridge cho ứng dụng chạy trong WebView.

Nền tảng

Thông tin	Mô tả
Android	Kotlin. minSdk 21, Kotlin 1.7.10. Phiên bản hiện tại 1.0.6.
iOS	Swift. Xcode 16.0+, iOS 13+. Phiên bản hiện tại 1.0.7.
Flutter	Dart. Xcode 15.2+, Kotlin 1.7.10, iOS 13+, minSdk 21. Phiên bản hiện tại 1.0.8.
JavaScript bridge	Dành cho trang web chạy trong WebView của Android hoặc iOS. Phiên bản hiện tại 1.0.8.

SDK làm gì cho bạn

Một lệnh gọi thực hiện toàn bộ việc đọc chip và, nếu muốn, cả xác minh phía server.

Thông tin	Mô tả
Đọc chip	Thiết lập kênh bảo mật, sau đó đọc com, sod, dg1, dg2, dg13, dg14, dg15.
Xác minh với RAR	Khi enableCheckNfcData là true, gửi các data group đến server Cake RAR, server này kiểm tra và trả về các trường thông tin công dân đã phân tích cùng một verificationKey.

INFO

Khi enableCheckNfcData được đặt là false, SDK chỉ trả về các data group thô và cloneStatus — không có trường thông tin công dân, không có verificationKey. Mọi thuộc tính được đánh dấu lấy từ API trong các bảng kết quả đều phụ thuộc vào cờ này được bật.

Hai cách mở khóa chip

Chip sẽ không mở nếu thiếu một khóa được suy ra từ dữ liệu in trên thẻ. SDK hỗ trợ cả hai phương án.

Thông tin	Mô tả
MRZ — số CCCD 9 chữ số + ngày sinh + ngày hết hạn	Phương án theo chuẩn ICAO. Cần ba thông tin đầu vào từ người dùng. Ném lỗi IllegalMRZException / InvalidFullMRZKey khi bất kỳ thông tin nào sai.
CAN — số CCCD 12 chữ số	Card Access Number. Chỉ cần số CCCD, nên đây là luồng đơn giản hơn. Được thêm từ phiên bản 1.0.3. Ném lỗi IllegalCanException / InvalidCANKey khi sai.

Ưu tiên dùng CAN nếu luồng của bạn đã có sẵn đầy đủ số 12 chữ số — nó loại bỏ hai trường nhập liệu và hai khả năng người dùng gõ sai.

WARNING

isVerified, cloneStatus và các kết quả khác của SDK chỉ dùng để điều khiển giao diện. Quyết định onboarding phải dựa trên Xác minh NFC do backend của bạn gọi, sau khi kiểm tra X-Signature — không bao giờ dựa trên giá trị ứng dụng báo về.

Cấu hình chung

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 bằng cách gọi Cake RAR để xác nhận dữ liệu hợp lệ và được cấp phép.
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	enum	Không	NO_CACHE	Lưu cache một lần quét thành công để có thể thử lại lệnh gọi server khi thất bại mà không cần quét lại. Xem bên dưới.

Mọi nền tảng đều hỗ trợ một header provider để bạn gắn thêm header tùy chỉnh vào mọi request của SDK.

Đầu vào khi chạy

Cả hai phương thức đọc đều nhận các tham số sau, ngoài khóa mở chip:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
accessToken	string	Có	—	Access token của request, được backend của bạn lấy từ Tạo giao dịch.
refId	string	Có	—	Reference ID của giao dịch cần xác minh.

Clone status

Mỗi kết quả đều mang một cloneStatus mô tả kết luận của quá trình xác minh.

Trường	Kiểu	Mô tả
notChecked	0	Thẻ chưa được kiểm tra.
good	1	Thẻ vượt qua xác minh.
alert	2	Thẻ gây ra cảnh báo.
error	8	Xảy ra lỗi trong quá trình quét.

Cache khi server lỗi

Khi việc đọc chip thành công nhưng server không thể xử lý request, SDK có thể lưu cache dữ liệu chip đã quét và thử lại lệnh gọi RAR sau đó mà không cần yêu cầu người dùng chạm thẻ lại.

// Android
val config = CICConfig(
    "<BASE_URL>",
    true,
    cacheScanStrategy = CICCacheScanStrategy.CACHE_FOR_VERIFY
)

// iOS
CESNfcConfig(baseUrl: "<BASE_URL>",
             cacheScanStrategy: .CACHE_FOR_VERIFY)   // .NO_CACHE là mặc định

// Flutter
final config = CakeNfcConfig(
  baseUrl: "<BASE_URL>",
  cacheScanStrategy: NfcCacheScanStrategy.CACHE_FOR_VERIFY,
);

Android và Flutter dùng citizen id làm khóa cache; iOS dùng MRZ key.

WARNING

Khi cache hit, SDK không bắt đầu một lượt quét chip mới, nên nfcScanWillStart và nfcScanDidEnd sẽ không được gọi. Trên iOS, điều này có nghĩa là bạn phải tự hiển thị giao diện "đang xác minh" từ dataVerificationWillStart — nếu không người dùng sẽ thấy màn hình đứng yên trong lúc lệnh gọi RAR đang chạy.

Hàm hỗ trợ kiểm tra thiết bị

Trường	Kiểu	Mô tả
isNfcAvailable	bool	Thiết bị có hỗ trợ đọc NFC hay không.
isNfcEnable	bool	NFC có đang được bật hay không. Chỉ áp dụng cho Android và Flutter — trên iOS luôn trả về true.
openNfcSetting	void	Mở màn hình cài đặt NFC của thiết bị. Chỉ áp dụng cho Android và Flutter.

Bước tiếp theo

• Tích hợp Android SDK — hướng dẫn tích hợp Kotlin
• Tích hợp iOS SDK — hướng dẫn tích hợp Swift
• Tích hợp Flutter SDK — hướng dẫn tích hợp Dart
• JavaScript Bridge — đọc chip từ trang WebView
• Tùy biến giao diện Android SDK — tùy biến giao diện màn hình quét Android