@retion-miniapp/sdk 0.18.0 → 0.19.1
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/CHANGELOG.md +19 -0
- package/README.md +7 -725
- package/dist/index.cjs +218 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +71 -1
- package/dist/index.d.ts +71 -1
- package/dist/index.js +209 -2
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,739 +1,21 @@
|
|
|
1
1
|
# @retion-miniapp/sdk
|
|
2
2
|
|
|
3
|
-
SDK cho web mini app chạy trong app Retion.
|
|
3
|
+
SDK cho web mini app chạy trong app Retion: đọc ngữ cảnh page đang mở, lấy token để gọi API và dùng chức năng native của app (thanh toán, in hoá đơn, quét mã, Face ID / Touch ID, nhận dạng giọng nói, vị trí, upload file).
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
npm i @retion-miniapp/sdk
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|---|---|
|
|
11
|
-
| [`getRouteParams()`](#getrouteparams) | Biết mini app đang mở ở tổ chức / page / khách nào |
|
|
12
|
-
| [`getToken(type)`](#gettokentype) | Lấy token của page đang mở để gọi API |
|
|
13
|
-
| [`onContextChange(cb)`](#oncontextchangecallback) | **Bắt buộc** — chuyển sang page / conversation khác |
|
|
14
|
-
| [`closeApp()`](#closeapp) | Đóng mini app |
|
|
15
|
-
| [`isInHost()`](#isinhost) | Đang chạy trong app hay trên trình duyệt |
|
|
16
|
-
| [`onAppPaused(cb)` / `onAppResumed(cb)`](#onapppausedcallback--onappresumedcallback) | Mini app bị đóng (chạy ngầm) / mở lại |
|
|
17
|
-
| [`requestPayment(req)`](#requestpaymentrequest) | Thanh toán qua cổng của app (Tap to Pay…) |
|
|
18
|
-
| [`printImage({ image })`](#printimage-image-) | In hoá đơn ra máy in của app |
|
|
19
|
-
| [`openScreen({ screen, params })`](#openscreen-screen-params-) | Mở 1 màn hình của app |
|
|
20
|
-
| [`openLink(url)`](#openlinkurl) | Mở link bằng hệ điều hành (deeplink app khác, tel:, mailto:, https) |
|
|
21
|
-
| [`haptic(type)`](#haptictype) | Rung phản hồi (bấm nút, thanh toán xong…) |
|
|
22
|
-
| [`showToast(message, options?)`](#showtoastmessage-options) | Hiện toast trên app, nổi trên mini app và camera |
|
|
23
|
-
| [`getBiometricAvailability()` / `authenticateBiometric(req)`](#face-id--touch-id--android-biometrics) | Kiểm tra Face ID / Touch ID và trả nguyên kết quả xác thực native |
|
|
24
|
-
| [`startSpeech(options)` / `stopSpeech()` / `onSpeech(event, cb)`](#nhận-dạng-giọng-nói) | Bắt đầu/dừng nhận dạng và nhận văn bản tạm thời/cuối cùng |
|
|
25
|
-
| [`scanCode(options?)` / `startScanner(options?)` / `stopScanner()` / `onScanner(event, cb)`](#quét-mã-qr--barcode) | Quét mã một lần hoặc liên tiếp kiểu quầy thu ngân |
|
|
26
|
-
| [`getCurrentLocation(options?)`](#vị-trí-hiện-tại) | Xin quyền và lấy vị trí thiết bị một lần |
|
|
27
|
-
| [`uploadFiles(options?)` / `getUploadCapabilities()`](#upload-file) | Chọn ảnh / video / tài liệu bằng UI của app, app nén + upload rồi trả link |
|
|
9
|
+
## Tài liệu
|
|
28
10
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## Ví dụ
|
|
34
|
-
|
|
35
|
-
```ts
|
|
36
|
-
import { getRouteParams, getToken, onContextChange } from '@retion-miniapp/sdk';
|
|
37
|
-
|
|
38
|
-
async function load() {
|
|
39
|
-
const { org_id, page_id } = getRouteParams();
|
|
40
|
-
const token = await getToken('access');
|
|
41
|
-
// gọi API của bạn với org_id, page_id, token
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
load(); // lúc mở
|
|
45
|
-
onContextChange(load); // chuyển conversation
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## `getRouteParams()`
|
|
51
|
-
|
|
52
|
-
Lấy param của mini app (như query trên URL): tổ chức, page, khách của conversation đang mở.
|
|
53
|
-
|
|
54
|
-
```ts
|
|
55
|
-
const { org_id, page_id, client_id } = getRouteParams();
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
| Field | Kiểu | Ý nghĩa |
|
|
59
|
-
|---|---|---|
|
|
60
|
-
| `org_id` | `string` | Tổ chức đang dùng app |
|
|
61
|
-
| `page_id` | `string` | Page (kênh) của conversation |
|
|
62
|
-
| `client_id` | `string` | Khách hàng của conversation |
|
|
63
|
-
| `message_id` | `string?` | Tin nhắn mở mini app (nếu mở từ 1 tin cụ thể) |
|
|
64
|
-
| `comment_id` | `string?` | Bình luận mở mini app (nếu mở từ bình luận) |
|
|
65
|
-
| `locale` | `string` | Ngôn ngữ app: `vi`, `en`, `id`, `lo`, `km`, `th`, `tl`, `zh` |
|
|
66
|
-
| `is_page_admin` | `1 \| 0` | `1` nếu người dùng là admin của page |
|
|
67
|
-
|
|
68
|
-
Ngoài app (trình duyệt / iframe cũ): đọc từ query URL — mọi giá trị là **chuỗi** (`is_page_admin` là `"1"` / `"0"`).
|
|
69
|
-
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## `getToken(type)`
|
|
73
|
-
|
|
74
|
-
Lấy token để gọi API. Luôn trả token **của page đang mở**. Gọi mỗi lần cần — **không lưu lại** (token có thể đổi khi chuyển page hoặc hết hạn).
|
|
75
|
-
|
|
76
|
-
```ts
|
|
77
|
-
const token = await getToken('access');
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
| `type` | Token | Cần quyền |
|
|
81
|
-
|---|---|---|
|
|
82
|
-
| `'access'` | Token của mini app cho page hiện tại | Không |
|
|
83
|
-
| `'partner'` | Token đối tác của page | `partner_token` |
|
|
84
|
-
| `'chatbox'` | Token đăng nhập của người dùng app — **toàn quyền** như người dùng | `chatbox_token` |
|
|
85
|
-
|
|
86
|
-
- Quyền do admin bật trên Console (app → *Quyền lấy token*) — không khai trong code được. Chưa bật → lỗi `PERMISSION_DENIED`.
|
|
87
|
-
- Ngoài app: đọc `?access_token=` / `?partner_token=` / `?chatbox_token=` trên URL; không có → lỗi `NOT_IN_HOST`.
|
|
88
|
-
- `getAccessToken()` = `getToken('access')`.
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## `onContextChange(callback)`
|
|
93
|
-
|
|
94
|
-
Gọi khi mini app **đang mở sẵn** được mở lại ở **conversation khác** (khác page hoặc khác khách, cùng tổ chức). App **không nạp lại trang**, nên web phải tự tải lại dữ liệu ở đây. **Bắt buộc** với mọi mini app.
|
|
95
|
-
|
|
96
|
-
```ts
|
|
97
|
-
onContextChange(() => load());
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
Callback nhận 2 tham số, dùng khi cần so sánh:
|
|
101
|
-
|
|
102
|
-
```ts
|
|
103
|
-
onContextChange((next, prev) => {
|
|
104
|
-
if (next.page_id !== prev.page_id) {
|
|
105
|
-
// đổi page → xoá dữ liệu riêng của page cũ trước khi load
|
|
106
|
-
}
|
|
107
|
-
load();
|
|
108
|
-
});
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
| Tham số | Kiểu | Ý nghĩa |
|
|
112
|
-
|---|---|---|
|
|
113
|
-
| `next` | `RouteParams` | Conversation mới — giống `getRouteParams()` gọi lúc này |
|
|
114
|
-
| `prev` | `RouteParams` | Conversation trước đó |
|
|
115
|
-
|
|
116
|
-
**Khi nào được gọi / không được gọi**
|
|
117
|
-
|
|
118
|
-
| Tình huống | App làm gì | Callback |
|
|
119
|
-
|---|---|---|
|
|
120
|
-
| Mở lại ở conversation khác, cùng tổ chức | Giữ nguyên trang, gửi thông tin mới | ✅ Gọi |
|
|
121
|
-
| Mở lại ở đúng conversation cũ | Giữ nguyên trang | ❌ Không gọi |
|
|
122
|
-
| Mở lại ở **tổ chức khác** | Nạp lại trang | ❌ Không gọi (code chạy lại từ đầu) |
|
|
123
|
-
| Mở lần đầu / trang chưa load xong | Nạp trang | ❌ Không gọi (code chạy lại từ đầu) |
|
|
124
|
-
|
|
125
|
-
**Lưu ý**
|
|
126
|
-
|
|
127
|
-
- Trong callback, `getRouteParams()` và `getToken()` đã trả thông tin + token của conversation mới.
|
|
128
|
-
- App tạm che mini app cho tới khi callback chạy xong → đổi giao diện sang trạng thái loading **ngay đầu** callback (trước lệnh `await` đầu tiên) để người dùng không thấy dữ liệu cũ.
|
|
129
|
-
- Trả về hàm huỷ lắng nghe: `const off = onContextChange(load); off();`
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## `closeApp()`
|
|
134
|
-
|
|
135
|
-
Đóng mini app, quay về màn chat. Mini app vẫn chạy ngầm để mở lại tức thì.
|
|
136
|
-
|
|
137
|
-
```ts
|
|
138
|
-
await closeApp();
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
Ngoài app → lỗi `NOT_IN_HOST`.
|
|
142
|
-
|
|
143
|
-
---
|
|
144
|
-
|
|
145
|
-
## `isInHost()`
|
|
146
|
-
|
|
147
|
-
`true` nếu đang chạy trong app Retion; `false` nếu trên trình duyệt / iframe cũ. Dùng khi 1 source chạy cả 2 nơi.
|
|
148
|
-
|
|
149
|
-
```ts
|
|
150
|
-
if (isInHost()) await closeApp();
|
|
151
|
-
else history.back();
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
---
|
|
155
|
-
|
|
156
|
-
## `onAppPaused(callback)` / `onAppResumed(callback)`
|
|
157
|
-
|
|
158
|
-
Mini app bị đóng (vẫn chạy ngầm) / được mở lại. Dừng việc chạy nền khi bị đóng để đỡ tốn pin.
|
|
159
|
-
|
|
160
|
-
```ts
|
|
161
|
-
onAppPaused(() => clearInterval(timer)); // polling, video, animation...
|
|
162
|
-
onAppResumed(() => load()); // làm mới dữ liệu nếu cần
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
Trả về hàm huỷ lắng nghe.
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## Chức năng native của app
|
|
170
|
-
|
|
171
|
-
Thanh toán, in, mở màn hình — **app tự cài** phần xử lý. Kết quả trả thẳng về chỗ `await`.
|
|
172
|
-
|
|
173
|
-
| Kết quả | Web nhận |
|
|
174
|
-
|---|---|
|
|
175
|
-
| Thành công | Giá trị trả về của `await` |
|
|
176
|
-
| App không hỗ trợ | Lỗi `NOT_SUPPORTED` — ẩn nút hoặc báo người dùng |
|
|
177
|
-
| Người dùng huỷ | Lỗi `CANCELLED` |
|
|
178
|
-
| Đang thanh toán / in mà gọi lần nữa (bấm 2 lần) | Lỗi `BUSY` — lượt đầu vẫn chạy bình thường |
|
|
179
|
-
|
|
180
|
-
### `requestPayment(request)`
|
|
181
|
-
|
|
182
|
-
```ts
|
|
183
|
-
import { requestPayment, MiniAppError, ErrorCode } from '@retion-miniapp/sdk';
|
|
184
|
-
|
|
185
|
-
try {
|
|
186
|
-
const { transaction_id, provider } = await requestPayment({
|
|
187
|
-
amount: 12.5, // theo đơn vị tiền tệ
|
|
188
|
-
currency: 'CAD',
|
|
189
|
-
order_id: order.id,
|
|
190
|
-
});
|
|
191
|
-
await markOrderPaid(order.id, { transaction_id, provider });
|
|
192
|
-
} catch (e) {
|
|
193
|
-
if (e instanceof MiniAppError && e.code === ErrorCode.CANCELLED) {return;} // người dùng huỷ
|
|
194
|
-
showError(e);
|
|
195
|
-
}
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
| Field | Kiểu | |
|
|
199
|
-
|---|---|---|
|
|
200
|
-
| `amount` | `number` | Số tiền theo đơn vị tiền tệ (12.5 = 12,50) |
|
|
201
|
-
| `currency` | `string` | ISO 4217: `CAD`, `USD`, `VND`… |
|
|
202
|
-
| `order_id` | `string?` | Mã đơn của bạn — gắn vào giao dịch để đối soát |
|
|
203
|
-
| `note` | `string?` | Ghi chú giao dịch |
|
|
204
|
-
| `metadata` | `object?` | Dữ liệu thêm app cần |
|
|
205
|
-
|
|
206
|
-
Kết quả: `{ transaction_id, provider, ... }`. Chờ tối đa 10 phút (người dùng chạm thẻ), không bị timeout 15s.
|
|
207
|
-
|
|
208
|
-
> **Luôn đối soát qua backend theo `order_id`.** Web có thể bị đóng / hết thời gian chờ trong khi giao dịch phía app vẫn
|
|
209
|
-
> thành công — đừng chỉ dựa vào kết quả `await` để quyết định đơn đã trả hay chưa.
|
|
210
|
-
|
|
211
|
-
### `printImage({ image })`
|
|
212
|
-
|
|
213
|
-
In ảnh hoá đơn (base64, có hoặc không có `data:image/...;base64,`). App tự hiện chọn máy in. Resolve khi in xong.
|
|
214
|
-
|
|
215
|
-
```ts
|
|
216
|
-
await printImage({ image: canvas.toDataURL('image/png') });
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### `openScreen({ screen, params })`
|
|
220
|
-
|
|
221
|
-
Mở 1 màn hình của app — app đóng mini app rồi chuyển màn. Tên màn hình do app định nghĩa (xem tài liệu của app);
|
|
222
|
-
màn không tồn tại → `NOT_SUPPORTED`.
|
|
223
|
-
|
|
224
|
-
```ts
|
|
225
|
-
await openScreen({ screen: 'customer', params: { customer_id } });
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
### `openLink(url)`
|
|
229
|
-
|
|
230
|
-
Nhờ app mở link bằng hệ điều hành: deeplink sang app khác (`retion://…`, `zalo://…`), `tel:`, `mailto:`, hoặc `https`
|
|
231
|
-
(trình duyệt ngoài / Universal Link mở thẳng app đích). Dùng thay `window.open` — WebView trong app **không tự mở**
|
|
232
|
-
link ra ngoài, gọi `window.open` sẽ nạp link ngay trong mini app.
|
|
233
|
-
|
|
234
|
-
```ts
|
|
235
|
-
import { isInHost, openLink } from '@retion-miniapp/sdk';
|
|
236
|
-
|
|
237
|
-
if (isInHost()) {
|
|
238
|
-
await openLink('https://retion.ai/chat').catch(() => {/* không mở được: chưa cài app đích… */});
|
|
239
|
-
} else {
|
|
240
|
-
window.open('https://retion.ai/chat', '_blank');
|
|
241
|
-
}
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
| Lỗi | Khi nào |
|
|
245
|
-
|---|---|
|
|
246
|
-
| `INVALID_PARAMS` | url sai định dạng hoặc scheme bị chặn (`javascript:`, `file:`, `data:`, `about:`, `blob:`) |
|
|
247
|
-
| `NOT_SUPPORTED` | Không ứng dụng nào mở được link hoặc tính năng chưa được hỗ trợ |
|
|
248
|
-
|
|
249
|
-
### `haptic(type)`
|
|
250
|
-
|
|
251
|
-
Rung phản hồi — gọi lúc nào cũng được, không chờ kết quả, không throw. Ngoài app / app chưa hỗ trợ → bỏ qua.
|
|
252
|
-
Tên type y hệt `react-native-haptic-feedback`, dùng hằng `HapticType` (không cần gõ chuỗi). Bỏ trống → `selection`.
|
|
253
|
-
|
|
254
|
-
```ts
|
|
255
|
-
import { haptic, HapticType } from '@retion-miniapp/sdk';
|
|
256
|
-
|
|
257
|
-
haptic(HapticType.impactLight); // bấm nút
|
|
258
|
-
haptic(HapticType.notificationSuccess); // thanh toán xong
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
| `HapticType` | Dùng khi |
|
|
262
|
-
|---|---|
|
|
263
|
-
| `selection` | Đổi tab, picker, toggle |
|
|
264
|
-
| `impactLight` / `impactMedium` / `impactHeavy` | Bấm nút, kéo thả |
|
|
265
|
-
| `rigid` / `soft` | Va chạm cứng / mềm |
|
|
266
|
-
| `notificationSuccess` / `notificationWarning` / `notificationError` | Kết quả thao tác |
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
---
|
|
270
|
-
|
|
271
|
-
## Face ID / Touch ID / Android biometrics
|
|
272
|
-
|
|
273
|
-
Kiểm tra thiết bị hỗ trợ rồi yêu cầu xác thực:
|
|
274
|
-
|
|
275
|
-
```ts
|
|
276
|
-
import { getBiometricAvailability, authenticateBiometric } from '@retion-miniapp/sdk';
|
|
277
|
-
|
|
278
|
-
async function authenticate() {
|
|
279
|
-
try {
|
|
280
|
-
const { available } = await getBiometricAvailability();
|
|
281
|
-
if (!available) return;
|
|
282
|
-
|
|
283
|
-
const result = await authenticateBiometric({
|
|
284
|
-
reason: 'Xác nhận danh tính',
|
|
285
|
-
cancelButtonText: 'Huỷ',
|
|
286
|
-
});
|
|
287
|
-
if (!result.success) {
|
|
288
|
-
console.log(result.error);
|
|
289
|
-
return;
|
|
290
|
-
}
|
|
291
|
-
// Tiếp tục thao tác sau khi xác thực thành công.
|
|
292
|
-
} catch (error) {
|
|
293
|
-
console.error(error);
|
|
294
|
-
}
|
|
295
|
-
}
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
| API | Kết quả |
|
|
299
|
-
| --- | --- |
|
|
300
|
-
| `getBiometricAvailability()` | `{ available, biometryType?, error? }` — khả dụng và loại sinh trắc học |
|
|
301
|
-
| `authenticateBiometric({ reason, cancelButtonText? })` | `{ success, error? }` — kết quả xác thực |
|
|
302
|
-
|
|
303
|
-
`reason` là nội dung hộp xác thực, dài 1–200 ký tự. `cancelButtonText` là nhãn nút huỷ, không bắt buộc, tối đa 80 ký tự.
|
|
304
|
-
|
|
305
|
-
Kiểm tra `result.success` trước khi tiếp tục. Người dùng huỷ có thể trả `{ success: false, error: 'User cancellation' }`; lỗi khác có thể đi vào `catch`. Loại xác thực do thiết bị quyết định: `FaceID`, `TouchID` hoặc `Biometrics` trên Android.
|
|
306
|
-
|
|
307
|
-
---
|
|
308
|
-
|
|
309
|
-
## Nhận dạng giọng nói
|
|
310
|
-
|
|
311
|
-
Đăng ký nhận văn bản trước khi bắt đầu nghe:
|
|
312
|
-
|
|
313
|
-
```ts
|
|
314
|
-
import { startSpeech, stopSpeech, onSpeech } from '@retion-miniapp/sdk';
|
|
315
|
-
|
|
316
|
-
const offPartial = onSpeech('speech.partial', result => console.log(result.text));
|
|
317
|
-
const offFinal = onSpeech('speech.final', result => console.log(result.text));
|
|
318
|
-
const offError = onSpeech('speech.error', error => console.error(error.code, error.message));
|
|
319
|
-
const offEnd = onSpeech('speech.end', () => console.log('Đã dừng nghe'));
|
|
320
|
-
|
|
321
|
-
// Gọi khi bấm nút bắt đầu.
|
|
322
|
-
async function startListening() {
|
|
323
|
-
// mode 's2t': chỉ chuyển giọng nói thành chữ. Bỏ mode (mặc định 'voice') = mở trợ lý voice AI của app chủ.
|
|
324
|
-
try { await startSpeech({ lang: 'vi-VN', mode: 's2t' }); }
|
|
325
|
-
catch (error) { console.error(error); }
|
|
326
|
-
}
|
|
327
|
-
|
|
328
|
-
// Gọi khi bấm nút dừng; vẫn giữ listener để nhận câu cuối.
|
|
329
|
-
async function stopListening() {
|
|
330
|
-
try { await stopSpeech(); }
|
|
331
|
-
catch (error) { console.error(error); }
|
|
332
|
-
}
|
|
333
|
-
|
|
334
|
-
// Khi huỷ component: dừng nếu không còn cần nghe và dọn listener.
|
|
335
|
-
async function dispose() {
|
|
336
|
-
try { await stopSpeech(); }
|
|
337
|
-
finally { offPartial(); offFinal(); offError(); offEnd(); }
|
|
338
|
-
}
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
| API / event | Kết quả |
|
|
342
|
-
| --- | --- |
|
|
343
|
-
| `startSpeech(options?)` | Bắt đầu nghe; trả `Promise<void>`, văn bản đến qua event |
|
|
344
|
-
| `stopSpeech()` | Yêu cầu dừng; trả `Promise<void>`, không phải câu cuối |
|
|
345
|
-
| `speech.partial` | `{ text, isFinal, results }` — văn bản tạm thời |
|
|
346
|
-
| `speech.final` | `{ text, isFinal, results }` — văn bản đã chốt |
|
|
347
|
-
| `speech.error` | `{ code, error, message }` — lỗi khi đang nghe |
|
|
348
|
-
| `speech.end` | Phiên nghe đã kết thúc |
|
|
11
|
+
- [Tài liệu SDK đầy đủ](docs/SDK_README.md) — ngữ cảnh, token, toàn bộ API, mã lỗi và type.
|
|
12
|
+
- [CHANGELOG](CHANGELOG.md) — thay đổi theo từng phiên bản.
|
|
349
13
|
|
|
350
|
-
|
|
14
|
+
Tài liệu chỉ nằm trong repo này, không đóng vào package phát hành.
|
|
351
15
|
|
|
352
|
-
|
|
16
|
+
## Lưu ý bắt buộc
|
|
353
17
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
Giữ listener sau khi gọi dừng để nhận câu cuối nếu có, và chờ `speech.end`. Nếu cần lưu câu cuối khi rời màn hình, đợi event kết thúc trước khi dọn listener. Huỷ listener không tự dừng nghe.
|
|
357
|
-
|
|
358
|
-
Lỗi bắt đầu/dừng đi vào `catch`; lỗi trong phiên đến qua `speech.error`. `BUSY` nghĩa là đang có phiên khác, `PERMISSION_DENIED` là chưa được cấp quyền, `NOT_SUPPORTED` là tính năng chưa được hỗ trợ. Xem thêm [xử lý lỗi](#lỗi).
|
|
359
|
-
|
|
360
|
-
---
|
|
361
|
-
|
|
362
|
-
## showToast(message, options?)
|
|
363
|
-
|
|
364
|
-
Web gọi lúc nào cũng được, không cần `await`; ngoài app thì bỏ qua. Toast mới thay toast cũ. `message` tối đa 200 ký tự. Cần `@retion-miniapp/react-native` 0.13.0+.
|
|
365
|
-
|
|
366
|
-
```ts
|
|
367
|
-
import { showToast, ToastType } from '@retion-miniapp/sdk';
|
|
368
|
-
|
|
369
|
-
showToast('Đã thêm vào giỏ', { type: ToastType.success });
|
|
370
|
-
showToast('Không tìm thấy sản phẩm', { type: ToastType.error });
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
`ToastType`: `info` (mặc định), `success`, `error`.
|
|
374
|
-
|
|
375
|
-
---
|
|
376
|
-
|
|
377
|
-
## Quét mã QR / barcode
|
|
378
|
-
|
|
379
|
-
`scanCode` phủ camera kín vùng mini app và tự đóng khi có mã. `startScanner` hiện camera ở phía trên, web vẫn dùng được ở phần dưới (hoặc phủ kín với `ScannerLayout.full`), và mở đến khi người dùng bấm Đóng hoặc web gọi `stopScanner()`. Camera có sẵn zoom, đèn pin và nút quét từ ảnh, kết quả từ ảnh trả về như quét camera.
|
|
380
|
-
|
|
381
|
-
```ts
|
|
382
|
-
import { scanCode, startScanner, stopScanner, onScanner, CodeType, ScannerEvent, ScannerEndReason, ScannerLayout } from '@retion-miniapp/sdk';
|
|
383
|
-
|
|
384
|
-
// Quét một lần: có mã thì tự đóng camera
|
|
385
|
-
try {
|
|
386
|
-
const { value, type } = await scanCode({ types: [CodeType.qr] });
|
|
387
|
-
} catch (error) {
|
|
388
|
-
// error.code === 'CANCELLED' khi người dùng đóng camera
|
|
389
|
-
}
|
|
390
|
-
|
|
391
|
-
// Quét liên tiếp: đăng ký event trước khi mở camera
|
|
392
|
-
const off_result = onScanner(ScannerEvent.result, ({ value, type }) => addToCart(value));
|
|
393
|
-
const off_end = onScanner(ScannerEvent.end, ({ reason, message }) => {
|
|
394
|
-
off_result();
|
|
395
|
-
off_end();
|
|
396
|
-
if (reason === ScannerEndReason.error) console.error(message);
|
|
397
|
-
});
|
|
398
|
-
await startScanner({ types: CodeType.all, cooldown_ms: 1500 });
|
|
399
|
-
// Đóng từ web nếu cần; người dùng cũng có nút Đóng trên camera
|
|
400
|
-
await stopScanner();
|
|
401
|
-
|
|
402
|
-
// Camera nằm đè (absolute): web giữ nguyên kích thước, tự chừa chỗ dưới camera.
|
|
403
|
-
// Mini app nằm trong iframe cùng origin thì đọc / nghe ở window.top
|
|
404
|
-
window.addEventListener('retionscannerheight', () => setCameraTop(window.__retionScannerHeight ?? 0));
|
|
405
|
-
await startScanner({ layout: ScannerLayout.top, absolute: true });
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
| Hằng | Giá trị |
|
|
409
|
-
| --- | --- |
|
|
410
|
-
| `CodeType` | `qr`, `ean13`, `ean8`, `upcA`, `upcE`, `code128`, `code39`, `code93`, `codabar`, `itf`, `pdf417`, `aztec`, `dataMatrix`; `CodeType.all` là mảng gồm tất cả, cũng là mặc định khi bỏ trống `types` |
|
|
411
|
-
| `ScannerEvent` | `result`: `{ value, type }`; `end`: `{ reason, message? }` |
|
|
412
|
-
| `ScannerEndReason` | `user`: người dùng đóng; `web`: web gọi `stopScanner()`; `closed`: mini app đóng/ẩn, reload hoặc app xuống nền; `error`: lỗi camera, có `message` |
|
|
413
|
-
|
|
414
|
-
| Tuỳ chọn | Mặc định | Ý nghĩa |
|
|
415
|
-
| --- | --- | --- |
|
|
416
|
-
| `types` | `CodeType.all` | Loại mã cần quét; quét ít loại hơn thì nhanh và ít nhận nhầm hơn |
|
|
417
|
-
| `layout` | `ScannerLayout.top` | Chỉ `startScanner`: camera ở trên web (`top`) hoặc phủ kín (`full`) |
|
|
418
|
-
| `absolute` | `false` | Chỉ `startScanner` với `top`: camera nằm đè lên web thay vì đẩy web xuống, web không co / giãn khi mở, đóng camera. Web tự chừa chỗ theo `window.__retionScannerHeight` (px, 0 khi đã đóng), đổi thì bắn event `retionscannerheight` |
|
|
419
|
-
| `hint` | `Đưa mã vào khung để quét` | Chữ hướng dẫn trên camera, 1–80 ký tự; truyền theo ngôn ngữ của mini app |
|
|
420
|
-
| `cooldown_ms` | `1500` | Chỉ `startScanner`, 0–60000 ms: **cùng một mã** phải rời khung đủ thời gian này mới được nhận lại, nên giữ nguyên mã trước camera không bị đếm thêm. Mã khác nhận ngay |
|
|
421
|
-
|
|
422
|
-
| Mã lỗi | Ý nghĩa |
|
|
423
|
-
| --- | --- |
|
|
424
|
-
| `CANCELLED` | Đóng camera trước khi có mã (`scanCode`), hoặc mini app đóng lúc đang xin quyền |
|
|
425
|
-
| `PERMISSION_DENIED` | Chưa cấp quyền camera; hướng dẫn bật lại trong Cài đặt |
|
|
426
|
-
| `BUSY` | Đang có phiên quét khác; cả máy chỉ có một phiên |
|
|
427
|
-
| `NOT_SUPPORTED` | Binary thiếu module camera, hoặc thiết bị không có camera sau |
|
|
428
|
-
| `INVALID_PARAMS` | `types` hoặc `cooldown_ms` không hợp lệ |
|
|
429
|
-
| `HOST_ERROR` | Lỗi camera trong lúc `scanCode` |
|
|
430
|
-
|
|
431
|
-
---
|
|
432
|
-
|
|
433
|
-
## Vị trí hiện tại
|
|
434
|
-
|
|
435
|
-
Xin quyền (nếu chưa có) và trả **một** vị trí. Không theo dõi liên tục, không lấy vị trí nền.
|
|
436
|
-
|
|
437
|
-
```ts
|
|
438
|
-
import { getCurrentLocation } from '@retion-miniapp/sdk';
|
|
439
|
-
|
|
440
|
-
async function locate() {
|
|
441
|
-
try {
|
|
442
|
-
const { coords, timestamp } = await getCurrentLocation({ timeout: 15000, maximumAge: 0 });
|
|
443
|
-
console.log(coords.latitude, coords.longitude, coords.accuracy, timestamp);
|
|
444
|
-
} catch (error) {
|
|
445
|
-
// PERMISSION_DENIED | POSITION_UNAVAILABLE | TIMEOUT | BUSY | NOT_SUPPORTED
|
|
446
|
-
console.error(error.code, error.message);
|
|
447
|
-
}
|
|
448
|
-
}
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
| Tuỳ chọn | Mặc định | Ghi chú |
|
|
452
|
-
| --- | --- | --- |
|
|
453
|
-
| `enableHighAccuracy` | `false` | Yêu cầu GPS chính xác cao |
|
|
454
|
-
| `timeout` | `15000` | 1–60000 ms |
|
|
455
|
-
| `maximumAge` | `0` | 0–86400000 ms; cho phép dùng vị trí đã lưu |
|
|
456
|
-
|
|
457
|
-
Kết quả: `{ coords: { latitude, longitude, accuracy, altitude, altitudeAccuracy, heading, speed }, timestamp }`. Android chấp nhận cả quyền vị trí gần đúng (`accuracy` khi đó lớn hơn). Cần app chủ dùng `@retion-miniapp/react-native` **0.9.0+**; bản cũ trả `NOT_SUPPORTED`.
|
|
458
|
-
|
|
459
|
-
## Upload file
|
|
460
|
-
|
|
461
|
-
Chọn file bằng **giao diện của app** (thư viện ảnh, camera, trình chọn tài liệu…), app **nén và upload** rồi trả link. Web chỉ nhận kết quả cuối, không nhận file gốc hay đường dẫn trong máy. Cần app chủ dùng `@retion-miniapp/react-native` **0.10.0+**; bản cũ trả `NOT_SUPPORTED`.
|
|
462
|
-
|
|
463
|
-
```ts
|
|
464
|
-
import { uploadFiles, getUploadCapabilities } from '@retion-miniapp/sdk';
|
|
465
|
-
|
|
466
|
-
// Hỏi app hỗ trợ nguồn nào để ẩn / hiện nút (vd chỉ hiện nút "Tài liệu" khi có 'document').
|
|
467
|
-
const { sources } = await getUploadCapabilities(); // ['library', 'camera', 'document']
|
|
468
|
-
|
|
469
|
-
const controller = new AbortController();
|
|
470
|
-
try {
|
|
471
|
-
const { files, failed } = await uploadFiles({
|
|
472
|
-
source: 'library',
|
|
473
|
-
accept: ['image/*'],
|
|
474
|
-
max_count: 5,
|
|
475
|
-
max_size: 20 * 1024 * 1024,
|
|
476
|
-
process: { image: { max_width: 1920, max_height: 1920, quality: 0.8 } },
|
|
477
|
-
onProgress: ({ percent }) => console.log(percent),
|
|
478
|
-
signal: controller.signal, // controller.abort() để huỷ
|
|
479
|
-
});
|
|
480
|
-
console.log(files.map(file => file.url));
|
|
481
|
-
if (failed.length) console.warn('Một số file lỗi', failed);
|
|
482
|
-
} catch (error) {
|
|
483
|
-
if (error.code !== 'CANCELLED') console.error(error.code, error.message);
|
|
484
|
-
}
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
Ví dụ khác:
|
|
488
|
-
|
|
489
|
-
```ts
|
|
490
|
-
// Tài liệu (PDF, Word, Excel) từ Files / iCloud / Drive
|
|
491
|
-
await uploadFiles({ source: 'document', accept: ['application/pdf', '.doc', '.docx', '.xls', '.xlsx'], max_count: 3 });
|
|
492
|
-
|
|
493
|
-
// Quay video từ camera, nén mức thấp
|
|
494
|
-
await uploadFiles({ source: 'camera', accept: ['video/*'], process: { video: { max_duration: 30, quality: 'low' } } });
|
|
495
|
-
|
|
496
|
-
// Upload lên server riêng của mini app thay vì máy chủ của app
|
|
497
|
-
await uploadFiles({
|
|
498
|
-
upload: {
|
|
499
|
-
target: 'url',
|
|
500
|
-
url: 'https://api.example.com/upload',
|
|
501
|
-
headers: { Authorization: `Bearer ${token}` },
|
|
502
|
-
form_data: { folder: 'avatars' },
|
|
503
|
-
field_name: 'file',
|
|
504
|
-
url_field: 'data.url', // server trả { data: { url: '...' } }
|
|
505
|
-
},
|
|
506
|
-
});
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
### `uploadFiles(options?): Promise<UploadFilesResult>`
|
|
510
|
-
|
|
511
|
-
**`UploadFilesOptions`** (tất cả đều tuỳ chọn)
|
|
512
|
-
|
|
513
|
-
| Prop | Type | Mặc định | Mô tả |
|
|
514
|
-
| --- | --- | --- | --- |
|
|
515
|
-
| `source` | `string` | `'library'` | Nguồn lấy file. Thường có `'library'` (thư viện ảnh / video), `'camera'` (chụp / quay mới), `'document'` (mọi loại file). App có thể đăng ký thêm; xem `getUploadCapabilities()`. Tên: chữ thường, số, `_`, `-`, tối đa 32 ký tự |
|
|
516
|
-
| `accept` | `string[]` | `[]` (mọi file) | Giống `<input accept>`: mime (`'image/*'`, `'application/pdf'`) hoặc đuôi file (`'.docx'`). Tối đa 50 mục. File không khớp nằm trong `failed` với mã `INVALID_FILE` |
|
|
517
|
-
| `max_count` | `number` | `1` | Số file tối đa được chọn, số nguyên 1–20. Camera luôn chụp 1 |
|
|
518
|
-
| `max_size` | `number` | không giới hạn | Byte tối đa **mỗi file, sau khi nén**. File vượt nằm trong `failed` với mã `FILE_TOO_LARGE` |
|
|
519
|
-
| `process` | `UploadProcessOptions` | `{}` | Nén trước khi upload (bảng dưới). App hỗ trợ tới đâu áp dụng tới đó; tài liệu không bị nén |
|
|
520
|
-
| `upload` | `UploadTarget \| UploadUrlTarget` | `{ target: 'host' }` | Upload lên đâu (bảng dưới) |
|
|
521
|
-
| `concurrency` | `number` | `3` | Số file upload song song, số nguyên 1–5 |
|
|
522
|
-
| `onProgress` | `(progress: UploadProgress) => void` | — | Tiến trình gộp cả lượt, tối đa ~5 lần/giây. Chỉ để hiển thị |
|
|
523
|
-
| `signal` | `AbortSignal` | — | `abort()` dừng các upload đang chạy, Promise reject `CANCELLED`. Không đóng được trình chọn file đang mở |
|
|
524
|
-
|
|
525
|
-
**`process`**
|
|
526
|
-
|
|
527
|
-
| Prop | Type | Mặc định | Mô tả |
|
|
528
|
-
| --- | --- | --- | --- |
|
|
529
|
-
| `image.max_width` | `number` | giữ nguyên | Chiều rộng tối đa (px), số nguyên 1–10000. Giữ tỉ lệ |
|
|
530
|
-
| `image.max_height` | `number` | giữ nguyên | Chiều cao tối đa (px), số nguyên 1–10000. Giữ tỉ lệ |
|
|
531
|
-
| `image.quality` | `number` | `0.8` | Chất lượng JPEG, trong khoảng (0, 1] |
|
|
532
|
-
| `video.max_duration` | `number` | không giới hạn | Thời lượng tối đa khi quay (giây), số nguyên 1–3600 |
|
|
533
|
-
| `video.quality` | `'low' \| 'medium' \| 'high'` | `'medium'` | Mức nén video |
|
|
534
|
-
|
|
535
|
-
Ảnh HEIC trên iOS được chuyển sang JPEG.
|
|
536
|
-
|
|
537
|
-
**`upload`**: máy chủ của app (`UploadTarget`)
|
|
538
|
-
|
|
539
|
-
| Prop | Type | Mặc định | Mô tả |
|
|
540
|
-
| --- | --- | --- | --- |
|
|
541
|
-
| `target` | `string` | `'host'` | Tên đích app đăng ký. `'host'` = máy chủ của app; app tự gắn token |
|
|
542
|
-
| `params` | `Record<string, unknown>` | `{}` | Tham số thêm cho đích (vd thư mục). Xem tài liệu của app |
|
|
543
|
-
|
|
544
|
-
**`upload`**: server của mini app (`UploadUrlTarget`). App gửi `multipart/form-data` bằng `POST`.
|
|
545
|
-
|
|
546
|
-
| Prop | Type | Mặc định | Mô tả |
|
|
547
|
-
| --- | --- | --- | --- |
|
|
548
|
-
| `target` | `'url'` | — | Bắt buộc |
|
|
549
|
-
| `url` | `string` | — | Bắt buộc, chỉ `https://` |
|
|
550
|
-
| `headers` | `Record<string, string>` | `{}` | Header gửi kèm (vd `Authorization`). Tối đa 20 key |
|
|
551
|
-
| `form_data` | `Record<string, string>` | `{}` | Field text gửi kèm trong form. Tối đa 20 key |
|
|
552
|
-
| `field_name` | `string` | `'file'` | Tên field chứa file |
|
|
553
|
-
| `url_field` | `string` | `'url'` | Đường dẫn tới link trong JSON server trả, dạng `a.b.c`. Thiếu link → `UPLOAD_FAILED` |
|
|
554
|
-
|
|
555
|
-
Server phải trả HTTP 2xx. Mỗi file là một request riêng.
|
|
556
|
-
|
|
557
|
-
**`UploadProgress`**
|
|
558
|
-
|
|
559
|
-
| Prop | Type | Mô tả |
|
|
560
|
-
| --- | --- | --- |
|
|
561
|
-
| `loaded` | `number` | Byte đã gửi (cả lượt) |
|
|
562
|
-
| `total` | `number` | Tổng byte (cả lượt); có thể là `0` khi chưa biết |
|
|
563
|
-
| `percent` | `number` | 0–100 |
|
|
564
|
-
| `done_count` | `number` | Số file đã xong (thành công hoặc lỗi) |
|
|
565
|
-
| `count` | `number` | Số file sẽ upload |
|
|
566
|
-
|
|
567
|
-
**`UploadFilesResult`**
|
|
568
|
-
|
|
569
|
-
| Prop | Type | Mô tả |
|
|
570
|
-
| --- | --- | --- |
|
|
571
|
-
| `files` | `UploadedFile[]` | File upload thành công, đúng thứ tự đã chọn |
|
|
572
|
-
| `failed` | `{ name: string; code: string; message: string }[]` | File lỗi riêng lẻ (`INVALID_FILE`, `FILE_TOO_LARGE`, `UPLOAD_FAILED`…). Các file khác vẫn thành công |
|
|
573
|
-
|
|
574
|
-
**`UploadedFile`**
|
|
575
|
-
|
|
576
|
-
| Prop | Type | Mô tả |
|
|
577
|
-
| --- | --- | --- |
|
|
578
|
-
| `url` | `string` | Link file đã upload |
|
|
579
|
-
| `name` | `string` | Tên file |
|
|
580
|
-
| `mime_type` | `string` | Vd `image/jpeg` |
|
|
581
|
-
| `size` | `number?` | Byte (sau nén) |
|
|
582
|
-
| `width` / `height` | `number?` | Kích thước ảnh / video (px), nếu có |
|
|
583
|
-
| `duration` | `number?` | Thời lượng video (giây), nếu có |
|
|
584
|
-
| `response` | `unknown?` | JSON server trả (`target: 'url'`) hoặc dữ liệu thêm app trả |
|
|
585
|
-
|
|
586
|
-
**Khi nào reject**
|
|
587
|
-
|
|
588
|
-
| `code` | Khi nào |
|
|
589
|
-
| --- | --- |
|
|
590
|
-
| `CANCELLED` | Người dùng đóng trình chọn mà không chọn gì, gọi `signal.abort()`, hoặc mini app bị đóng / reload |
|
|
591
|
-
| `PERMISSION_DENIED` | Người dùng từ chối quyền ảnh / camera |
|
|
592
|
-
| `NOT_SUPPORTED` | App chưa hỗ trợ `source` / `upload.target` này, hoặc app phiên bản cũ |
|
|
593
|
-
| `BUSY` | Đang mở một trình chọn file khác. Các lượt đang upload không chặn lượt mới |
|
|
594
|
-
| `INVALID_PARAMS` | Tham số sai kiểu / ngoài khoảng (thông báo nêu rõ prop) |
|
|
595
|
-
| `UPLOAD_FAILED` / `FILE_TOO_LARGE` / `INVALID_FILE` | **Mọi** file đều lỗi. Mã và thông báo lấy từ file đầu tiên |
|
|
596
|
-
| `NOT_IN_HOST` | Chạy ngoài app |
|
|
597
|
-
|
|
598
|
-
Thời gian chờ tối đa 30 phút (gồm lúc chọn file và upload).
|
|
599
|
-
|
|
600
|
-
### `getUploadCapabilities(): Promise<UploadCapabilities>`
|
|
601
|
-
|
|
602
|
-
| Prop | Type | Mô tả |
|
|
603
|
-
| --- | --- | --- |
|
|
604
|
-
| `sources` | `string[]` | Nguồn app hỗ trợ, vd `['library', 'camera', 'document']` |
|
|
605
|
-
| `file_types` | `Record<string, UploadFileType[]>` | Loại file theo nguồn, dùng để hiện lựa chọn thay vì tự ghi danh sách. Nguồn app tự đăng ký không có mục này; app dưới 0.10.3 không trả field này |
|
|
606
|
-
| `targets` | `string[]` | Đích upload app hỗ trợ. Luôn có `'url'`; thường có `'host'` |
|
|
607
|
-
| `max_count` | `number` | `max_count` lớn nhất cho phép (20) |
|
|
608
|
-
|
|
609
|
-
**`UploadFileType`**
|
|
610
|
-
|
|
611
|
-
| Prop | Type | Mô tả |
|
|
612
|
-
| --- | --- | --- |
|
|
613
|
-
| `type` | `string` | Mã loại, vd `'image'`, `'pdf'` |
|
|
614
|
-
| `label` | `string` | Tên hiển thị (tiếng Việt) |
|
|
615
|
-
| `accept` | `string[]` | Truyền thẳng vào `uploadFiles({ accept })`; `[]` = mọi file |
|
|
616
|
-
|
|
617
|
-
```ts
|
|
618
|
-
const { file_types } = await getUploadCapabilities();
|
|
619
|
-
const [first] = file_types?.library ?? [];
|
|
620
|
-
await uploadFiles({ source: 'library', accept: first?.accept });
|
|
621
|
-
```
|
|
622
|
-
|
|
623
|
-
App bản cũ reject `NOT_SUPPORTED`.
|
|
624
|
-
|
|
625
|
-
---
|
|
626
|
-
|
|
627
|
-
## Changelog — `openChangelogPopup()` / `openChangelogHistory()`
|
|
628
|
-
|
|
629
|
-
App chủ hiện popup "Có gì mới" / màn "Xem tất cả cập nhật" bằng UI của nó (nội dung lấy từ `CHANGELOG.md` đã deploy lên Console).
|
|
630
|
-
App chủ vẫn tự hiện popup khi người dùng mở bản mới — 2 hàm này cho nút trong mini app (vd mục "Có gì mới" trong cài đặt).
|
|
631
|
-
|
|
632
|
-
```ts
|
|
633
|
-
import { openChangelogPopup, openChangelogHistory } from '@retion-miniapp/sdk';
|
|
634
|
-
|
|
635
|
-
const shown = await openChangelogPopup({ force: true }); // hiện changelog bản đang dùng, kể cả đã xem
|
|
636
|
-
await openChangelogHistory(); // toàn bộ lịch sử, mới nhất trước
|
|
637
|
-
|
|
638
|
-
// Web merchant mở cho mini app con (chạy trong iframe)
|
|
639
|
-
await openChangelogPopup({ app_id: 'vn.merchant.drive' });
|
|
640
|
-
```
|
|
641
|
-
|
|
642
|
-
| Hàm | Kết quả |
|
|
643
|
-
|---|---|
|
|
644
|
-
| `openChangelogPopup({ app_id?, force? })` | `true` nếu popup hiện. Không `force` → chỉ hiện khi có bản mới chưa xem. `false`: không có gì để hiện / bản chưa có changelog / đang có popup khác / lỗi mạng |
|
|
645
|
-
| `openChangelogHistory({ app_id? })` | mở màn lịch sử |
|
|
646
|
-
|
|
647
|
-
`app_id` mặc định là mini app đang gọi. Mini app con chạy trong iframe của web merchant (cùng origin) vẫn gọi được — SDK tự gửi qua cửa sổ cha — nhưng **phải truyền `app_id`** (đúng `app_id` trong `miniapp.config.json`). App chủ cũ → `NOT_SUPPORTED`; ngoài app → `NOT_IN_HOST`. Cần `@retion-miniapp/react-native` 0.21.0+.
|
|
648
|
-
|
|
649
|
-
## Nhân viên AI của mini app — `setAgent({ app_id, agent_id })`
|
|
650
|
-
|
|
651
|
-
Mỗi mini app có 1 Nhân viên AI (agent) riêng. Báo cho app chủ biết agent của app → thanh Agent, voice và sheet
|
|
652
|
-
"Hội thoại" của app chủ dùng agent này (mỗi phiên voice = 1 hội thoại mới của agent).
|
|
653
|
-
|
|
654
|
-
```ts
|
|
655
|
-
import { setAgent } from '@retion-miniapp/sdk';
|
|
656
|
-
|
|
657
|
-
// Lúc mở app (hoặc khi lấy xong agent từ API). Gọi lại để đổi agent.
|
|
658
|
-
setAgent({ app_id: 'timeboxing', agent_id }); // app_id như miniapp.config.json
|
|
659
|
-
|
|
660
|
-
// agent_info (tuỳ chọn): thông tin của agent
|
|
661
|
-
setAgent({ app_id: 'timeboxing', agent_id, agent_info: { name: 'Zio', description: 'Trợ lý timeboxing' } });
|
|
662
|
-
```
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
### Ngữ cảnh Agent — `onAgentContext(listener, { app_id? })`
|
|
666
|
-
|
|
667
|
-
Khi Agent trả lời một câu hỏi, server có thể kèm ngữ cảnh đã dùng (vd điều kiện lọc). App chủ đẩy xuống đúng mini app
|
|
668
|
-
của agent đó (event `retion.ai.context`) → mini app tự lọc danh sách / điều khiển màn hình theo ngữ cảnh này.
|
|
669
|
-
|
|
670
|
-
```ts
|
|
671
|
-
import { onAgentContext } from '@retion-miniapp/sdk';
|
|
672
|
-
|
|
673
|
-
const off = onAgentContext(({ payload_context, message_text, fb_client_id }) => {
|
|
674
|
-
// payload_context: nguyên giá trị server trả, vd [{ $where: { … }, $sort: { createdAt: 'desc' } }]
|
|
675
|
-
applyFilter(payload_context);
|
|
676
|
-
});
|
|
677
|
-
// rời màn: off()
|
|
678
|
-
```
|
|
679
|
-
|
|
680
|
-
- Chỉ nhận event của app mình: `app_id` truyền vào, bỏ trống thì dùng app_id đã truyền cho `setAgent`.
|
|
681
|
-
- Chạy cả khi mini app mở bằng WebView riêng lẫn khi là app con trong iframe cùng origin của web merchant.
|
|
682
|
-
- Cùng một câu hỏi chỉ báo 1 lần. Ngoài app chủ: không có event, không lỗi.
|
|
683
|
-
|
|
684
|
-
## Lỗi
|
|
685
|
-
|
|
686
|
-
Mọi lỗi là `MiniAppError`, có `code` (loại lỗi) và `method` (hàm gây lỗi).
|
|
687
|
-
|
|
688
|
-
```ts
|
|
689
|
-
import { getToken, MiniAppError, ErrorCode } from '@retion-miniapp/sdk';
|
|
690
|
-
|
|
691
|
-
try {
|
|
692
|
-
await getToken('chatbox');
|
|
693
|
-
} catch (e) {
|
|
694
|
-
if (e instanceof MiniAppError && e.code === ErrorCode.PERMISSION_DENIED) {
|
|
695
|
-
// chưa được cấp quyền chatbox_token
|
|
696
|
-
}
|
|
697
|
-
}
|
|
698
|
-
```
|
|
699
|
-
|
|
700
|
-
| `code` | Khi nào |
|
|
701
|
-
|---|---|
|
|
702
|
-
| `NOT_IN_HOST` | Chạy ngoài app mà gọi hàm cần app |
|
|
703
|
-
| `PERMISSION_DENIED` | Chưa được cấp quyền lấy token đó, hoặc người dùng từ chối quyền vị trí |
|
|
704
|
-
| `POSITION_UNAVAILABLE` | Tắt dịch vụ định vị / không có tín hiệu |
|
|
705
|
-
| `TIMEOUT` | App không phản hồi sau 15s (thanh toán / in: 10 phút, upload: 30 phút), hoặc hết `timeout` khi lấy vị trí |
|
|
706
|
-
| `NOT_SUPPORTED` | Phiên bản app hiện tại chưa hỗ trợ hàm này |
|
|
707
|
-
| `CANCELLED` | Người dùng huỷ (thanh toán, chọn máy in, chọn file…), hoặc mini app đóng khi đang lấy vị trí / upload |
|
|
708
|
-
| `BUSY` | Đang thanh toán / in / lấy vị trí / mở trình chọn file mà gọi lần nữa |
|
|
709
|
-
| `INVALID_PARAMS` | Tham số truyền vào sai kiểu / ngoài khoảng |
|
|
710
|
-
| `UPLOAD_FAILED` | Upload lỗi (mạng, server trả lỗi, response không có link) |
|
|
711
|
-
| `FILE_TOO_LARGE` | File vượt `max_size` |
|
|
712
|
-
| `INVALID_FILE` | File không khớp `accept` |
|
|
713
|
-
| `HOST_ERROR` | Lỗi khác phía app (vd page chưa có token) |
|
|
714
|
-
|
|
715
|
-
---
|
|
716
|
-
|
|
717
|
-
## TypeScript
|
|
718
|
-
|
|
719
|
-
Kèm sẵn type. Export từ package:
|
|
720
|
-
|
|
721
|
-
- Ngữ cảnh / token: `RouteParams`, `TokenType`
|
|
722
|
-
- Native: `PaymentRequest`, `PaymentResult`, `PrintImageRequest`, `OpenScreenRequest`, `HapticType`, `ToastType`, `ShowToastOptions`
|
|
723
|
-
- Sinh trắc học: `BiometryType`, `BiometricAvailability`, `BiometricRequest`, `BiometricResult`
|
|
724
|
-
- Giọng nói: `SpeechOptions`, `SpeechResult`, `SpeechError`, `SpeechEvents`
|
|
725
|
-
- Quét mã: `CodeType`, `ScannerEvent`, `ScannerEndReason`, `ScannerLayout`, `ScanCodeOptions`, `StartScannerOptions`, `ScanResult`, `ScannerEnd`, `ScannerEvents`
|
|
726
|
-
- Vị trí: `LocationOptions`, `LocationResult`
|
|
727
|
-
- Upload: `UploadFilesOptions`, `UploadProcessOptions`, `UploadFilesResult`, `UploadedFile`, `UploadProgress`, `UploadTarget`, `UploadUrlTarget`, `UploadCapabilities`, `UploadFileType`
|
|
728
|
-
- Lỗi: `MiniAppError`, `ErrorCode`
|
|
729
|
-
|
|
730
|
-
```ts
|
|
731
|
-
import type { RouteParams, TokenType, UploadFilesOptions, UploadedFile } from '@retion-miniapp/sdk';
|
|
732
|
-
```
|
|
733
|
-
|
|
734
|
-
---
|
|
735
|
-
|
|
736
|
-
Build + deploy lên app: [`@retion-miniapp/cli`](https://www.npmjs.com/package/@retion-miniapp/cli).
|
|
18
|
+
**1 mini app = 1 trang, load 1 lần.** Mở mini app ở page / conversation khác, app **không nạp lại trang** mà gọi `onContextChange` — thiếu nó web sẽ hiện dữ liệu page cũ. Đổi tổ chức thì app nạp lại trang.
|
|
737
19
|
|
|
738
20
|
## License
|
|
739
21
|
|