Tích hợp iOS SDK
Hướng dẫn tích hợp SmartOTP iOS SDK, phân phối dưới dạng CakeOTP.xcframework.
WARNING
Trang này ghi lại các tham số, kết quả trả về và mã lỗi của iOS SDK. Hãy hỏi CAKE Support để lấy header file hoặc một project mẫu cho chữ ký phương thức chính xác trước khi triển khai.
Cài đặt
- Mở project Xcode của bạn.
- Kéo
CakeOTP.xcframeworkvào project. - Tích Copy items if needed, Create groups, và Add to targets.
- Chọn target project của bạn.
- Trong Frameworks, Libraries, and Embedded Content, đặt framework thành Embed & Sign.
- Import
CakeOTPtrong code của bạn.
Cấu hình
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
hostName | String | Không | Do SDK tự sinh | Host name của API. |
isShowLog | Bool | Không | false | In log của SDK. |
| Timeout interval | Int | Không | 30 | Timeout HTTP request tính bằng giây. |
Header tùy chỉnh được thêm bằng cách khởi tạo một object RestEntity và gọi hàm add của nó — có sẵn cả cách gọi trực tiếp lẫn thông qua hàm cập nhật cấu hình.
Ghi đè base URL
Mọi API service đều nhận một tham số overrideBaseUrl.
WARNING
Truyền null hoặc chuỗi rỗng cho overrideBaseUrl không quay về hostName — request 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.
Kích hoạt
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
otp | String | Có | — | OTP do server gửi sau khi backend của bạn gọi Đăng ký. |
vpBankUserId | String | Không | Do SDK tự sinh | ID người dùng. |
vpBankDeviceId | String | Không | Do SDK tự sinh | ID thiết bị. |
vpBankPartnerId | String | Không | Do SDK tự sinh | ID partner. |
deviceOS | String | Không | iOS | Hệ điều hành thiết bị dùng để theo dõi. |
pushToken | String | Không | — | Push token, nếu dùng. |
appVersion | String | Không | — | Phiên bản ứng dụng, nếu dùng. |
token | String | Không | — | Token đăng ký từ Đăng ký. |
registrationId | String | Không | — | Registration id từ Đăng ký. |
Trả về: ActivateSOTPModel, hoặc một CakeErrorModel mang theo code và message.
Tham số otp chính là activation_key từ response của Đăng ký.
| Mã | Mô tả |
|---|---|
3 | Parameter invalid |
103 | Thông tin Partner không chính xác — Partner details are incorrect. |
124 | OTP không hợp lệ — Invalid OTP. |
125 | OTP hết hạn sử dụng — OTP expired. |
129 | Token không hợp lệ — Invalid token. |
INFO
Các tham số trên iOS có tên vpBankUserId, vpBankDeviceId và vpBankPartnerId. Đây là các định danh chung cho user, device và partner bất kể tên gọi mang tính đặc thù tenant — hãy truyền giá trị của riêng bạn bất kể bạn là partner nào.
PIN và lưu trữ
Store
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
pin | String | Có | — | PIN của người dùng, 4 hoặc 6 chữ số. |
vpBankUserId | String | Không | Do SDK tự sinh | ID người dùng. |
Lưu khóa bí mật của Soft OTP trong bộ nhớ cục bộ bên trong SDK, mã hóa bằng PIN.
Check
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
pin | String | Có | — | PIN của người dùng, 4 hoặc 6 chữ số. |
Trả về: Bool. Chỉ được gọi sau khi lưu Soft OTP thành công.
Clear
Xóa PIN đang được lưu hiện tại.
Đổi PIN
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
oldPin | String | Có | — | PIN hiện tại. Truyền chuỗi rỗng khi chưa có PIN nào được lưu. |
newPin | String | Có | — | PIN mới, được kiểm tra với hai PIN gần nhất. |
Trả về: ChangePinResult
| Trường | Kiểu | Mô tả |
|---|---|---|
success | ChangePinResult | PIN đã được đổi. |
invalidOldPin | ChangePinResult | PIN cũ không hợp lệ. |
sameOldAndNewPin | ChangePinResult | PIN mới trùng với PIN cũ. |
samePreviousPins | ChangePinResult | PIN mới trùng với một trong các PIN trước đó đã lưu. |
unknownFailure | ChangePinResult | Lỗi không xác định. |
iOS phân biệt năm kết quả trong khi Android chỉ báo cáo ba — sameOldAndNewPin và samePreviousPins đều xuất hiện dưới dạng UNKNOWN_FAILURE trên Android.
Tạo OTP
Cơ bản
Không nhận tham số. Trả về: String? — Soft OTP cơ bản được tạo ra.
Nâng cao
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
challengeKey | String | Có | — | Khóa challenge từ Tạo giao dịch, được băm (hash) từ user_id, device_id, registration_id, app_id, transaction_id, transaction_amount và unique_id cùng với private key của server. |
Trả về: String? — Soft OTP nâng cao được tạo ra.
Lấy trạng thái
Trả về: status dưới dạng String, hoặc một CakeErrorModel.
Một trong các giá trị NON_ACTIVATED, ACTIVATED, TEMPORARY_BLOCKED, NOT_CURRENT_USER, NOT_REGISTERED — xem Tổng quan Mobile SDK § Các giá trị trạng thái.
| Mã | Mô tả |
|---|---|
103 | Thông tin Partner không chính xác — Partner details are incorrect. |
Đồng bộ thời gian
Trả về timestamp hiện tại của server dưới dạng SyncTimeData, hoặc một CakeErrorModel.
| Mã | Mô tả |
|---|---|
103 | Thông tin Partner không chính xác — Partner details are incorrect. |
129 | Token không hợp lệ — Invalid token. |
190108 | Tài khoản chưa hoạt động — Account not activated. |
190302 | OTP không chính xác — Incorrect OTP. |
Hủy kích hoạt
Hủy kích hoạt Soft OTP đang hoạt động hiện tại của người dùng.
Trả về: Bool, hoặc một CakeErrorModel.
| Mã | Mô tả |
|---|---|
3 | Parameter invalid |
103 | Thông tin Partner không chính xác — Partner details are incorrect. |
129 | Token không hợp lệ — Invalid token. |
Giao dịch mới nhất
Không nhận tham số. Trả về: LatestTransactionResponseModel, hoặc một CakeErrorModel.
Tương đương với Lấy giao dịch mới nhất.
Accessor
| Trường | Kiểu | Mô tả |
|---|---|---|
| Get current username | String? | Username đã đăng ký. |
Get current registration_id | String? | Registration id đã đăng ký. |
| Get current user id | String? | User id đã đăng ký. |
| Get serial id | String? | Serial id từ server. |
| Save serial id | — | Lưu một serial id do bạn tự cung cấp. |
| Get time | GetTimeResponseModel | Timestamp của server, thông qua API GetTime. |
| Get period | Int? | Chu kỳ TOTP. |
| Get remaining validity time | Int | Số giây còn lại của OTP hiện tại. Trả về -1 khi lỗi. |
| Check is SOTP registered | Bool | Thiết bị này đã đăng ký SmartOTP hay chưa. |
INFO
getRemainingValidityTime trả về -1 khi lỗi trên iOS, trong khi Android trả về một giá trị rỗng. Hãy kiểm tra -1 một cách tường minh thay vì coi mọi giá trị falsy là bằng không.
Lưu ý khi triển khai
| Thông tin | Mô tả |
|---|---|
| Chữ ký phương thức | Không liệt kê ở đây. Tên chính xác, nhãn tham số và hình dạng completion-handler có trong header file do CAKE Support cung cấp. |
RestEntity | Được nhắc đến cho header tùy chỉnh nhưng không có định nghĩa kiểu dữ liệu đi kèm. |
| Thông báo lỗi | Được ghi ở đây có dấu tiếng Việt. SDK có thể trả về dạng không dấu (Thong tin Partner khong chinh xac) — hãy so khớp theo mã lỗi, không theo nội dung. |
Bước tiếp theo
- Tổng quan Mobile SDK — các khái niệm dùng chung với Android
- Tích hợp Android SDK — hướng dẫn tương đương với code đầy đủ
- Mã lỗi — bảng lỗi đầy đủ