Tổng quan Mobile SDK
eKYC Mobile SDK bọc luồng chụp ảnh, kiểm tra chất lượng và xác minh thành hai lệnh gọi: takeNID cho thẻ định danh và takeFaces cho ảnh selfie. SDK có bản cho Android, iOS và Flutter, với cùng khái niệm và mã lỗi trên cả ba nền tảng.
Nền tảng
| Thông tin | Mô tả |
|---|---|
| Android | Kotlin. Gradle 7.4, minSdk 21, targetSdk 33. Phiên bản hiện tại 1.1.9. |
| iOS | Swift 5. Xcode 16.0+, iOS 13+. Phiên bản hiện tại 1.1.9. |
| Flutter | Dart. Flutter SDK >=3.0.0 <4.0.0. Phiên bản hiện tại 1.0.0. |
Cả ba đều gọi cùng API bên dưới, nên các verdict, nhãn ảnh và cấu trúc response được ghi ở đó áp dụng không đổi.
SDK làm gì cho bạn
Mỗi entry point chạy một pipeline thay vì một thao tác đơn lẻ.
| Thông tin | Mô tả |
|---|---|
takeNID | Chụp thẻ → tải ảnh lên → kiểm tra sanity → kiểm tra giả mạo → trích xuất thông tin thẻ. |
takeFaces | Chụp selfie → tải ảnh lên → kiểm tra sanity khuôn mặt → kiểm tra liveness. |
Nếu bất kỳ bước nào thất bại, pipeline dừng lại và trả về lỗi; nó không tiếp tục với một ảnh xấu. Mỗi SDK cũng expose các lệnh gọi API riêng lẻ (upload, checkNIDSanity, checkNIDTampering, readNIDInfo, checkFaceSanity, checkFaceLiveness, compareFaces) khi bạn cần tự điều khiển từng bước.
WARNING
Đối tượng kết quả của SDK chỉ dùng để điều khiển giao diện. Quyết định onboarding phải dựa trên kết quả backend của bạn lấy từ eKYC server (hoặc trên response mà backend đã xác minh X-Signature) — không bao giờ dựa trên verdict do ứng dụng hay trình duyệt báo về, vì client bị chỉnh sửa có thể thay đổi chúng.
Cấu hình chung
Mọi nền tảng đều dựng một config object với cùng bốn nhóm thiết lập.
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
baseUrl | string | Có | — | Base URL cho các request API. Xem Tổng quan § Điều kiện tiên quyết. |
languageCode | string | Không | vi | vi cho tiếng Việt, en cho tiếng Anh. |
tokenProvider | TokenProvider | Có | — | Cung cấp authentication token. Được gọi với timestamp, path và method. |
logger | Logger | Không | — | Nhận các thông báo info, error và warning từ SDK. |
WARNING
TokenProvider.getToken(timestamp, path, method) nhận chính xác method và path của request vì token là một signature theo từng request, không phải một chuỗi tĩnh. Không bao giờ hardcode token trong ứng dụng — hãy tính toán nó trên backend của bạn. Xem Ký request để biết cơ chế.
Tùy chọn chụp ảnh
Cả hai entry point đều nhận các cờ để tắt một phần của pipeline.
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
captureOnly | bool | Không | false | Chỉ chụp ảnh — không tải lên, không kiểm tra chất lượng, không OCR. |
requiredReview | bool | Không | true | Hiển thị màn hình xác nhận sau khi chụp. Chỉ áp dụng cho NID. |
autoCaptureEnable | bool | Không | true | Tự động chụp khi chất lượng ảnh đạt yêu cầu. Đặt false để chụp thủ công. Chỉ áp dụng cho NID. |
requiredScanQR | bool | Không | false | Quét mã QR ở mặt trước thẻ. Chỉ áp dụng cho NID. |
cardSides | CardSide[] | Không | [front, back] | Mặt nào cần chụp. |
otherSideImages | Map | Không | — | Mặt còn lại đã được chụp trước đó, để kiểm tra chất lượng có thể chạy trên cả hai mặt. |
INFO
Kiểm tra sanity và giả mạo chính xác hơn khi có đủ cả hai mặt thẻ. Nếu luồng của bạn chụp từng mặt qua từng lệnh gọi riêng, hãy truyền mặt còn lại qua otherSideImages thay vì kiểm tra từng mặt một cách tách biệt.
Nhãn ảnh
Khi gọi upload trực tiếp, label PHẢI là một trong các giá trị sau:
| Trường | Kiểu | Mô tả |
|---|---|---|
portrait | string | Ảnh chân dung. |
qr_code | string | Ảnh mã QR. |
id_card.vn.national_id.front | string | Mặt trước của thẻ Việt Nam (CMND cũ/mới, CCCD, Hộ chiếu). |
id_card.vn.national_id.back | string | Mặt sau của thẻ Việt Nam. |
doc.vn.business_license | string | Ảnh giấy phép kinh doanh. |
Mã lỗi của SDK
Các mã này do chính SDK phát sinh, tách biệt với mã lỗi API dạng số.
| Trường | Kiểu | Mô tả |
|---|---|---|
40000 | string | Timeout. |
40001 | string | Người dùng đã hủy — nhấn nút back của thiết bị hoặc nút back trên màn hình. |
40002 | string | Các quyền bắt buộc chưa được cấp. |
40003 | string | Mở thiết bị camera thất bại. Chỉ Android và Flutter. |
50000 | string | Runtime exception không mong đợi. |
60000 | string | Kiểm tra sanity của NID thất bại. |
60001 | string | Kiểm tra giả mạo của NID thất bại. |
60002 | string | Kiểm tra sanity khuôn mặt thất bại. |
60003 | string | Kiểm tra liveness khuôn mặt thất bại. |
Tên hằng số khác nhau tùy nền tảng — EkycError.NID_SANITY_FAILED trên Android, kErrorCodeNidSanityFailed trên iOS, EkycFailure.nidSanityFailed trên Flutter — nhưng giá trị số thì giống hệt nhau.
API được sử dụng
| Thông tin | Mô tả |
|---|---|
| Tải ảnh lên | Mọi ảnh đã chụp đều được tải lên trước khi bất kỳ kiểm tra nào chạy. |
| Xác minh ID Card Sanity | Kiểm tra tính xác thực và hợp lệ của thẻ. |
| Phát hiện giả mạo thẻ ID | Phát hiện làm giả và chỉnh sửa. |
| Đọc thông tin thẻ ID | Trích xuất OCR, MRZ và QR. |
| Xác minh sanity khuôn mặt · Xác minh liveness khuôn mặt | Chất lượng và liveness của selfie. |
| So sánh khuôn mặt | So khớp ảnh selfie với ảnh chân dung trên thẻ. |
Bước tiếp theo
- Tích hợp Android SDK — hướng dẫn tích hợp cho Kotlin
- Tích hợp iOS SDK — hướng dẫn tích hợp cho Swift
- Tích hợp Flutter SDK — hướng dẫn tích hợp cho Dart, gồm cả tùy biến giao diện
- Mã lỗi — các mã lỗi API mà SDK trả về