Tổng quan Mobile SDK
FaceAuthen không có SDK chụp ảnh riêng. Nó dùng lại CAKE eKYC Mobile SDK — cùng entry point takeFaces chụp một ảnh selfie, kiểm tra chất lượng và xác nhận liveness. Trang này chỉ đề cập đến những phần liên quan đến xác thực khuôn mặt.
Nền tảng
| Thông tin | Mô tả |
|---|---|
| Android | Kotlin. Entry point CakeEkyc. Phiên bản hiện tại 1.1.9. |
| iOS | Swift. Entry point CakeEkycSdk. Phiên bản hiện tại 1.1.9. |
| Flutter | Dart. Entry point CakeEkycPlugin. Phiên bản hiện tại 1.0.0. |
SDK làm gì cho FaceAuthen
takeFaces chạy một pipeline và trả cho bạn những ảnh đã vượt qua kiểm tra chất lượng và liveness:
chụp khuôn mặt → tải ảnh lên → kiểm tra sanity khuôn mặt → kiểm tra livenessKết quả đó cấp dữ liệu cho hai lệnh gọi FaceAuthen mà backend của bạn thực hiện:
| Thông tin | Mô tả |
|---|---|
| Đăng ký khuôn mặt | Lần đăng ký đầu tiên. Truyền các image ID đã chụp vào faces. |
| Xác minh Face Authen | Mọi lần xác thực tiếp theo. Truyền image ID của ảnh selfie mới. |
WARNING
SDK không bao giờ tự gọi FaceAuthen. Nó chỉ chụp và xác thực ảnh, rồi dừng lại. Đăng ký, xác minh, xử lý trùng lặp và khóa hồ sơ đều là trách nhiệm của backend bạn — và authentication_key để đóng một giao dịch chỉ đến từ Xác minh Face Authen.
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 request API. |
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. |
WARNING
TokenProvider.getToken(timestamp, path, method) nhận method và path 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 nó — hãy tính toán nó trên backend của bạn. Xem Ký request.
Tùy chọn chụp ảnh
| 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 kiểm tra liveness. |
loadingView | View | Không | Mặc định của SDK | Thay thế giao diện loading hiển thị trong lúc tải lên và kiểm tra. Chỉ Android và iOS. |
Mã lỗi của SDK
Do chính SDK phát sinh, tách biệt với mã lỗi API của FaceAuthen.
| Trường | Kiểu | Mô tả |
|---|---|---|
40000 | string | Timeout. |
40001 | string | Người dùng đã hủy — nhấn back. |
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. |
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.FACE_SANITY_FAILED trên Android, kErrorCodeFaceSanityFailed trên iOS, EkycFailure.faceSanityFailed trên Flutter — nhưng giá trị số thì khớp nhau.
Các mã liên quan đến CCCD 60000 và 60001 cũng tồn tại trong cùng SDK nhưng không bao giờ xuất hiện trong luồng FaceAuthen, vốn không chụp thẻ định danh nào.
Nhãn ảnh
Khi gọi upload trực tiếp, dùng portrait cho một ảnh selfie chụp từ camera. Các nhãn khác thuộc về luồng xử lý giấy tờ.
| Trường | Kiểu | Mô tả |
|---|---|---|
portrait | string | Ảnh chân dung. |
portrait_nfc | string | Ảnh chân dung đọc được từ chip NFC. Dùng cùng face_type: "id_card" khi đăng ký. |
Xem Khuyến nghị sử dụng để biết đầy đủ các nhãn.
Đăng ký từ thẻ ID
Đăng ký khuôn mặt chấp nhận face_type: "id_card" bên cạnh giá trị mặc định selfie. Dùng khi khuôn mặt đăng ký đến từ một giấy tờ thay vì chụp trực tiếp — ví dụ một ảnh chân dung được trích xuất khi đọc chip CCCD. takeFaces của SDK luôn tạo ra selfie; một khuôn mặt id_card đến từ luồng xử lý giấy tờ riêng của bạn.
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
- Đăng ký khuôn mặt — đăng ký các ảnh đã chụp