Tích hợp Flutter SDK

Hướng dẫn tích hợp CICReader Flutter plugin, phiên bản 1.0.8. Entry point là CakeEidPlugin.

Yêu cầu build

Thông tin	Mô tả
iOS	Xcode 15.2+, target iOS 13+
Android	Kotlin 1.7.10, minimum Android SDK 21

Tích hợp

iOS

Bật capability Near Field Communication Tag Reading, sau đó cập nhật Info.plist:

<key>NFCReaderUsageDescription</key>
<string>{Enter your NFC usage description here}</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
    <string>A0000002472001</string>
    <string>00000000000000</string>
</array>

Android

allprojects {
    repositories {
        maven { url "https://maven.google.com" }
        maven { url "https://jcenter.bintray.com" }  // đảm bảo dòng này có mặt
    }
}

Khởi tạo

final eidPlugin = CakeEidPlugin();

final config = CakeNfcConfig(
  baseUrl: "<BASE_URL>",
  enableCheckData: true,
  readTimeoutMs: 60000,
  writeTimeoutMs: 60000,
  cacheScanStrategy: NfcCacheScanStrategy.NO_CACHE,
);

final success = await eidPlugin.initialize(config);

if (success) {
  print('Initialization succeeded');
}

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.
enableCheckData	bool	Không	true	Xác minh dữ liệu NFC với Cake RAR.
readTimeoutMs	int	Không	60000	Timeout đọc API tính bằng mili-giây.
writeTimeoutMs	int	Không	60000	Timeout ghi API tính bằng mili-giây.
cacheScanStrategy	NfcCacheScanStrategy	Không	NO_CACHE	Xem Tổng quan Mobile SDK § Cache khi server lỗi.

INFO

Tham số constructor của Flutter là enableCheckData — cùng thiết lập mà Android và iOS SDK gọi là enableCheckNfcData. Hãy liên hệ đội CAKE nếu quá trình khởi tạo từ chối key này.

Đọc chip

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

try {
  final result = await eidPlugin.readCIC(
    idCard: idCard,      // 9 chữ số cuối của số CCCD
    dob: dob,
    expiryDate: expiryDate,
    accessToken: accessToken,
    refId: refId,
  );
} catch (e) {
  // Xử lý lỗi
}

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
idCard	string	Có	—	9 chữ số cuối của số CCCD.
dob	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ố

try {
  final result = await eidPlugin.readCard(
    idCard: idCard,      // Số CCCD đầy đủ 12 chữ số
    accessToken: accessToken,
    refId: refId,
  );
} catch (e) {
  // Xử lý lỗi
}

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
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.

Lưu ý hai phương thức có tên khác nhau — readCIC cho MRZ, readCard cho CAN.

Kết quả

CICCardResult 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 enableCheckData 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	NfcCloneStatus	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ả
citizenIdentify	string	Số định danh của công dân.
oldCitizenIdentify	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.
ethnicity	string	Dân tộc.
religion	string	Tôn giáo.
placeOfOrigin	string	Quê quán.
placeOfResidence	string	Nơi thường trú.
personalIdentification	string	Đặc điểm nhận dạng cá nhân.
dateProvide	string	Ngày cấp thẻ.
fatherName	string	Họ tên cha.
motherName	string	Họ tên mẹ.
partnerName	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.

Các tên này khớp với tên trường của API, khác với Android và iOS SDK vốn dùng idCardNo / residenceAddress.

Xử lý lỗi

Ba lỗi sau xuất hiện chung trên cả hai nền tảng:

Trường	Kiểu	Mô tả
UserCancelled	3	Người dùng đã hủy thao tác.
SessionOnGoing	4	Một phiên đọc khác đang diễn ra.
Unspecified	-1	Lỗi không mong đợi. Thông báo mang theo chi tiết.

Ngoài các lỗi đó, lỗi xuất hiện với mã của nền tảng gốc — bảng iOS cho bản build iOS, bảng Android cho bản build Android. Cả hai đều có trong Mã lỗi.

Hàm dựng sẵn

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

Kiểm tra cấu hình IPA

Áp dụng cùng checklist production của iOS — xem Tích hợp iOS SDK § Kiểm tra cấu hình IPA.

Bước tiếp theo

• Xác minh NFC — redeem verificationKey từ backend của bạn
• Mã lỗi — bảng lỗi theo từng nền tảng
• Tổng quan Mobile SDK — các khái niệm dùng chung giữa các nền tảng