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.
Files changed (53) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +76 -10
  3. package/android/build.gradle +14 -20
  4. package/android/src/main/AndroidManifest.xml +1 -0
  5. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +5 -1
  6. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +8 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +4 -1
  8. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +29 -3
  9. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +26 -1
  10. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +51 -15
  11. package/android/src/main/res/layout/rn_live_widget_host.xml +64 -74
  12. package/docs/GUIDE-EN.md +109 -7
  13. package/docs/GUIDE-VI.md +109 -7
  14. package/docs/index.html +440 -0
  15. package/docs/llms-full.txt +132 -0
  16. package/docs/llms.txt +88 -0
  17. package/ios/Models/DynamicLayoutModels.swift +5 -0
  18. package/ios/Widgets/DynamicHomeScreenWidget.swift +2 -3
  19. package/lib/builder.d.ts.map +1 -1
  20. package/lib/builder.js +29 -19
  21. package/lib/builder.js.map +1 -1
  22. package/lib/dispatcher.d.ts +7 -0
  23. package/lib/dispatcher.d.ts.map +1 -1
  24. package/lib/dispatcher.js +11 -0
  25. package/lib/dispatcher.js.map +1 -1
  26. package/lib/hooks.d.ts +66 -0
  27. package/lib/hooks.d.ts.map +1 -0
  28. package/lib/hooks.js +166 -0
  29. package/lib/hooks.js.map +1 -0
  30. package/lib/index.d.ts +32 -7
  31. package/lib/index.d.ts.map +1 -1
  32. package/lib/index.js +115 -8
  33. package/lib/index.js.map +1 -1
  34. package/lib/jsx.d.ts +79 -0
  35. package/lib/jsx.d.ts.map +1 -0
  36. package/lib/jsx.js +196 -0
  37. package/lib/jsx.js.map +1 -0
  38. package/lib/preview.d.ts +54 -0
  39. package/lib/preview.d.ts.map +1 -0
  40. package/lib/preview.js +466 -0
  41. package/lib/preview.js.map +1 -0
  42. package/lib/types.d.ts +8 -0
  43. package/lib/types.d.ts.map +1 -1
  44. package/package.json +3 -1
  45. package/src/builder.ts +29 -19
  46. package/src/dispatcher.ts +17 -0
  47. package/src/hooks.ts +223 -0
  48. package/src/index.ts +137 -13
  49. package/src/jsx.tsx +296 -0
  50. package/src/preview.tsx +719 -0
  51. package/src/react-ambient.d.ts +10 -0
  52. package/src/react-native-env.d.ts +43 -0
  53. 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
- npm run setup:widgets
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.update('main', { small, medium, large })` in your app, go to the Android Home Screen.
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 (`UI.*`)
316
+ ## 4. Declarative UI Engine
317
317
 
318
- ### `UI.StyleSheet` & Reusable Styling (`StyleProp`)
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
- await Widget.setRemoteConfig({
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
- intervalMinutes: 15, // OS-scheduled background sync every 15 minutes
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
- npm run setup:widgets
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.update('main', { small, medium, large })` trong app, ra màn hình chính (Home Screen) của Android.
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
- ### `UI.StyleSheet` & Tái sử dụng Style (`StyleProp`)
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 có dữ liệu mới từ Server:
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
- await Widget.setRemoteConfig({
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
- intervalMinutes: 15, // Tự động đồng bộ mỗi 15 phút ở tầng OS (WidgetKit Timeline / Android AlarmManager)
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