react-native-live-widgets 1.1.0 → 1.2.0
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 +20 -0
- package/README.md +76 -10
- package/android/build.gradle +14 -20
- package/android/src/main/AndroidManifest.xml +1 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +8 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +4 -1
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +29 -3
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +26 -1
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +51 -15
- package/android/src/main/res/layout/rn_live_widget_host.xml +64 -74
- package/docs/GUIDE-EN.md +109 -7
- package/docs/GUIDE-VI.md +109 -7
- package/docs/index.html +440 -0
- package/docs/llms-full.txt +132 -0
- package/docs/llms.txt +88 -0
- package/ios/Models/DynamicLayoutModels.swift +5 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +2 -3
- package/lib/builder.d.ts.map +1 -1
- package/lib/builder.js +29 -19
- package/lib/builder.js.map +1 -1
- package/lib/dispatcher.d.ts +7 -0
- package/lib/dispatcher.d.ts.map +1 -1
- package/lib/dispatcher.js +11 -0
- package/lib/dispatcher.js.map +1 -1
- package/lib/hooks.d.ts +66 -0
- package/lib/hooks.d.ts.map +1 -0
- package/lib/hooks.js +166 -0
- package/lib/hooks.js.map +1 -0
- package/lib/index.d.ts +32 -7
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +115 -8
- package/lib/index.js.map +1 -1
- package/lib/jsx.d.ts +79 -0
- package/lib/jsx.d.ts.map +1 -0
- package/lib/jsx.js +196 -0
- package/lib/jsx.js.map +1 -0
- package/lib/preview.d.ts +54 -0
- package/lib/preview.d.ts.map +1 -0
- package/lib/preview.js +466 -0
- package/lib/preview.js.map +1 -0
- package/lib/types.d.ts +8 -0
- package/lib/types.d.ts.map +1 -1
- package/package.json +3 -1
- package/src/builder.ts +29 -19
- package/src/dispatcher.ts +17 -0
- package/src/hooks.ts +223 -0
- package/src/index.ts +137 -13
- package/src/jsx.tsx +296 -0
- package/src/preview.tsx +719 -0
- package/src/react-ambient.d.ts +10 -0
- package/src/react-native-env.d.ts +43 -0
- package/src/types.ts +8 -0
package/docs/GUIDE-EN.md
CHANGED
|
@@ -68,7 +68,7 @@ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
|
|
|
68
68
|
cd LiveWidgetsExampleExpo
|
|
69
69
|
npm install
|
|
70
70
|
npx expo prebuild
|
|
71
|
-
|
|
71
|
+
npx react-native-live-widgets init
|
|
72
72
|
npx expo run:ios # or npx expo run:android
|
|
73
73
|
```
|
|
74
74
|
|
|
@@ -237,7 +237,7 @@ async function ensureAndroidNotificationPermission() {
|
|
|
237
237
|
```
|
|
238
238
|
|
|
239
239
|
#### 5. Step 4: Adding & Resizing Home Screen Widgets on Android (`small` / `medium` / `large`)
|
|
240
|
-
1. After calling `Widget.
|
|
240
|
+
1. After calling `Widget.setLayout('main', { small, medium, large })` (or alias `Widget.update(...)`) in your app, go to the Android Home Screen.
|
|
241
241
|
2. **Long-press an empty area** on the Home Screen -> Tap **Widgets** -> Find your app -> Drag **Live Widgets** onto the Home Screen.
|
|
242
242
|
3. **Responsive Family Switching (`small` / `medium` / `large`):** Long-press the placed widget and release to show the resize handles:
|
|
243
243
|
- Resize to **2×2 cells** (`width < 210dp`): Automatically renders the **`small`** layout (1:1 square aspect ratio).
|
|
@@ -313,9 +313,86 @@ import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widge
|
|
|
313
313
|
|
|
314
314
|
---
|
|
315
315
|
|
|
316
|
-
## 4. Declarative UI Engine
|
|
316
|
+
## 4. Declarative UI Engine
|
|
317
317
|
|
|
318
|
-
|
|
318
|
+
The library supports **2 dual UI authoring styles** side-by-side depending on your preferences:
|
|
319
|
+
1. **Style 1: React JSX / TSX Components (`<VStack>`, `<Text>`, `<Button>`)** — Write widgets exactly like building standard React Native components. Fully supports the standard `style` prop, conditional style arrays, and nested hierarchies.
|
|
320
|
+
2. **Style 2: Functional DSL (`UI.VStack(...)`)** — Concise and functional, with zero JSX tags to import.
|
|
321
|
+
|
|
322
|
+
Both styles compile down automatically to the exact same native engine (SwiftUI on iOS and 2D Canvas on Android).
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
### Style 1: Building Widgets with JSX / TSX Components
|
|
327
|
+
|
|
328
|
+
```tsx
|
|
329
|
+
import React from 'react';
|
|
330
|
+
import { StyleSheet } from 'react-native';
|
|
331
|
+
import { Widget, VStack, HStack, Text, Badge, Progress, Button } from 'react-native-live-widgets';
|
|
332
|
+
|
|
333
|
+
export const MyWidgetLayout = (
|
|
334
|
+
<VStack style={styles.card}>
|
|
335
|
+
<HStack style={styles.header}>
|
|
336
|
+
<Text style={styles.title}>Shift Check-in</Text>
|
|
337
|
+
<Badge text="07:54 (Valid)" backgroundColor="#064E3B" textColor="#6EE7B7" />
|
|
338
|
+
</HStack>
|
|
339
|
+
<Progress value={0.75} style="segmented" segments={4} tintColor="#38BDF8" height={8} />
|
|
340
|
+
<Button title="Refresh Data" actionId="refresh" fullWidth />
|
|
341
|
+
</VStack>
|
|
342
|
+
);
|
|
343
|
+
|
|
344
|
+
const styles = StyleSheet.create({
|
|
345
|
+
card: {
|
|
346
|
+
padding: 16,
|
|
347
|
+
backgroundColor: '#0F172A',
|
|
348
|
+
borderRadius: 16,
|
|
349
|
+
},
|
|
350
|
+
header: {
|
|
351
|
+
justifyContent: 'space-between',
|
|
352
|
+
marginBottom: 8,
|
|
353
|
+
},
|
|
354
|
+
title: {
|
|
355
|
+
fontSize: 14,
|
|
356
|
+
fontWeight: 'bold',
|
|
357
|
+
color: '#FFFFFF',
|
|
358
|
+
},
|
|
359
|
+
});
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
### In-App Widget Preview (`<WidgetPreview>` / `<VoltraWidgetPreview>`)
|
|
365
|
+
|
|
366
|
+
Embed a realistic, pixel-accurate widget mockup inside any app screen to test layout bounds and button click interactions without leaving your application:
|
|
367
|
+
|
|
368
|
+
```tsx
|
|
369
|
+
import { WidgetPreview, VStack, HStack, Text, Button } from 'react-native-live-widgets';
|
|
370
|
+
|
|
371
|
+
export function PreviewScreen() {
|
|
372
|
+
return (
|
|
373
|
+
<WidgetPreview
|
|
374
|
+
size="medium" // 'small' | 'medium' | 'large' | 'lockScreen'
|
|
375
|
+
showBadge={true} // Shows 'Medium • 338×158'
|
|
376
|
+
interactiveSizeSwitch={true} // Quick tabs to switch small / medium / large
|
|
377
|
+
onAction={(actionId) => {
|
|
378
|
+
console.log('Action tapped inside preview:', actionId);
|
|
379
|
+
}}
|
|
380
|
+
>
|
|
381
|
+
<VStack padding={16} backgroundColor="#0F172A" borderRadius={20}>
|
|
382
|
+
<HStack justifyContent="spaceBetween">
|
|
383
|
+
<Text fontSize={14} fontWeight="bold" color="#FFFFFF">Project Progress</Text>
|
|
384
|
+
<Text fontSize={12} color="#38BDF8">75%</Text>
|
|
385
|
+
</HStack>
|
|
386
|
+
<Button title="Update" actionId="refresh" fullWidth />
|
|
387
|
+
</VStack>
|
|
388
|
+
</WidgetPreview>
|
|
389
|
+
);
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
### Style 2: Functional DSL (`UI.StyleSheet` & Reusable Styling)
|
|
319
396
|
Just like React Native's `StyleSheet.create`, you can define reusable styles to keep your widget layouts modular and clean, supporting conditional style arrays:
|
|
320
397
|
|
|
321
398
|
```typescript
|
|
@@ -502,6 +579,12 @@ UI.Button({
|
|
|
502
579
|
})
|
|
503
580
|
```
|
|
504
581
|
|
|
582
|
+
> [!IMPORTANT]
|
|
583
|
+
> **Architectural Recommendation for Terminated (Force-Killed) Apps:**
|
|
584
|
+
> - **iOS:** When the main app is force-killed by the user, the JavaScript engine (Hermes/JSC) is terminated. Widget button taps are handled natively by Swift (`AppIntent`) and stored in App Groups. JavaScript callbacks (`registerActionHandler`) **cannot run** until the app is reopened.
|
|
585
|
+
> - **Android:** While `HeadlessJsTaskService` can wake the JS runtime in the background, aggressive OEM battery savers (MIUI, ColorOS, OneUI) may delay or suppress headless execution.
|
|
586
|
+
> - **Production Rule:** For mission-critical actions (e.g., employee attendance check-ins or financial authorizations), adopt an **Offline-First & Local State Queue** pattern: Native widgets record the action in `SharedStorage`, and `App.tsx` reads and synchronizes the queue when the app is next launched.
|
|
587
|
+
|
|
505
588
|
### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Advanced Layout Containers)
|
|
506
589
|
```typescript
|
|
507
590
|
// 1. ZStack: Overlay layers on top of each other
|
|
@@ -610,6 +693,11 @@ UI.Custom('WeatherCard', { city: 'Ho Chi Minh City', temp: '31°C' })
|
|
|
610
693
|
|
|
611
694
|
## 5. Dynamic Island Configuration (iPhone 14 Pro, 15, 16, 17)
|
|
612
695
|
|
|
696
|
+
> [!NOTE]
|
|
697
|
+
> **Platform Differences: iOS Dynamic Island vs. Android Live Updates:**
|
|
698
|
+
> - **iOS:** The `dynamicIsland` configuration maps directly to Apple's hardware Dynamic Island pill (iPhone 14 Pro+) via ActivityKit and SwiftUI (`compactLeading`, `compactTrailing`, `minimal`, `expanded`).
|
|
699
|
+
> - **Android:** Because standard Android devices do not feature Apple's hardware island cutout, this configuration is mapped to an **Ongoing Promoted Notification (`Notification.ProgressStyle`)** with an avatar icon, progress segments, and action buttons on the notification bar.
|
|
700
|
+
|
|
613
701
|
```typescript
|
|
614
702
|
dynamicIsland: {
|
|
615
703
|
compactLeading: UI.HStack(
|
|
@@ -735,14 +823,21 @@ if (isSupported) {
|
|
|
735
823
|
When the user swipes away (force-kills) the main app, the React Native JS thread stops. To keep your Widget updated with live server data autonomously:
|
|
736
824
|
|
|
737
825
|
```typescript
|
|
738
|
-
|
|
826
|
+
// Full standard signature:
|
|
827
|
+
await Widget.setRemoteConfig('main', {
|
|
739
828
|
url: 'https://api.yourcompany.com/v1/widget-summary',
|
|
740
829
|
method: 'GET',
|
|
741
830
|
headers: {
|
|
742
831
|
Authorization: `Bearer ${accessToken}`,
|
|
743
832
|
},
|
|
744
|
-
|
|
745
|
-
});
|
|
833
|
+
refreshIntervalMinutes: 15, // OS-scheduled background sync (alias: intervalMinutes)
|
|
834
|
+
}, APP_GROUP);
|
|
835
|
+
|
|
836
|
+
// Or convenient shorthand (defaults to widgetKey = 'main'):
|
|
837
|
+
await Widget.setRemoteConfig({
|
|
838
|
+
url: 'https://api.yourcompany.com/v1/widget-summary',
|
|
839
|
+
refreshIntervalMinutes: 15,
|
|
840
|
+
}, APP_GROUP);
|
|
746
841
|
```
|
|
747
842
|
|
|
748
843
|
- **How it works:**
|
|
@@ -750,6 +845,13 @@ await Widget.setRemoteConfig({
|
|
|
750
845
|
- **Android**: `AlarmManager` schedules `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), fetches fresh JSON in the background (`goAsync()`), updates `SharedPreferences`, and redraws `DynamicHomeScreenWidgetProvider`.
|
|
751
846
|
- The built-in `{{_lastSyncTime}}` placeholder automatically resolves to the latest sync timestamp (`HH:mm:ss`).
|
|
752
847
|
|
|
848
|
+
> [!NOTE]
|
|
849
|
+
> **Understanding Polling Intervals & OS Widget Budget:**
|
|
850
|
+
> - The `intervalMinutes: 15` option specifies the *desired* refresh cadence. Both iOS and Android apply strict battery and resource policies:
|
|
851
|
+
> - **iOS WidgetKit Budget:** Apple enforces a daily budget (~40 to 70 reloads per day). If the device is in Low Power Mode or the daily quota is exhausted, reloads may be delayed.
|
|
852
|
+
> - **Android Doze Mode:** Batches recurring background alarms to preserve battery health.
|
|
853
|
+
> - **Recommendation:** If your application requires precise, second-by-second updates (e.g., driver location or emergency shifts), always rely on **Server Push Notifications (APNs / FCM)** as the primary transport and treat background polling as a fallback.
|
|
854
|
+
|
|
753
855
|
---
|
|
754
856
|
|
|
755
857
|
## 8. Managing All 3 Push Token Types (APNs & FCM)
|
package/docs/GUIDE-VI.md
CHANGED
|
@@ -68,7 +68,7 @@ git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
|
|
|
68
68
|
cd LiveWidgetsExampleExpo
|
|
69
69
|
npm install
|
|
70
70
|
npx expo prebuild
|
|
71
|
-
|
|
71
|
+
npx react-native-live-widgets init
|
|
72
72
|
npx expo run:ios # hoặc npx expo run:android
|
|
73
73
|
```
|
|
74
74
|
|
|
@@ -237,7 +237,7 @@ async function ensureAndroidNotificationPermission() {
|
|
|
237
237
|
```
|
|
238
238
|
|
|
239
239
|
#### 5. Bước 4: Cách thêm và kéo giãn Home Screen Widget trên Android (`small` / `medium` / `large`)
|
|
240
|
-
1. Sau khi gọi `Widget.
|
|
240
|
+
1. Sau khi gọi `Widget.setLayout('main', { small, medium, large })` (hoặc alias `Widget.update(...)`) trong app, ra màn hình chính (Home Screen) của Android.
|
|
241
241
|
2. **Nhấn giữ vào khoảng trống** trên màn hình chính -> Chọn **Widgets (Tiện ích)** -> Tìm ứng dụng của bạn -> Kéo **Live Widgets** ra màn hình.
|
|
242
242
|
3. **Thay đổi kích thước tự động (Responsive Sizing):** Nhấn giữ vào Widget trên màn hình chính rồi thả tay ra để xuất hiện khung viền 4 chấm tròn:
|
|
243
243
|
- Kéo thu nhỏ về **2×2 ô** (`chiều rộng < 210dp`): Tự động hiển thị giao diện **`small`** (tỷ lệ vuông 1:1).
|
|
@@ -315,7 +315,84 @@ import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widge
|
|
|
315
315
|
|
|
316
316
|
## 4. Xây dựng Giao diện Động (Declarative UI Engine)
|
|
317
317
|
|
|
318
|
-
|
|
318
|
+
Thư viện hỗ trợ song song **2 phong cách viết giao diện** tùy theo sở thích và thói quen của bạn:
|
|
319
|
+
1. **Phong cách 1: Dạng JSX / TSX (`<VStack>`, `<Text>`, `<Button>`)** — Giống hệt như viết Component trong React Native, trực quan và dễ bảo trì khi layout lồng ghép nhiều tầng. Hỗ trợ đầy đủ thuộc tính `style` và mảng style có điều kiện.
|
|
320
|
+
2. **Phong cách 2: Dạng Hàm lồng nhau (`UI.VStack(...)`)** — Phong cách Functional gọn gàng, không cần import nhiều thẻ JSX.
|
|
321
|
+
|
|
322
|
+
Cả 2 cách đều được biên dịch tự động sang cùng một kiến trúc Native (SwiftUI trên iOS và 2D Canvas trên Android).
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
### Phong cách 1: Xây dựng bằng JSX / TSX Component
|
|
327
|
+
|
|
328
|
+
```tsx
|
|
329
|
+
import React from 'react';
|
|
330
|
+
import { StyleSheet } from 'react-native';
|
|
331
|
+
import { Widget, VStack, HStack, Text, Badge, Progress, Button } from 'react-native-live-widgets';
|
|
332
|
+
|
|
333
|
+
export const MyWidgetLayout = (
|
|
334
|
+
<VStack style={styles.card}>
|
|
335
|
+
<HStack style={styles.header}>
|
|
336
|
+
<Text style={styles.title}>Vào ca sáng</Text>
|
|
337
|
+
<Badge text="07:54 (Hợp lệ)" backgroundColor="#064E3B" textColor="#6EE7B7" />
|
|
338
|
+
</HStack>
|
|
339
|
+
<Progress value={0.75} style="segmented" segments={4} tintColor="#38BDF8" height={8} />
|
|
340
|
+
<Button title="Làm mới dữ liệu" actionId="refresh" fullWidth />
|
|
341
|
+
</VStack>
|
|
342
|
+
);
|
|
343
|
+
|
|
344
|
+
const styles = StyleSheet.create({
|
|
345
|
+
card: {
|
|
346
|
+
padding: 16,
|
|
347
|
+
backgroundColor: '#0F172A',
|
|
348
|
+
borderRadius: 16,
|
|
349
|
+
},
|
|
350
|
+
header: {
|
|
351
|
+
justifyContent: 'space-between',
|
|
352
|
+
marginBottom: 8,
|
|
353
|
+
},
|
|
354
|
+
title: {
|
|
355
|
+
fontSize: 14,
|
|
356
|
+
fontWeight: 'bold',
|
|
357
|
+
color: '#FFFFFF',
|
|
358
|
+
},
|
|
359
|
+
});
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
### Xem Trước Widget Trong App (`<WidgetPreview>` / `<VoltraWidgetPreview>`)
|
|
365
|
+
|
|
366
|
+
Bạn có thể nhúng widget vào trực tiếp bất kỳ màn hình nào của ứng dụng để xem trước giao diện và bấm thử các nút tương tác mà không cần phải thoát ra Home Screen:
|
|
367
|
+
|
|
368
|
+
```tsx
|
|
369
|
+
import { WidgetPreview, VStack, HStack, Text, Button } from 'react-native-live-widgets';
|
|
370
|
+
|
|
371
|
+
export function PreviewScreen() {
|
|
372
|
+
return (
|
|
373
|
+
<WidgetPreview
|
|
374
|
+
size="medium" // 'small' | 'medium' | 'large' | 'lockScreen'
|
|
375
|
+
showBadge={true} // Hiển thị 'Medium • 338×158'
|
|
376
|
+
interactiveSizeSwitch={true} // Bật thanh tab để chuyển nhanh small/medium/large
|
|
377
|
+
onAction={(actionId) => {
|
|
378
|
+
console.log('Action được bấm trên widget:', actionId);
|
|
379
|
+
}}
|
|
380
|
+
>
|
|
381
|
+
<VStack padding={16} backgroundColor="#0F172A" borderRadius={20}>
|
|
382
|
+
<HStack justifyContent="spaceBetween">
|
|
383
|
+
<Text fontSize={14} fontWeight="bold" color="#FFFFFF">Tiến độ công việc</Text>
|
|
384
|
+
<Text fontSize={12} color="#38BDF8">75%</Text>
|
|
385
|
+
</HStack>
|
|
386
|
+
<Button title="Cập nhật" actionId="refresh" fullWidth />
|
|
387
|
+
</VStack>
|
|
388
|
+
</WidgetPreview>
|
|
389
|
+
);
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
### Phong cách 2: Dạng Hàm (`UI.StyleSheet` & Functional DSL)
|
|
319
396
|
Tương tự như `StyleSheet.create` trong React Native, bạn có thể gom nhóm các style định dạng lại để tái sử dụng nhiều nơi, giữ code sạch sẽ và hỗ trợ truyền mảng style có điều kiện:
|
|
320
397
|
|
|
321
398
|
```typescript
|
|
@@ -502,6 +579,12 @@ UI.Button({
|
|
|
502
579
|
})
|
|
503
580
|
```
|
|
504
581
|
|
|
582
|
+
> [!IMPORTANT]
|
|
583
|
+
> **Khuyến nghị kiến trúc khi xử lý Action lúc App bị Force-Kill (Termination):**
|
|
584
|
+
> - **Trên iOS:** Khi người dùng vuốt tắt ứng dụng hoàn toàn (Force-Kill), JavaScript Engine (Hermes/JSC) sẽ bị tiêu diệt. Lúc này, việc bấm nút trên Widget sẽ do Native Swift (`AppIntent`) xử lý độc lập và ghi nhận trạng thái vào App Group. JS callback (`registerActionHandler`) sẽ **không thể chạy** cho đến khi ứng dụng được người dùng mở lại.
|
|
585
|
+
> - **Trên Android:** Thư viện hỗ trợ `HeadlessJsTaskService` để thức tỉnh JS thread trong nền. Tuy nhiên, trên một số dòng máy có cơ chế quản lý pin nghiêm ngặt (MIUI, ColorOS, OneUI), tiến trình nền vẫn có thể bị hạn chế.
|
|
586
|
+
> - **Quy tắc thiết kế cho Production:** Với các nghiệp vụ sống còn (như **Chấm công**, thanh toán, gửi đơn từ quan trọng), không nên thiết kế nghiệp vụ phụ thuộc 100% vào việc JS callback phải chạy khi app bị kill. Hãy ưu tiên thiết kế theo mô hình **Offline-First & Local State Queue**: Native Widget ghi nhận hành động vào `SharedStorage` (App Group / SharedPreferences), và khi người dùng khởi động lại ứng dụng, `App.tsx` sẽ đọc queue này và đồng bộ an toàn lên Server!
|
|
587
|
+
|
|
505
588
|
### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Bố cục nâng cao)
|
|
506
589
|
```typescript
|
|
507
590
|
// 1. ZStack: Xếp chồng các lớp (Overlay)
|
|
@@ -611,6 +694,11 @@ UI.Custom('WeatherCard', { city: 'TP.HCM', temp: '31°C' })
|
|
|
611
694
|
|
|
612
695
|
## 5. Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)
|
|
613
696
|
|
|
697
|
+
> [!NOTE]
|
|
698
|
+
> **Khác biệt nền tảng: iOS Dynamic Island vs Android Live Updates:**
|
|
699
|
+
> - **Trên iOS:** Khối cấu hình `dynamicIsland` tương tác trực tiếp với phần cứng Dynamic Island (viên thuốc trên iPhone 14 Pro trở lên) thông qua ActivityKit và SwiftUI (`compactLeading`, `compactTrailing`, `minimal`, `expanded`).
|
|
700
|
+
> - **Trên Android:** Do hệ điều hành Android gốc không có phần cứng Dynamic Island của Apple, cấu hình này được thư viện tự động ánh xạ sang **Ongoing Promoted Notification (`Notification.ProgressStyle`)** hiển thị thường trực trên thanh trạng thái với đầy đủ Avatar tròn, thanh tiến trình chia chặng và nút bấm tương tác.
|
|
701
|
+
|
|
614
702
|
```typescript
|
|
615
703
|
dynamicIsland: {
|
|
616
704
|
compactLeading: UI.HStack(
|
|
@@ -733,17 +821,24 @@ if (isSupported) {
|
|
|
733
821
|
|
|
734
822
|
## 7. Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)
|
|
735
823
|
|
|
736
|
-
Khi ứng dụng bị người dùng vuốt tắt hoàn toàn (Kill App), JavaScript thread của React Native sẽ dừng. Để Widget vẫn luôn
|
|
824
|
+
Khi ứng dụng bị người dùng vuốt tắt hoàn toàn (Kill App), JavaScript thread của React Native sẽ dừng. Để Widget vẫn luôn tự động gọi API lấy dữ liệu mới từ Server:
|
|
737
825
|
|
|
738
826
|
```typescript
|
|
739
|
-
|
|
827
|
+
// Cú pháp tiêu chuẩn đầy đủ:
|
|
828
|
+
await Widget.setRemoteConfig('main', {
|
|
740
829
|
url: 'https://api.yourcompany.com/v1/widget-summary',
|
|
741
830
|
method: 'GET',
|
|
742
831
|
headers: {
|
|
743
832
|
Authorization: `Bearer ${accessToken}`,
|
|
744
833
|
},
|
|
745
|
-
|
|
746
|
-
});
|
|
834
|
+
refreshIntervalMinutes: 15, // Chu kỳ gọi ngầm ở tầng OS (alias: intervalMinutes)
|
|
835
|
+
}, APP_GROUP);
|
|
836
|
+
|
|
837
|
+
// Hoặc cú pháp ngắn gọn (mặc định widgetKey = 'main'):
|
|
838
|
+
await Widget.setRemoteConfig({
|
|
839
|
+
url: 'https://api.yourcompany.com/v1/widget-summary',
|
|
840
|
+
refreshIntervalMinutes: 15,
|
|
841
|
+
}, APP_GROUP);
|
|
747
842
|
```
|
|
748
843
|
|
|
749
844
|
- **Cách hoạt động:**
|
|
@@ -751,6 +846,13 @@ await Widget.setRemoteConfig({
|
|
|
751
846
|
- Trên **Android**: `AlarmManager` tự động đánh thức `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), tải JSON mới và vẽ lại `DynamicHomeScreenWidgetProvider`.
|
|
752
847
|
- Biến đặc biệt `{{_lastSyncTime}}` luôn tự động cập nhật thành giờ đồng bộ mới nhất (`HH:mm:ss`).
|
|
753
848
|
|
|
849
|
+
> [!NOTE]
|
|
850
|
+
> **Về chu kỳ gọi API và giới hạn tài nguyên hệ điều hành (Widget Budget):**
|
|
851
|
+
> - Tham số `intervalMinutes: 15` là thời gian mong muốn đề xuất cho hệ điều hành. Cả iOS và Android đều áp dụng cơ chế quản lý năng lượng nghiêm ngặt:
|
|
852
|
+
> - **iOS WidgetKit Budget:** Apple cấp hạn mức reload Widget (khoảng 40 - 70 lần/ngày). Nếu thiết bị bật chế độ *Tiết kiệm pin (Low Power Mode)* hoặc đã cạn budget trong ngày, iOS có thể giãn cách thời gian gọi API.
|
|
853
|
+
> - **Android Doze Mode:** Hệ thống sẽ gom các tác vụ nền định kỳ để chạy cùng lúc nhằm tiết kiệm pin.
|
|
854
|
+
> - **Khuyến nghị:** Nếu ứng dụng của bạn yêu cầu cập nhật chính xác từng giây/phút (như vị trí tài xế, tiến trình đơn hàng), **Server Push Notification (APNs / FCM)** là giải pháp tối ưu nhất, tính năng polling `setRemoteConfig` là giải pháp bổ trợ định kỳ.
|
|
855
|
+
|
|
754
856
|
---
|
|
755
857
|
|
|
756
858
|
## 8. Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity
|