Tổng quan Mobile SDK

SmartOTP SDK lưu giữ khóa bí mật của client trên thiết bị, bảo vệ nó bằng PIN của người dùng, và tạo mã TOTP ở chế độ offline. SDK có bản cho Android và iOS. SDK cũng bọc các lệnh gọi API mà ứng dụng của bạn cần — kích hoạt, hủy kích hoạt, trạng thái, đồng bộ thời gian, giao dịch mới nhất.

Nền tảng

Thông tin	Mô tả
Android	Kotlin. Entry point SdkSoft. Phiên bản hiện tại 0.4.0.
iOS	Swift. Framework CakeOTP.xcframework.

SDK làm gì cho bạn

Thông tin	Mô tả
Lưu giữ khóa bí mật	Lưu khóa bí mật của client từ Kích hoạt trong bộ nhớ an toàn cục bộ, mã hóa bằng PIN của người dùng.
Tạo mã	Tạo OTP cơ bản và OTP nâng cao ngay trên thiết bị, không cần gọi mạng.
Bọc API	Tự gọi kích hoạt, hủy kích hoạt, lấy trạng thái, đồng bộ thời gian và lấy giao dịch mới nhất giúp bạn.
Theo dõi độ lệch	So sánh đồng hồ thiết bị với server và điều chỉnh.

Backend của bạn vẫn phụ trách Đăng ký, Tạo giao dịch và Xác minh OTP — SDK không bao giờ tự xác minh mã mà nó tạo ra.

PIN

Mọi thứ SDK lưu trữ đều được khóa bằng một PIN mà người dùng chọn khi kích hoạt.

Thông tin	Mô tả
Đặt PIN	storedSecureSmartOTP(pin) sau khi kích hoạt thành công.
Kiểm tra PIN	isValidPin(pin) trước khi tạo bất kỳ mã nào.
Đổi PIN	changePin(oldPin, newPin). PIN mới không được trùng với hai PIN trước đó.

WARNING

Android quy định PIN là 4 chữ số; iOS chấp nhận 4 hoặc 6. Nếu một ứng dụng cần tương tác với ứng dụng còn lại — cùng một người dùng, hai thiết bị — hãy thống nhất một độ dài duy nhất từ đầu, nếu không PIN đặt trên iOS có thể không dùng được trên Android.

Tạo mã

isValidPin(pin)                      → false: hiển thị lỗi, yêu cầu nhập lại
  ↓ true
generateSmartOTP()                   → OTP cơ bản, không gắn ngữ cảnh giao dịch
generateAdvancedSotp(challengeKey)   → OTP nâng cao, gắn với một giao dịch cụ thể

challengeKey đến từ Tạo giao dịch, được push đến thiết bị qua Firebase hoặc được backend của bạn truyền xuống.

Hàm hỗ trợ thiết bị và phiên

Cả hai nền tảng đều expose cùng các accessor chỉ đọc sau:

Thông tin	Mô tả
isSmartOtpRegistered	Thiết bị này đã đăng ký SmartOTP với bất kỳ người dùng nào chưa.
getCurrentUserId · getCurrentUsername	Người dùng đã đăng ký trên thiết bị này.
getRegistrationId · getSerialId	Các định danh được lưu khi kích hoạt.
getTime	Timestamp của server.
getPeriod	Chu kỳ TOTP tính bằng giây.
getRemainingValidityTime	Số giây còn lại của mã hiện tại.

Các giá trị trạng thái

SDK báo cáo hai trạng thái mà endpoint Lấy trạng thái (Back-end) không có.

Trường	Kiểu	Mô tả
NOT_REGISTERED	string	Thiết bị này chưa đăng ký SmartOTP với bất kỳ người dùng nào.
NOT_CURRENT_USER	string	userId được hỏi không phải người dùng mà thiết bị này đã đăng ký.
NON_ACTIVATED	string	Đã đăng ký nhưng chưa kích hoạt trên thiết bị này, hoặc đã kích hoạt trên một thiết bị khác.
ACTIVATED	string	SmartOTP đang hoạt động cho người dùng này trên thiết bị này.
TEMPORARY_BLOCKED	string	SmartOTP của người dùng này trên thiết bị này đang bị chặn.

INFO

NOT_REGISTERED và NOT_CURRENT_USER là kết luận cục bộ trên thiết bị mà SDK đưa ra trước hoặc thay vì gọi server. Hãy xử lý cả năm giá trị, không chỉ ba giá trị có trong tài liệu API.

Mã lỗi của SDK

Ngoài mã lỗi của API, SDK còn tự phát sinh thêm ba mã riêng.

Trường	Kiểu	Mô tả
-1	int	Thông tin không hợp lệ — invalid information.
-2	int	Giải mã secret token thất bại. Chỉ Android.
190302	int	OTP không chính xác — incorrect OTP. Được đồng bộ thời gian phát sinh khi mở khóa bằng useOtp.

Ghi đè Base URL

Mọi lệnh gọi API của SDK đều nhận một overrideBaseUrl để trỏ đến một môi trường khác mà không cần khởi tạo lại.

WARNING

Trên iOS, truyền null hoặc chuỗi rỗng cho overrideBaseUrl không quay về host đã cấu hình — lệnh gọi sẽ thất bại với Unknown host name. Hãy bỏ hẳn tham số này thay vì truyền một giá trị rỗng.

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
• Mã lỗi — bảng lỗi của API