react-native-timacare 3.3.52 → 3.3.53
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +166 -104
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,142 +1,204 @@
|
|
|
1
|
-
#
|
|
1
|
+
# react-native-timacare
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Tima Care SDK** — bộ SDK React Native cho phép nhúng toàn bộ luồng vay/quản lý khoản vay của Tima vào ứng dụng của bạn: định danh eKYC, xác thực khuôn mặt (liveness), ký hợp đồng điện tử (eSign), giải ngân số (digital lending), lịch trả nợ, thanh toán và chi tiết khoản vay.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
SDK cung cấp sẵn một cây điều hướng (navigator) với đầy đủ các màn hình nghiệp vụ. Ứng dụng chủ (host app) chỉ cần khởi tạo cấu hình, gắn `<RNTimacare />` vào `NavigationContainer` của mình và điều hướng vào SDK khi cần.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
---
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Tính năng
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
11
|
+
- **eKYC / định danh**: chụp CCCD (mặt trước/sau), quét MRZ, selfie, OCR giấy tờ xe.
|
|
12
|
+
- **Liveness**: xác thực khuôn mặt (bao gồm bản v2).
|
|
13
|
+
- **eSign & hợp đồng**: xem trước, ký và xác nhận hợp đồng điện tử (Tima, CIMB, MySign Viettel).
|
|
14
|
+
- **Digital lending**: luồng nộp hồ sơ nhanh (quick submit) và đầy đủ (full submit), toàn trình số.
|
|
15
|
+
- **Quản lý khoản vay**: chi tiết khoản vay, lịch trả nợ, thanh toán, mã QR, minh chứng chuyển khoản.
|
|
16
|
+
- **Điều hướng có kiểm soát**: deep-link trực tiếp vào chi tiết khoản vay từ bên ngoài SDK (ví dụ từ push notification hoặc danh sách của host app).
|
|
17
|
+
- **Bền bỉ với mạng yếu**: tự động retry request GET khi lỗi tạm thời, phát hiện offline qua NetInfo (tuỳ chọn), xử lý phiên hết hạn (401) tập trung.
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
---
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
## Yêu cầu
|
|
20
22
|
|
|
23
|
+
- React Native `>= 0.72` (đã kiểm thử với `0.77.x`)
|
|
24
|
+
- React `>= 18`
|
|
25
|
+
- `@react-navigation/native` và `@react-navigation/native-stack` (v6+)
|
|
26
|
+
- `react-native-safe-area-context`
|
|
27
|
+
|
|
28
|
+
SDK sử dụng nhiều thư viện native (camera, vision-camera, pdf, svg, fast-image, ...). Các thư viện này được khai báo là **peer dependencies** — host app phải tự cài đặt. Xem danh sách đầy đủ trong mục `peerDependencies` của [package.json](package.json).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Cài đặt
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
# npm
|
|
36
|
+
npm install react-native-timacare
|
|
37
|
+
|
|
38
|
+
# yarn
|
|
39
|
+
yarn add react-native-timacare
|
|
21
40
|
```
|
|
22
|
-
ignite-project
|
|
23
|
-
├── app
|
|
24
|
-
│ ├── components
|
|
25
|
-
│ ├── i18n
|
|
26
|
-
│ ├── utils
|
|
27
|
-
│ ├── models
|
|
28
|
-
│ ├── navigation
|
|
29
|
-
│ ├── screens
|
|
30
|
-
│ ├── services
|
|
31
|
-
│ ├── theme
|
|
32
|
-
│ ├── app.tsx
|
|
33
|
-
├── storybook
|
|
34
|
-
│ ├── views
|
|
35
|
-
│ ├── index.tsx
|
|
36
|
-
│ ├── storybook-registry.ts
|
|
37
|
-
│ ├── storybook.ts
|
|
38
|
-
├── test
|
|
39
|
-
│ ├── __snapshots__
|
|
40
|
-
│ ├── storyshots.test.ts.snap
|
|
41
|
-
│ ├── mock-i18n.ts
|
|
42
|
-
│ ├── mock-reactotron.ts
|
|
43
|
-
│ ├── setup.ts
|
|
44
|
-
│ ├── storyshots.test.ts
|
|
45
|
-
├── README.md
|
|
46
|
-
├── android
|
|
47
|
-
│ ├── app
|
|
48
|
-
│ ├── build.gradle
|
|
49
|
-
│ ├── gradle
|
|
50
|
-
│ ├── gradle.properties
|
|
51
|
-
│ ├── gradlew
|
|
52
|
-
│ ├── gradlew.bat
|
|
53
|
-
│ ├── keystores
|
|
54
|
-
│ └── settings.gradle
|
|
55
|
-
├── ignite
|
|
56
|
-
│ ├── ignite.json
|
|
57
|
-
│ └── plugins
|
|
58
|
-
├── index.js
|
|
59
|
-
├── ios
|
|
60
|
-
│ ├── IgniteProject
|
|
61
|
-
│ ├── IgniteProject-tvOS
|
|
62
|
-
│ ├── IgniteProject-tvOSTests
|
|
63
|
-
│ ├── IgniteProject.xcodeproj
|
|
64
|
-
│ └── IgniteProjectTests
|
|
65
|
-
├── .env
|
|
66
|
-
└── package.json
|
|
67
41
|
|
|
42
|
+
Sau đó cài các peer dependencies được liệt kê trong [package.json](package.json) và chạy `pod install` cho iOS:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
cd ios && pod install && cd ..
|
|
68
46
|
```
|
|
69
47
|
|
|
70
|
-
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Tích hợp nhanh
|
|
51
|
+
|
|
52
|
+
Host app tự sở hữu `NavigationContainer` của mình, đăng ký `ref` đó cho SDK, khởi tạo cấu hình bằng `initSDK`, rồi render `<RNTimacare />`.
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
import * as React from 'react';
|
|
56
|
+
import { StatusBar } from 'react-native';
|
|
57
|
+
import {
|
|
58
|
+
NavigationContainer,
|
|
59
|
+
useNavigationContainerRef,
|
|
60
|
+
} from '@react-navigation/native';
|
|
61
|
+
import {
|
|
62
|
+
initialWindowMetrics,
|
|
63
|
+
SafeAreaProvider,
|
|
64
|
+
} from 'react-native-safe-area-context';
|
|
65
|
+
import { RNTimacare, initSDK, setNavigationRef } from 'react-native-timacare';
|
|
66
|
+
|
|
67
|
+
export default function App() {
|
|
68
|
+
// Host app tự quản lý ref của NavigationContainer...
|
|
69
|
+
const navigationRef = useNavigationContainerRef();
|
|
70
|
+
|
|
71
|
+
// ...và đăng ký ref đó cho SDK một lần, để goDetail() có thể điều hướng.
|
|
72
|
+
React.useEffect(() => {
|
|
73
|
+
setNavigationRef(navigationRef);
|
|
74
|
+
}, [navigationRef]);
|
|
75
|
+
|
|
76
|
+
initSDK({
|
|
77
|
+
baseUrl: 'https://apilos.tima.vn/',
|
|
78
|
+
token: 'YOUR_JWT_TOKEN',
|
|
79
|
+
timeout: 300000,
|
|
80
|
+
logout: () => {
|
|
81
|
+
// Phiên hết hạn (401): điều hướng về màn hình đăng nhập, xoá token, ...
|
|
82
|
+
console.log('[App] 401 - Session expired, logging out...');
|
|
83
|
+
},
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
return (
|
|
87
|
+
<SafeAreaProvider initialMetrics={initialWindowMetrics}>
|
|
88
|
+
<StatusBar
|
|
89
|
+
translucent
|
|
90
|
+
backgroundColor="transparent"
|
|
91
|
+
barStyle="dark-content"
|
|
92
|
+
/>
|
|
93
|
+
<NavigationContainer ref={navigationRef}>
|
|
94
|
+
<RNTimacare />
|
|
95
|
+
</NavigationContainer>
|
|
96
|
+
</SafeAreaProvider>
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
```
|
|
71
100
|
|
|
72
|
-
|
|
101
|
+
> Xem ví dụ đầy đủ, chạy được trong thư mục [`example/`](example/src/App.tsx).
|
|
73
102
|
|
|
74
|
-
|
|
103
|
+
---
|
|
75
104
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
├── screens
|
|
83
|
-
├── services
|
|
84
|
-
├── theme
|
|
85
|
-
├── utils
|
|
86
|
-
└── app.tsx
|
|
105
|
+
## API
|
|
106
|
+
|
|
107
|
+
SDK export 4 thành phần chính từ `react-native-timacare`:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
import { RNTimacare, initSDK, setNavigationRef, goDetail } from 'react-native-timacare';
|
|
87
111
|
```
|
|
88
112
|
|
|
89
|
-
|
|
90
|
-
This is where your React components will live. Each component will have a directory containing the `.tsx` file, along with a story file, and optionally `.presets`, and `.props` files for larger components. The app will come with some commonly used components like Button.
|
|
113
|
+
### `RNTimacare`
|
|
91
114
|
|
|
92
|
-
|
|
93
|
-
This is where your translations will live if you are using `react-native-i18n`.
|
|
115
|
+
Component React render cây điều hướng của SDK (`PrimaryNavigator`) với toàn bộ các màn hình nghiệp vụ. Đặt bên trong `NavigationContainer` của host app.
|
|
94
116
|
|
|
95
|
-
|
|
96
|
-
This is where your app's models will live. Each model has a directory which will contain the `mobx-state-tree` model file, test file, and any other supporting files like actions, types, etc.
|
|
117
|
+
### `initSDK(options: SDKConfig)`
|
|
97
118
|
|
|
98
|
-
|
|
99
|
-
This is where your `react-navigation` navigators will live.
|
|
119
|
+
Khởi tạo SDK. Nên gọi trước khi render `<RNTimacare />`. Ngoài việc lưu cấu hình, hàm này còn thu thập thông tin thiết bị (deviceId, IP công khai, appId, payload thiết bị) phục vụ nghiệp vụ.
|
|
100
120
|
|
|
101
|
-
|
|
102
|
-
|
|
121
|
+
| Tham số | Kiểu | Bắt buộc | Mô tả |
|
|
122
|
+
| ------------ | ----------------------- | :------: | -------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| `baseUrl` | `string` | ✅ | Base URL của API Tima (ví dụ `https://apilos.tima.vn/`). |
|
|
124
|
+
| `token` | `string` | – | JWT xác thực người dùng, gắn vào header mỗi request. |
|
|
125
|
+
| `timeout` | `number` | – | Timeout (ms) cho các request ghi/upload. Mặc định do SDK quản lý. |
|
|
126
|
+
| `getTimeout` | `number` | – | Timeout (ms) riêng cho request GET (idempotent). Mặc định `30000`. Fail nhanh để cơ chế retry tiếp quản. |
|
|
127
|
+
| `logout` | `() => void` | – | Callback khi API trả về `401`. Dùng để đưa người dùng về màn hình đăng nhập, xoá token, ... |
|
|
128
|
+
| `netInfo` | `NetInfoLike` | – | Truyền default export của `@react-native-community/netinfo` để fail ngay khi mất kết nối thay vì đợi timeout. |
|
|
103
129
|
|
|
104
|
-
|
|
105
|
-
Any services that interface with the outside world will live here (think REST APIs, Push Notifications, etc.).
|
|
130
|
+
> Gọi bất kỳ API nào của SDK trước khi `initSDK` sẽ ném lỗi `SDK not initialized. Call initSDK() first.`
|
|
106
131
|
|
|
107
|
-
|
|
108
|
-
Here lives the theme for your application, including spacing, colors, and typography.
|
|
132
|
+
### `setNavigationRef(ref, hostRoute?)`
|
|
109
133
|
|
|
110
|
-
|
|
111
|
-
This is a great place to put miscellaneous helpers and utilities. Things like date helpers, formatters, etc. are often found here. However, it should only be used for things that are truely shared across your application. If a helper or utility is only used by a specific component or model, consider co-locating your helper with that component or model.
|
|
134
|
+
Đăng ký `ref` của `NavigationContainer` (từ `useNavigationContainerRef()` hoặc `createNavigationContainerRef()`) cho SDK. Nhờ đó `goDetail()` có thể điều hướng ngay cả khi được gọi từ bên ngoài React.
|
|
112
135
|
|
|
113
|
-
|
|
136
|
+
- `ref`: ref của container (chấp nhận cả dạng object có method trực tiếp lẫn `useRef()` gắn qua `.current`).
|
|
137
|
+
- `hostRoute` *(tuỳ chọn)*: tên route của host app đang render `<RNTimacare />`. Cần khai báo khi SDK **chưa** được mount sẵn (host có màn hình riêng và chỉ mount SDK dưới một route riêng) để deep-link vào SDK trong một lần điều hướng.
|
|
114
138
|
|
|
115
|
-
###
|
|
139
|
+
### `goDetail(loan)`
|
|
116
140
|
|
|
117
|
-
|
|
141
|
+
Điều hướng thẳng vào màn hình chi tiết khoản vay một cách imperative — hữu ích khi mở từ push notification hoặc danh sách khoản vay do host app tự render.
|
|
118
142
|
|
|
119
|
-
|
|
143
|
+
```ts
|
|
144
|
+
// Chỉ với id khoản vay
|
|
145
|
+
goDetail(12345);
|
|
120
146
|
|
|
121
|
-
|
|
147
|
+
// Hoặc với object khoản vay
|
|
148
|
+
goDetail({ id: 12345, disbursementPartner: 'CIMB' });
|
|
149
|
+
```
|
|
122
150
|
|
|
123
|
-
|
|
151
|
+
- Chỉ cần `id` để tải dữ liệu chi tiết.
|
|
152
|
+
- `disbursementPartner === 'CIMB'` → mở màn `DetailLoan`; ngược lại → `DetailLoanTima`.
|
|
124
153
|
|
|
125
|
-
|
|
154
|
+
Thứ tự phân giải điều hướng: (1) nếu navigator của SDK đang mount → điều hướng trực tiếp; (2) nếu chưa mount nhưng host đã đăng ký `ref` + `hostRoute` → mount SDK và deep-link trong một lần; (3) fallback: dispatch qua ref của host (chỉ hoạt động khi SDK là navigator gốc).
|
|
126
155
|
|
|
127
|
-
|
|
156
|
+
---
|
|
128
157
|
|
|
129
|
-
|
|
130
|
-
This starts up the storybook server.
|
|
158
|
+
## Cấu trúc source
|
|
131
159
|
|
|
132
|
-
|
|
133
|
-
|
|
160
|
+
```
|
|
161
|
+
src
|
|
162
|
+
├── RNTimacare.tsx # Component gốc render PrimaryNavigator
|
|
163
|
+
├── sdkConfig.ts # initSDK / getSDKConfig, kiểu SDKConfig
|
|
164
|
+
├── index.tsx # Public API export
|
|
165
|
+
├── navigation/ # PrimaryNavigator, root-navigator, navigationRef, goDetail
|
|
166
|
+
├── screens/ # Toàn bộ màn hình nghiệp vụ (eKYC, eSign, liveness, loan, ...)
|
|
167
|
+
├── services/api/ # Lớp API (apisauce) + retry, xử lý 401, api-problem
|
|
168
|
+
├── components/ # Component dùng chung
|
|
169
|
+
├── constants/ # Hằng số
|
|
170
|
+
├── theme/ # Màu sắc, spacing, typography
|
|
171
|
+
├── utils/ # Tiện ích (log, storage, ...)
|
|
172
|
+
└── assets/ # Ảnh, icon, animation
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Phát triển
|
|
178
|
+
|
|
179
|
+
Dự án sử dụng [react-native-builder-bob](https://github.com/callstack/react-native-builder-bob) để build thư viện.
|
|
180
|
+
|
|
181
|
+
```sh
|
|
182
|
+
# Cài đặt dependencies cho cả thư viện và example
|
|
183
|
+
yarn bootstrap
|
|
184
|
+
|
|
185
|
+
# Chạy app ví dụ
|
|
186
|
+
yarn example android
|
|
187
|
+
yarn example ios
|
|
188
|
+
|
|
189
|
+
# Kiểm tra
|
|
190
|
+
yarn typecheck # Kiểm tra kiểu TypeScript
|
|
191
|
+
yarn lint # ESLint
|
|
192
|
+
yarn test # Jest
|
|
193
|
+
|
|
194
|
+
# Build thư viện
|
|
195
|
+
yarn prepack
|
|
196
|
+
```
|
|
134
197
|
|
|
135
|
-
|
|
198
|
+
App demo nằm trong thư mục [`example/`](example/) và import trực tiếp từ mã nguồn thư viện.
|
|
136
199
|
|
|
137
|
-
|
|
138
|
-
- [2016 aka Ignite 1.0](https://github.com/infinitered/ignite-ir-boilerplate-2016)
|
|
200
|
+
---
|
|
139
201
|
|
|
140
|
-
##
|
|
202
|
+
## License
|
|
141
203
|
|
|
142
|
-
[
|
|
204
|
+
[MIT](LICENSE) © Quang Duc
|