Troubleshooting
Android
| Vấn đề | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
Không resolve được io.liveness.flash:sdk-android | Thiếu GitHub Packages repository hoặc token không có read:packages | Kiểm tra repository URL, username/token và quyền truy cập repo private |
| Camera không mở | Chưa khai báo hoặc chưa request runtime permission CAMERA | Khai báo manifest và request permission trước khi start SDK |
| Màn hình SDK không hiển thị đúng | Truyền applicationContext hoặc container chưa có kích thước | Dùng Activity hiện tại và layout full-screen/gần full-screen |
Callback trả SDK_NOT_INITIALIZED | Chưa gọi setConfigSDK hoặc config bị clear | Setup lại SDK trước khi live check/register face |
Callback trả BACK_PRESSED | Người dùng bấm back trong flow nhúng view | Xử lý như trạng thái hủy flow, không coi là lỗi hệ thống |
| Lỗi ProGuard/R8 runtime | Model/callback bị shrink | Thêm keep rules cho com.liveness.sdk.corev4.model và CallbackLivenessListener |
iOS
| Vấn đề | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Không install được pod | Chưa có quyền repo SDK/private pod hoặc token sai | Kiểm tra GitHub token, quyền repo và dependency SignManager |
Undefined symbols hoặc dyld library not loaded | Framework/dependency chưa link đủ | Chạy lại pod install, mở .xcworkspace, kiểm tra Pods và Embed/Link settings |
| Build simulator lỗi architecture | SDK hiện ưu tiên ios-arm64 | Build và test trên thiết bị thật |
| Không mở được camera | Thiếu NSCameraUsageDescription hoặc user chưa cấp quyền | Kiểm tra Info.plist và request camera permission trước khi start |
| Start session không chạy | detector bị release hoặc previewView chưa layout | Giữ strong reference tới detector và tạo detector sau khi view sẵn sàng |
| Callback thất bại liên tục | Sai appId, key, base URL, transaction hoặc custom header/param | Kiểm tra config SDK, API log, additionParam, additionHeader và response backend |
Flutter
| Vấn đề | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
sdk_not_setup | Chưa gọi setup trước registerFace hoặc live check | Gọi setup và kiểm tra success == true trước khi mở flow |
Activity must extend ComponentActivity | MainActivity không tương thích native view Android | Đổi MainActivity sang FlutterFragmentActivity |
| Không resolve được native Android dependency | Thiếu Maven repo/credential của Flash Liveness Android | Bổ sung GitHub Packages repository trong settings.gradle(.kts) |
| iOS camera không mở | Thiếu NSCameraUsageDescription | Thêm key vào Runner/Info.plist và request permission |
| Live check view trắng/không ổn định | Widget bị đặt trong container quá nhỏ hoặc rebuild liên tục | Đặt trong màn hình riêng full-screen/gần full-screen |
| Event không về | Native view bị dispose hoặc app đóng màn hình quá sớm | Chỉ dispose sau khi nhận success, failure, cancel hoặc user chủ động thoát |
Checklist log khi cần hỗ trợ
Khi gửi issue cho đội SDK, nên chuẩn bị:
- Nền tảng, OS version, device model.
- Version SDK/plugin đang dùng.
- Thời điểm lỗi: setup, register face, start live check, verify backend, callback.
- Log SDK/backend đã ẩn thông tin nhạy cảm.
- Payload callback cuối cùng, đặc biệt
sdkErrorCode,status,message,requestId. - Ảnh chụp màn hình hoặc video flow nếu lỗi liên quan UI/camera.