react-native-live-widgets 0.0.0-stage → 1.0.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 (59) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +21 -0
  3. package/README.md +221 -2
  4. package/android/build.gradle +49 -0
  5. package/android/src/main/AndroidManifest.xml +38 -0
  6. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +440 -0
  7. package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityPackage.kt +17 -0
  8. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +24 -0
  9. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +410 -0
  10. package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +67 -0
  11. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicNodeRegistry.kt +64 -0
  12. package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +1223 -0
  13. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +120 -0
  14. package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +281 -0
  15. package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +229 -0
  16. package/android/src/main/res/layout/rn_live_widget_host.xml +113 -0
  17. package/android/src/main/res/xml/rn_live_widget_info.xml +14 -0
  18. package/assets/dashboard_features.png +0 -0
  19. package/assets/dynamic_island_expanded.png +0 -0
  20. package/assets/home_widget_interactive.png +0 -0
  21. package/assets/lock_screen_live_activity.png +0 -0
  22. package/cli/setup.js +94 -0
  23. package/docs/GUIDE-EN.md +804 -0
  24. package/docs/GUIDE-VI.md +802 -0
  25. package/docs/widgets.md +52 -0
  26. package/ios/Bridge/LiveActivityModule.m +105 -0
  27. package/ios/Bridge/LiveActivityModule.swift +957 -0
  28. package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
  29. package/ios/Models/DynamicActivityAttributes.swift +22 -0
  30. package/ios/Models/DynamicLayoutModels.swift +243 -0
  31. package/ios/Renderer/ColorHexExtension.swift +49 -0
  32. package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
  33. package/ios/Renderer/DynamicNodeView.swift +1060 -0
  34. package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
  35. package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
  36. package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
  37. package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
  38. package/lib/builder.d.ts +60 -0
  39. package/lib/builder.d.ts.map +1 -0
  40. package/lib/builder.js +296 -0
  41. package/lib/builder.js.map +1 -0
  42. package/lib/dispatcher.d.ts +16 -0
  43. package/lib/dispatcher.d.ts.map +1 -0
  44. package/lib/dispatcher.js +23 -0
  45. package/lib/dispatcher.js.map +1 -0
  46. package/lib/index.d.ts +199 -0
  47. package/lib/index.d.ts.map +1 -0
  48. package/lib/index.js +634 -0
  49. package/lib/index.js.map +1 -0
  50. package/lib/types.d.ts +489 -0
  51. package/lib/types.d.ts.map +1 -0
  52. package/lib/types.js +10 -0
  53. package/lib/types.js.map +1 -0
  54. package/package.json +68 -4
  55. package/react-native-live-widgets.podspec +38 -0
  56. package/src/builder.ts +409 -0
  57. package/src/dispatcher.ts +25 -0
  58. package/src/index.ts +681 -0
  59. package/src/types.ts +595 -0
@@ -0,0 +1,802 @@
1
+ # HƯỚNG DẪN SỬ DỤNG VÀ THIẾT LẬP THƯ VIỆN REACT-NATIVE-LIVE-WIDGETS 🚀
2
+
3
+ > 🌐 **Language:** **Tiếng Việt** | [English (GUIDE-EN.md)](./GUIDE-EN.md)
4
+
5
+ Tài liệu hướng dẫn toàn diện từ cài đặt, thiết lập native (iOS/Android), xây dựng giao diện động bằng JavaScript/TypeScript cho cả **Live Activities (Dynamic Island / Lock Screen / Android Live Update)** và **Home Screen Widgets (Tiện ích màn hình chính tương tác đa trang)**.
6
+
7
+ ---
8
+
9
+ ## MỤC LỤC
10
+ 1. [Giới thiệu và Kiến trúc](#1-giới-thiệu-và-kiến-trúc)
11
+ 2. [Cài đặt và Thiết lập Dự án](#2-cài-đặt-và-thiết-lập-dự-án)
12
+ - [Cài đặt package](#cài-đặt-package)
13
+ - [Thiết lập iOS (Xcode & Widget Extension)](#thiết-lập-ios-xcode--widget-extension)
14
+ - [Thiết lập Android (Gradle, Manifest, MainApplication & Permissions)](#thiết-lập-android-gradle-manifest-mainapplication--permissions)
15
+ - [Cấu trúc Thư mục Native của Thư viện (`ios/` & `android/`)](#cấu-trúc-thư-mục-native-của-thư-viện-ios--android)
16
+ 3. [Tài liệu API (Core API Reference)](#3-tài-liệu-api-core-api-reference)
17
+ - [LiveActivity API (Màn hình khóa, Dynamic Island & 3 loại Push Token)](#1-liveactivity-api)
18
+ - [Widget API (Tiện ích màn hình chính, Multi-page & Background Sync)](#2-widget-api)
19
+ - [SharedStorage API (Đồng bộ App Groups & SharedPreferences)](#3-sharedstorage-api)
20
+ 4. [Xây dựng Giao diện Động (Declarative UI Engine)](#4-xây-dựng-giao-diện-động-declarative-ui-engine)
21
+ - [UI.VStack & UI.HStack](#uivstack--uihstack)
22
+ - [UI.Text](#uitext)
23
+ - [UI.Timer (Realtime không tốn pin)](#uitimer-realtime-không-tốn-pin)
24
+ - [UI.Progress (Thanh tiến trình bar, segmented, circular)](#uiprogress-thanh-tiến-trình-đa-dạng)
25
+ - [UI.Equalizer (Sóng nhạc chuyển động liên tục)](#uiequalizer-sóng-nhạc-chuyển-động-liên-tục)
26
+ - [UI.Image (URL mạng, Base64, File, Asset & SF Symbols)](#uiimage-url-mạng-base64-file-asset--sf-symbols)
27
+ - [UI.Button (Tương tác chuyển trang, Tick công việc, Refresh API & Deep Link)](#uibutton-nút-bấm-tương-tác-trực-tiếp-trên-widget)
28
+ 5. [Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)](#5-cấu-hình-dynamic-island-iphone-14-pro-15-16-17)
29
+ 6. [Tạo Home Screen & Lock Screen Widget Đa Dạng bằng JavaScript](#6-tạo-home-screen-widget-đa-trang--tương-tác-bằng-javascript)
30
+ - [Lock Screen Widgets trên iOS (accessoryRectangular, circular, inline)](#lock-screen-widgets-trên-ios)
31
+ - [Ghim Tiện ích vào Màn hình chính trong App (Android In-App Pin)](#ghim-tiện-ích-vào-màn-hình-chính-trong-app-android-in-app-pin)
32
+ 7. [Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)](#7-đồng-bộ-api-ngầm-cho-widget-kể-cả-khi-kill-app-widgetsetremoteconfig)
33
+ 8. [Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity](#8-quản-lý-3-loại-push-token-apns--fcm-cho-live-activity)
34
+ 9. [State Machine & Tự động cập nhật theo pha (Phases)](#9-state-machine--tự-động-cập-nhật-theo-pha-phases)
35
+ 10. [Cấu trúc Payload Server Push (APNs & FCM)](#10-cấu-trúc-payload-server-push-apns--fcm)
36
+ 11. [Xử lý sự cố thường gặp (Troubleshooting)](#11-xử-lý-sự-cố-thường-gặp-troubleshooting)
37
+
38
+ ---
39
+
40
+ ## 1. Giới thiệu và Kiến trúc
41
+
42
+ Thư viện **`react-native-live-widgets`** là giải pháp All-in-One cho phép viết **100% giao diện Widget và Live Activity ngay trong code React Native (`App.tsx`)**, tự động ánh xạ sang Native cho cả iOS và Android:
43
+
44
+ - **Live Activity (iOS 16.1+ ActivityKit & Dynamic Island):** Cho sự kiện thời gian thực (chấm công, chuyến xe, giao đồ ăn, bấm giờ Pomodoro).
45
+ - **Live Update (Android API 24 -> Android 16 API 36 `Notification.ProgressStyle`):** Thông báo thời gian thực trên thanh trạng thái Android có hỗ trợ ảnh đại diện (`LargeIcon`), thanh chia chặng (`segmented`) và các nút bấm tương tác (`Action Buttons`).
46
+ - **Home Screen Widgets (iOS WidgetKit & Android AppWidget Canvas Renderer):** Tiện ích ngoài màn hình chính (`small`, `medium`, `large`) hỗ trợ bấm chuyển trang/tab (`pages`), tick hoàn thành công việc (`toggle`), hiển thị ảnh từ URL mạng/Base64 và tự động gọi API ngầm khi ứng dụng bị tắt.
47
+ - **Shared Storage:** Cầu nối lưu trữ tức thời giữa React Native App và Widgets thông qua iOS App Groups và Android `SharedPreferences`.
48
+
49
+ ---
50
+
51
+ ## 2. Cài đặt và Thiết lập Dự án
52
+
53
+ ### Cài đặt package
54
+ Trong thư mục gốc của dự án React Native:
55
+ ```bash
56
+ npm install react-native-live-widgets
57
+ # hoặc
58
+ yarn add react-native-live-widgets
59
+
60
+ # Tự động cấu hình Info.plist, Entitlements, AndroidManifest và tạo file mẫu Widget
61
+ npx react-native-live-widgets init --group group.com.yourcompany.app
62
+ ```
63
+
64
+ ---
65
+
66
+ ### Thiết lập iOS (Xcode & Widget Extension)
67
+
68
+ #### Bước 1: Kích hoạt Live Activities & App Groups
69
+ Lệnh `npx react-native-live-widgets init` đã tự động thêm vào `Info.plist` và `.entitlements`:
70
+ ```xml
71
+ <key>NSSupportsLiveActivities</key>
72
+ <true/>
73
+ <key>NSSupportsLiveActivitiesFrequentUpdates</key>
74
+ <true/>
75
+ ```
76
+ Và trong `<TênApp>.entitlements` + `LiveWidgetsExtension.entitlements`:
77
+ ```xml
78
+ <key>aps-environment</key>
79
+ <string>development</string>
80
+ <key>com.apple.security.application-groups</key>
81
+ <array>
82
+ <string>group.<bundle_id_của_bạn></string>
83
+ </array>
84
+ ```
85
+
86
+ #### Bước 2: Tạo Widget Extension Target trong Xcode (nếu chưa có)
87
+ 1. Mở file `.xcworkspace` bằng Xcode.
88
+ 2. Chọn menu: **File -> New -> Target... -> Widget Extension**.
89
+ 3. Đặt tên **Product Name:** `LiveWidgets` (hoặc `LiveWidgetsExtension`), bỏ chọn *Include Configuration App Intent*.
90
+ 4. Sử dụng nội dung chuẩn từ thư viện cho `LiveWidgetsBundle.swift`:
91
+ ```swift
92
+ import WidgetKit
93
+ import SwiftUI
94
+ import react_native_live_widgets
95
+
96
+ @main
97
+ struct LiveWidgetsBundle: WidgetBundle {
98
+ var body: some Widget {
99
+ if #available(iOS 16.1, *) {
100
+ DynamicLiveActivityWidget()
101
+ }
102
+ DynamicHomeScreenWidget()
103
+ }
104
+ }
105
+ ```
106
+
107
+ #### Bước 3: Cấu hình `Podfile` và cài đặt Pods
108
+ Trong `ios/Podfile`, đảm bảo target Widget Extension có kế thừa pod `react-native-live-widgets`:
109
+ ```ruby
110
+ target 'LiveWidgetsExtension' do
111
+ use_modular_headers!
112
+ pod 'react-native-live-widgets', :path => '../node_modules/react-native-live-widgets'
113
+ end
114
+ ```
115
+ Sau đó chạy:
116
+ ```bash
117
+ cd ios && pod install
118
+ ```
119
+
120
+ ---
121
+
122
+ ### Thiết lập Android (Gradle, Manifest, MainApplication & Permissions)
123
+
124
+ Trên Android, phần lớn cấu hình phức tạp đã được thư viện **tự động hóa sẵn** thông qua cơ chế **Android Manifest Merger** của Gradle. Dưới đây là chi tiết những gì đã có sẵn và những gì bạn cần kiểm tra trong dự án:
125
+
126
+ #### 1. Những thành phần thư viện đã tự động đăng ký (Bạn KHÔNG cần khai báo lại)
127
+ Trong file `AndroidManifest.xml` của thư viện `react-native-live-widgets` đã tích hợp sẵn và tự động gộp vào app của bạn khi build:
128
+ - **Các quyền hệ thống (Permissions):**
129
+ - `android.permission.INTERNET` (tải ảnh từ URL mạng & gọi Background API cho Widget).
130
+ - `android.permission.POST_NOTIFICATIONS` (hiển thị Live Update Notification trên Android 13+).
131
+ - `android.permission.POST_PROMOTED_NOTIFICATIONS` (hiển thị Live Updates chip trên thanh trạng thái Android 16 / API 36).
132
+ - `android.permission.VIBRATE`.
133
+ - **Home Screen Widget Provider (`DynamicHomeScreenWidgetProvider`):** Đã gắn sẵn bộ cấu hình `@xml/rn_live_widgets_info` hỗ trợ kéo giãn tự do (`resizeMode="horizontal|vertical"`).
134
+ - **Broadcast Receiver (`LiveActivityReceiver`):** Tự động bắt các sự kiện bấm nút trên Notification và Widget.
135
+
136
+ #### 2. Bước 1: Kiểm tra phiên bản SDK trong `android/build.gradle`
137
+ Đảm bảo file `android/build.gradle` của dự án có `minSdkVersion >= 24` và `compileSdkVersion >= 35` (hoặc `36` nếu muốn dùng Live Updates chuẩn Android 16):
138
+ ```groovy
139
+ buildscript {
140
+ ext {
141
+ buildToolsVersion = "35.0.0"
142
+ minSdkVersion = 24
143
+ compileSdkVersion = 35 // Hoặc 36 cho Android 16
144
+ targetSdkVersion = 35
145
+ ndkVersion = "27.1.12297006"
146
+ kotlinVersion = "2.1.20"
147
+ }
148
+ }
149
+ ```
150
+
151
+ #### 3. Bước 2: Kiểm tra `MainApplication.kt`
152
+ Với React Native 0.7x / 0.8x, cơ chế **Autolinking** (`PackageList(this).packages`) sẽ tự động liên kết `LiveActivityPackage`.
153
+ > ⚠️ **Lưu ý quan trọng với React Native 0.80+:** Trong `MainApplication.kt`, bắt buộc phải gọi `loadReactNative(this)` bên trong `onCreate()` để khởi tạo SoLoader/JSI trước khi mở ứng dụng:
154
+ ```kotlin
155
+ package com.yourcompany.app
156
+
157
+ import android.app.Application
158
+ import com.facebook.react.PackageList
159
+ import com.facebook.react.ReactApplication
160
+ import com.facebook.react.ReactHost
161
+ import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
162
+ import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
163
+
164
+ class MainApplication : Application(), ReactApplication {
165
+ override val reactHost: ReactHost by lazy {
166
+ getDefaultReactHost(
167
+ context = applicationContext,
168
+ packageList = PackageList(this).packages, // LiveActivityPackage() đã tự động được thêm tại đây
169
+ )
170
+ }
171
+
172
+ override fun onCreate() {
173
+ super.onCreate()
174
+ loadReactNative(this) // Bắt buộc trên React Native 0.80+
175
+ }
176
+ }
177
+ ```
178
+
179
+ #### 4. Bước 3: Xin quyền Thông báo (Runtime Permission) trên Android 13+ (API 33+)
180
+ Trên Android 13 trở lên, hệ điều hành yêu cầu xin quyền `POST_NOTIFICATIONS` lúc chạy trước khi hiển thị Live Update Notification. Bạn có thể gọi hàm có sẵn của thư viện hoặc dùng `PermissionsAndroid` trong `App.tsx`:
181
+ ```typescript
182
+ import { Platform, PermissionsAndroid } from 'react-native';
183
+ import { LiveActivity } from 'react-native-live-widgets';
184
+
185
+ async function ensureAndroidNotificationPermission() {
186
+ if (Platform.OS === 'android' && Platform.Version >= 33) {
187
+ await PermissionsAndroid.request(
188
+ PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
189
+ );
190
+ }
191
+ // Hoặc gọi trực tiếp hàm đa nền tảng của thư viện:
192
+ await LiveActivity.registerForPushNotifications();
193
+ }
194
+ ```
195
+
196
+ #### 5. Bước 4: Cách thêm và kéo giãn Home Screen Widget trên Android (`small` / `medium` / `large`)
197
+ 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.
198
+ 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.
199
+ 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:
200
+ - 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).
201
+ - Kéo ngang **4×2 ô** (mặc định): Tự động hiển thị giao diện **`medium`**.
202
+ - Kéo giãn dọc xuống **4×4 ô** (`chiều cao >= 200dp`): Tự động hiển thị giao diện **`large`** đầy đủ chi tiết.
203
+
204
+ ---
205
+
206
+ ### Cấu trúc Thư mục Native của Thư viện (`ios/` & `android/`)
207
+
208
+ Mã nguồn native của thư viện được chia theo từng nhóm chức năng rõ ràng để bạn dễ dàng tra cứu hoặc mở rộng khi cần:
209
+
210
+ ```text
211
+ react-native-live-widgets/
212
+ ├── ios/
213
+ │ ├── Bridge/ # LiveActivityModule.swift/.m (Cầu nối React Native <-> iOS)
214
+ │ ├── Models/ # DynamicLayoutModels.swift, DynamicActivityAttributes.swift
215
+ │ ├── Storage/ # DynamicWidgetStateStore.swift, DynamicWidgetImageCache.swift
216
+ │ ├── Intents/ # DynamicWidgetActionIntent.swift (Xử lý nút bấm iOS 17+)
217
+ │ ├── Renderer/ # DynamicNodeView.swift, ColorHexExtension.swift (Vẽ SwiftUI từ JSON)
218
+ │ └── Widgets/ # DynamicHomeScreenWidget.swift, DynamicLiveActivityWidget.swift
219
+ └── android/src/main/java/com/reactnativeliveactivity/
220
+ ├── bridge/ # LiveActivityModule.kt, LiveActivityPackage.kt
221
+ ├── storage/ # DynamicWidgetStateStore.kt, DynamicWidgetImageCache.kt
222
+ ├── renderer/ # DynamicWidgetCanvasRenderer.kt (Vẽ Canvas 2D + tính vùng bấm HitBox)
223
+ ├── widgets/ # DynamicHomeScreenWidgetProvider.kt (Quản lý AppWidget Small/Medium/Large)
224
+ └── liveactivity/ # LiveActivityNotifier.kt, LiveActivityReceiver.kt (Android 8 -> 16 Live Update)
225
+ ```
226
+
227
+ ---
228
+
229
+ ## 3. Tài liệu API (Core API Reference)
230
+
231
+ ```typescript
232
+ import { LiveActivity, Widget, SharedStorage, UI } from 'react-native-live-widgets';
233
+ ```
234
+
235
+ ### 1. `LiveActivity` API
236
+ - `LiveActivity.start(options)`: Khởi chạy Live Activity (iOS) / Live Update Notification (Android). Trả về `{ activityId, activityPushToken }`.
237
+ - `LiveActivity.update(options)`: Cập nhật giao diện và nội dung mới cho `activityId`.
238
+ - `LiveActivity.end(activityId)`: Kết thúc 1 phiên đang chạy.
239
+ - `LiveActivity.endAll()`: Kết thúc toàn bộ các phiên đang chạy.
240
+ - `LiveActivity.registerForPushNotifications()`: Yêu cầu hệ điều hành cấp quyền thông báo và đăng ký APNs Device Token.
241
+ - `LiveActivity.getAllPushTokens(activityId?)`: Lấy trọn bộ 3 loại Push Token (`devicePushToken`, `pushToStartToken`, `activityUpdateToken`).
242
+ - `LiveActivity.getDevicePushToken()`: Lấy APNs Device Token (iOS) hoặc FCM Token đã lưu (Android).
243
+ - `LiveActivity.getPushToStartToken()`: Lấy APNs Push-to-Start Token (iOS 17.2+).
244
+ - `LiveActivity.getActivityPushToken(activityId?)`: Lấy APNs Activity Update Token của phiên đang chạy.
245
+ - `LiveActivity.setDevicePushToken(token)`: Lưu FCM Token trên Android vào bộ quản lý chung.
246
+ - `LiveActivity.onDevicePushTokenChange(cb)` / `onPushToStartTokenChange(cb)` / `onActivityUpdateTokenChange(cb)`: Lắng nghe sự kiện xoay token theo thời gian thực.
247
+
248
+ ### 2. `Widget` API (Tiện ích Màn hình chính & Màn hình khóa)
249
+ - `Widget.setLayout(widgetKey, layoutConfig, appGroup?)`: Cập nhật giao diện động (`small`, `medium`, `large` cho Home Screen; `accessoryRectangular`, `accessoryCircular`, `accessoryInline` cho Lock Screen; `pages`, `initialPage` cho Widget đa trang). Tự động nén và tải trước toàn bộ ảnh từ URL mạng.
250
+ - `Widget.requestPin()`: *(Android 8.0+)* Mở hộp thoại hệ thống cho phép người dùng bấm ghim trực tiếp Tiện ích ra Màn hình chính ngay từ trong ứng dụng mà không cần ra launcher nhấn giữ kéo thả thủ công!
251
+ - `Widget.isPinSupported()`: Kiểm tra xem Launcher của thiết bị hiện tại có hỗ trợ ghim Tiện ích trực tiếp hay không.
252
+ - `Widget.setRemoteConfig(config, widgetKey?, appGroup?)`: Cấu hình URL API để Widget tự động gọi ngầm cập nhật dữ liệu mới kể cả khi người dùng đã vuốt tắt (Kill) App.
253
+ - `Widget.reloadAll()`: Yêu cầu iOS/Android vẽ lại toàn bộ Widget ngay lập tức.
254
+ - `Widget.reload(kind)`: Vẽ lại 1 Widget cụ thể.
255
+ - `Widget.getInteractiveState(widgetKey?, appGroup?)`: Đọc trạng thái tương tác hiện tại trên Widget (`activePage`, `toggledItems`, `lastSyncTime`, `remoteVariables`).
256
+ - `Widget.onWidgetAction(cb)`: Lắng nghe khi người dùng bấm nút trên Widget hoặc Notification.
257
+
258
+ ### 3. `SharedStorage` API
259
+ - `SharedStorage.set(key, value, appGroup?)`: Lưu chuỗi hoặc JSON vào bộ nhớ chung App Group / SharedPreferences.
260
+ - `SharedStorage.get<T>(key, appGroup?)`: Đọc dữ liệu từ bộ nhớ chung.
261
+ - `SharedStorage.remove(key, appGroup?)`: Xóa 1 khóa.
262
+ - `SharedStorage.clear(appGroup?)`: Xóa sạch dữ liệu chung (dùng khi Logout).
263
+
264
+ ### 4. `AudioPlayer` API (Phát nhạc & Kiểm thử sóng Equalizer)
265
+ - `AudioPlayer.play(url)`: Phát bài nhạc trực tiếp từ URL (`.mp3`, `.m4a`, `.aac`, `.wav`) qua loa máy (iOS `AVPlayer` / Android `MediaPlayer`).
266
+ - `AudioPlayer.pause()`: Tạm dừng bài nhạc.
267
+ - `AudioPlayer.resume()`: Tiếp tục phát bài nhạc.
268
+ - `AudioPlayer.stop()`: Dừng bài nhạc và giải phóng bộ nhớ.
269
+ - `AudioPlayer.getStatus()`: Lấy trạng thái phát (`{ isPlaying, currentTime, duration }`).
270
+
271
+ ---
272
+
273
+ ## 4. Xây dựng Giao diện Động (Declarative UI Engine)
274
+
275
+ ### `UI.StyleSheet` & Tái sử dụng Style (`StyleProp`)
276
+ 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:
277
+
278
+ ```typescript
279
+ import { UI } from 'react-native-live-widgets';
280
+
281
+ const styles = UI.StyleSheet.create({
282
+ card: {
283
+ padding: 14,
284
+ backgroundColor: '#0F172A',
285
+ borderRadius: 14,
286
+ spacing: 8,
287
+ },
288
+ headerText: {
289
+ fontSize: 10,
290
+ fontWeight: 'bold',
291
+ color: '#38BDF8',
292
+ },
293
+ titleText: {
294
+ fontSize: 15,
295
+ fontWeight: 'bold',
296
+ color: '#F8FAFC',
297
+ },
298
+ errorText: {
299
+ color: '#EF4444',
300
+ },
301
+ });
302
+
303
+ // Sử dụng đơn lẻ hoặc mảng có điều kiện (conditional styling):
304
+ UI.VStack(
305
+ styles.card,
306
+ UI.Text('TIÊU ĐỀ BÁO CÁO', styles.headerText),
307
+ UI.Text('Trạng thái ca làm', [styles.titleText, isError && styles.errorText])
308
+ );
309
+ ```
310
+
311
+ ### `UI.VStack` & `UI.HStack`
312
+ Khối bố cục dọc (`VStack`) và ngang (`HStack`):
313
+ ```typescript
314
+ UI.VStack(
315
+ {
316
+ padding: 14,
317
+ backgroundColor: '#1A1D24',
318
+ borderRadius: 16,
319
+ spacing: 8,
320
+ alignItems: 'leading', // 'leading' | 'center' | 'trailing'
321
+ },
322
+ // Các phần tử con...
323
+ )
324
+ ```
325
+
326
+ ### `UI.Text`
327
+ Hiển thị văn bản hỗ trợ tự động thay thế biến động `{{field}}` từ Background API và tự gạch ngang chữ khi gắn `strikethroughWhenToggled`:
328
+ ```typescript
329
+ UI.Text('Check-in lúc {{checkinTime}}', {
330
+ color: '#FFFFFF',
331
+ fontSize: 15,
332
+ fontWeight: 'bold',
333
+ maxLines: 1,
334
+ strikethroughWhenToggled: 'task_1', // Tự động gạch ngang và làm mờ khi 'task_1' được tick!
335
+ })
336
+ ```
337
+
338
+ ### `UI.Timer` (Realtime không tốn pin)
339
+ Đồng hồ đếm ngược (`countdown`) hoặc đếm lên (`countup`) tự chạy mượt mà trên cả Lock Screen, Dynamic Island và Home Screen Widget:
340
+ ```typescript
341
+ UI.Timer(targetTimestampInSeconds, {
342
+ mode: 'countdown',
343
+ color: '#FFA500',
344
+ fontSize: 16,
345
+ fontWeight: 'bold',
346
+ showsHours: false, // Tắt hiển thị giờ để gọn gàng trên Dynamic Island Compact
347
+ })
348
+ ```
349
+
350
+ ### `UI.Progress` (Thanh tiến trình đa dạng)
351
+ Hỗ trợ 3 kiểu dáng: `'bar'` (thanh liền), `'segmented'` (thanh chia nhiều chặng kiểu giao hàng/ca làm việc), và `'circular'` (vòng tròn tiến độ):
352
+ ```typescript
353
+ // 1. Thanh chia 4 chặng (Segmented)
354
+ UI.Progress({
355
+ style: 'segmented',
356
+ segments: 4,
357
+ currentSegment: 3, // Hoặc truyền value: 0.75
358
+ tintColor: '#10B981',
359
+ trackColor: '#374151',
360
+ segmentSpacing: 6,
361
+ height: 8,
362
+ })
363
+
364
+ // 2. Vòng tròn tiến độ (Circular)
365
+ UI.Progress({
366
+ style: 'circular',
367
+ value: 0.68,
368
+ tintColor: '#10B981',
369
+ trackColor: '#064E3B',
370
+ height: 64,
371
+ showPercentage: true,
372
+ })
373
+ ```
374
+
375
+ ### `UI.Equalizer` (Sóng nhạc chuyển động liên tục)
376
+ Component sóng nhạc / âm thanh động chuyên dụng. Trên Dynamic Island và Live Activity màn hình khóa (iOS), component tự động chạy nhịp sóng dao động liên tục thời gian thực (Native TimelineView Animation) mượt mà mà không tốn pin; trên Android và Home Screen hiển thị các thanh sóng nhạc trực quan:
377
+ ```typescript
378
+ // 1. Dùng trong Dynamic Island (compactTrailing hoặc minimal)
379
+ UI.Equalizer({
380
+ isPlaying: true, // true: sóng nhảy liên tục | false: đứng yên
381
+ barCount: 4, // Số thanh sóng nhạc (2 đến 8)
382
+ tintColor: '#10B981', // Màu sắc thanh sóng (Spotify / Apple Music green)
383
+ height: 14, // Chiều cao thanh
384
+ barWidth: 3, // Độ rộng mỗi thanh
385
+ spacing: 2, // Khoảng cách giữa các thanh
386
+ })
387
+
388
+ // 2. Dùng trong Widget nghe nhạc ngoài Home Screen / Lock Screen
389
+ UI.Equalizer({
390
+ isPlaying: true,
391
+ barCount: 5,
392
+ tintColor: '#FFFFFF',
393
+ height: 18,
394
+ })
395
+ ```
396
+
397
+ ### `UI.Image` (URL mạng, Base64, File, Asset & SF Symbols)
398
+ Hỗ trợ truyền ảnh từ **5 nguồn khác nhau** trên cả iOS và Android. Khi truyền `url` (`https://...`), thư viện sẽ tự động tải ngầm, nén ảnh tối ưu RAM (`maxDimension = 360px` để không bao giờ vượt giới hạn 30MB của iOS WidgetKit) và lưu vào bộ nhớ đệm:
399
+ ```typescript
400
+ // 1. Ảnh từ URL mạng (Avatar tròn có viền)
401
+ UI.Image({
402
+ url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=300&q=80',
403
+ width: 44,
404
+ height: 44,
405
+ cornerRadius: 999, // 999 = Bo tròn hoàn toàn (Circle)
406
+ contentMode: 'fill', // 'fill' | 'fit'
407
+ borderColor: '#60A5FA', // Màu viền
408
+ borderWidth: 2, // Độ dày viền
409
+ })
410
+
411
+ // 2. Ảnh từ chuỗi Base64 (QR Code, Barcode, Badge...)
412
+ UI.Image({
413
+ base64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...',
414
+ width: 36,
415
+ height: 36,
416
+ cornerRadius: 8,
417
+ })
418
+
419
+ // 3. Icon hệ thống (SF Symbols trên iOS / Vector Mapping trên Android)
420
+ UI.Image({
421
+ systemName: 'bicycle',
422
+ tintColor: '#FB923C',
423
+ width: 18,
424
+ height: 18,
425
+ })
426
+ ```
427
+
428
+ ### `UI.Button` (Nút bấm tương tác trực tiếp trên Widget)
429
+ Cho phép người dùng thao tác ngay trên mặt Widget (iOS 17+ `AppIntents` & Android `PendingIntent` Hit Zones) mà **không cần mở ứng dụng**:
430
+ ```typescript
431
+ // 1. Nút chuyển sang trang/tab khác trên Widget
432
+ UI.Button({
433
+ title: 'Việc cần làm →',
434
+ actionId: 'page:tasks', // Hoặc 'page:next' / 'page:prev'
435
+ backgroundColor: '#2563EB',
436
+ color: '#FFFFFF',
437
+ fontSize: 11,
438
+ paddingHorizontal: 10,
439
+ paddingVertical: 5,
440
+ borderRadius: 8,
441
+ })
442
+
443
+ // 2. Nút Tick hoàn thành công việc ngay trên Widget
444
+ UI.Button({
445
+ title: 'Duyệt PR module chấm công',
446
+ actionId: 'toggle:task_1', // Tự động đổi [ ] <-> [✓]
447
+ backgroundColor: '#F8FAFC',
448
+ activeBackgroundColor: '#DCFCE7',
449
+ color: '#1E293B',
450
+ activeColor: '#15803D',
451
+ })
452
+
453
+ // 3. Nút gọi API làm mới dữ liệu ngầm ngay lập tức
454
+ UI.Button({
455
+ title: '↻ Làm mới',
456
+ actionId: 'refresh',
457
+ backgroundColor: '#1E293B',
458
+ color: '#60A5FA',
459
+ })
460
+ ```
461
+
462
+ ### `UI.ZStack`, `UI.Grid` & `UI.Divider` (Bố cục nâng cao)
463
+ ```typescript
464
+ // 1. ZStack: Xếp chồng các lớp (Overlay)
465
+ UI.ZStack(
466
+ { zAlignment: 'bottomTrailing' },
467
+ UI.Image('https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200', { width: 44, height: 44, borderRadius: 22 }),
468
+ UI.Badge('●', { backgroundColor: '#10B981', textColor: '#FFFFFF', fontSize: 8 })
469
+ )
470
+
471
+ // 2. Grid: Chia lưới nhiều cột đều nhau (Bảng thống kê 2x2 KPI)
472
+ UI.Grid(
473
+ { columns: 2, columnSpacing: 8, rowSpacing: 8 },
474
+ UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Doanh thu', { fontSize: 10, color: '#94A3B8' }), UI.Text('4.85 Tỷ', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' })),
475
+ UI.VStack({ padding: 8, backgroundColor: '#1E293B', borderRadius: 8 }, UI.Text('Đơn hàng', { fontSize: 10, color: '#94A3B8' }), UI.Text('1,420', { fontSize: 14, fontWeight: 'bold', color: '#34D399' }))
476
+ )
477
+
478
+ // 3. Divider: Đường kẻ phân cách ngang/dọc
479
+ UI.Divider({ color: '#334155', thickness: 1, marginVertical: 4 })
480
+ ```
481
+
482
+ ### `UI.Gauge` & `UI.Chart` (Đồng hồ đo KPI & Biểu đồ Cột / Đường Sparkline)
483
+ ```typescript
484
+ // 1. Đồng hồ đo tốc độ / KPI cung tròn 240° (Gauge)
485
+ UI.Gauge(0.86, {
486
+ size: 66,
487
+ tintColor: '#38BDF8',
488
+ trackColor: '#1E293B',
489
+ textColor: '#F8FAFC',
490
+ labelColor: '#94A3B8',
491
+ valueText: '86%',
492
+ label: 'KPI Quý',
493
+ })
494
+
495
+ // 2. Biểu đồ Cột ('bar') hoặc Đường xu hướng ('line')
496
+ UI.Chart([42, 58, 51, 74, 68, 92, 108], {
497
+ style: 'bar', // 'bar' | 'line'
498
+ labels: ['T2', 'T3', 'T4', 'T5', 'T6', 'T7', 'CN'],
499
+ tintColor: '#38BDF8',
500
+ secondaryColor: '#1E3A8A',
501
+ labelColor: '#94A3B8',
502
+ height: 48,
503
+ })
504
+ ```
505
+
506
+ ### `UI.Toggle`, `UI.Badge` & `UI.Link`
507
+ ```typescript
508
+ // 1. Toggle: Ô tích Checkbox hoặc Công tắc gạt Switch ngay trên mặt Widget
509
+ UI.Toggle('Duyệt báo cáo doanh thu tuần', {
510
+ actionId: 'toggle:kpi_approve',
511
+ style: 'checkbox', // 'checkbox' | 'switch'
512
+ tintColor: '#38BDF8',
513
+ textColor: '#F8FAFC',
514
+ })
515
+
516
+ // 2. Badge: Nhãn trạng thái dạng viên thuốc (Pill / Capsule)
517
+ UI.Badge('+18% Vượt chỉ tiêu', {
518
+ backgroundColor: '#064E3B',
519
+ textColor: '#34D399',
520
+ fontSize: 10,
521
+ })
522
+
523
+ // 3. Link: Biến cả một khối giao diện thành vùng bấm mở Deep Link hoặc chạy Action
524
+ UI.Link(
525
+ { deepLink: 'livewidgets://analytics/q4', padding: 10, backgroundColor: '#1E293B', borderRadius: 10 },
526
+ UI.Text('Xem chi tiết báo cáo →', { fontSize: 12, fontWeight: 'bold', color: '#38BDF8' })
527
+ )
528
+ ```
529
+
530
+ ### `UI.Custom` & `DynamicNodeRegistry` (Tự mở rộng Component Native tùy ý bằng Swift / Kotlin)
531
+ Nếu bạn muốn tự viết một Component riêng bằng **SwiftUI** hoặc **Kotlin Canvas** mà không cần sửa code lõi của thư viện:
532
+
533
+ 1. **Đăng ký bên iOS (Swift — trong `LiveWidgetsBundle.swift`):**
534
+ ```swift
535
+ import SwiftUI
536
+ import react_native_live_widgets
537
+
538
+ // Đăng ký Custom View theo tên "WeatherCard"
539
+ DynamicNodeRegistry.shared.registerView("WeatherCard") { node in
540
+ let city = node.props?["city"]?.stringValue ?? "Hà Nội"
541
+ let temp = node.props?["temp"]?.stringValue ?? "28°C"
542
+ HStack {
543
+ Image(systemName: "sun.max.fill").foregroundColor(.yellow)
544
+ Text("\(city): \(temp)").font(.headline)
545
+ }
546
+ }
547
+ ```
548
+
549
+ 2. **Đăng ký bên Android (Kotlin — trong `MainApplication.onCreate()`):**
550
+ ```kotlin
551
+ import com.reactnativeliveactivity.DynamicNodeRegistry
552
+
553
+ DynamicNodeRegistry.register(
554
+ componentName = "WeatherCard",
555
+ heightDp = { 44f },
556
+ drawer = { context, canvas, rect, props, density ->
557
+ // Tự vẽ tự do lên Android Canvas
558
+ }
559
+ )
560
+ ```
561
+
562
+ 3. **Gọi trực tiếp từ React Native (`App.tsx`):**
563
+ ```typescript
564
+ UI.Custom('WeatherCard', { city: 'TP.HCM', temp: '31°C' })
565
+ ```
566
+
567
+ ---
568
+
569
+ ## 5. Cấu hình Dynamic Island (iPhone 14 Pro, 15, 16, 17)
570
+
571
+ ```typescript
572
+ dynamicIsland: {
573
+ compactLeading: UI.HStack(
574
+ { spacing: 4 },
575
+ UI.Image({
576
+ url: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=200&q=80',
577
+ width: 18,
578
+ height: 18,
579
+ cornerRadius: 999,
580
+ }),
581
+ UI.Text('08:02', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' })
582
+ ),
583
+ compactTrailing: UI.Timer(shiftEndTimestamp, {
584
+ mode: 'countdown',
585
+ color: '#60A5FA',
586
+ fontSize: 12,
587
+ fontWeight: 'bold',
588
+ showsHours: false,
589
+ }),
590
+ minimal: UI.Image({ systemName: 'clock.fill', tintColor: '#60A5FA', width: 14, height: 14 }),
591
+ expanded: {
592
+ leading: UI.Text('ĐANG TRONG CA', { color: '#60A5FA', fontSize: 12, fontWeight: 'bold' }),
593
+ trailing: UI.Timer(shiftEndTimestamp, { mode: 'countdown', color: '#FFFFFF', fontSize: 14, fontWeight: 'bold' }),
594
+ bottom: UI.VStack(
595
+ { spacing: 6 },
596
+ UI.Progress({ style: 'segmented', segments: 4, value: 0.75, tintColor: '#3B82F6', height: 6 }),
597
+ UI.Text('Check-in: Văn phòng Quận 1', { color: '#94A3B8', fontSize: 11 })
598
+ ),
599
+ },
600
+ }
601
+ ```
602
+
603
+ ---
604
+
605
+ ## 6. Tạo Home Screen Widget Đa Trang & Tương Tác bằng JavaScript
606
+
607
+ Bạn có thể truyền thuộc tính `pages` vào `Widget.setLayout` để tạo nhiều màn hình (Tabs/Pages) ngay bên trong 1 Widget duy nhất:
608
+
609
+ ```typescript
610
+ await Widget.setLayout('main', {
611
+ initialPage: 'overview',
612
+ // Mặc định (trang Tổng quan)
613
+ medium: overviewPageNode,
614
+ // Khai báo các trang để chuyển qua lại bằng actionId: 'page:<tên_trang>'
615
+ pages: {
616
+ overview: {
617
+ small: overviewSmallNode,
618
+ medium: overviewMediumNode,
619
+ large: overviewLargeNode,
620
+ },
621
+ tasks: {
622
+ small: tasksSmallNode,
623
+ medium: tasksMediumNode,
624
+ large: tasksLargeNode,
625
+ },
626
+ stats: {
627
+ small: statsSmallNode,
628
+ medium: statsMediumNode,
629
+ large: statsLargeNode,
630
+ },
631
+ },
632
+ });
633
+ ```
634
+
635
+ ### Lock Screen Widgets trên iOS
636
+ Từ iOS 16+, WidgetKit hỗ trợ 3 kích thước đặc biệt trên màn hình khóa (Lock Screen):
637
+ - `accessoryRectangular`: Khung chữ nhật nằm ngang phía dưới đồng hồ.
638
+ - `accessoryCircular`: Biểu tượng / chỉ số tròn nhỏ.
639
+ - `accessoryInline`: Dòng chữ vắn tắt nằm ngay phía trên đồng hồ.
640
+
641
+ > [!NOTE]
642
+ > Thư viện tự động loại bỏ nền opaque (`backgroundColor`) và căn chỉnh padding chuẩn xác để widget màn hình khóa hiển thị tự nhiên với hệ số trong suốt (vibrancy) của iOS.
643
+
644
+ ```typescript
645
+ await Widget.setLayout('main', {
646
+ // Widget Home Screen
647
+ small: smallNode,
648
+ medium: mediumNode,
649
+ large: largeNode,
650
+
651
+ // Widget Lock Screen (iOS 16+)
652
+ accessoryRectangular: UI.HStack(
653
+ { spacing: 6 },
654
+ UI.VStack(
655
+ { spacing: 2 },
656
+ UI.Text('Starboy', { fontSize: 13, fontWeight: 'bold', color: '#FFFFFF' }),
657
+ UI.Text('The Weeknd', { fontSize: 11, color: '#CCCCCC' })
658
+ ),
659
+ UI.Spacer(),
660
+ UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 16 })
661
+ ),
662
+ accessoryCircular: UI.VStack(
663
+ { spacing: 2 },
664
+ UI.Equalizer({ isPlaying: true, barCount: 4, tintColor: '#FFFFFF', height: 18 }),
665
+ UI.Text('MUSIC', { fontSize: 8, fontWeight: 'bold', color: '#FFFFFF' })
666
+ ),
667
+ accessoryInline: UI.Text('♪ Starboy • The Weeknd', { fontSize: 12, fontWeight: 'medium' }),
668
+ });
669
+ ```
670
+
671
+ ### Ghim Tiện ích vào Màn hình chính trong App (Android In-App Pin)
672
+ Trên Android 8.0+ (API 26+), bạn có thể hiển thị nút trong ứng dụng để người dùng bấm ghim ngay tiện ích ra màn hình chính mà không cần hướng dẫn người dùng nhấn giữ màn hình thủ công:
673
+
674
+ ```typescript
675
+ import { Widget } from 'react-native-live-widgets';
676
+
677
+ // Kiểm tra xem Launcher hiện tại có hỗ trợ ghim hay không
678
+ const isSupported = await Widget.isPinSupported();
679
+
680
+ if (isSupported) {
681
+ // Yêu cầu hệ điều hành hiện hộp thoại ghim Widget
682
+ const success = await Widget.requestPin();
683
+ if (success) {
684
+ console.log('Hệ thống đã nhận yêu cầu ghim tiện ích');
685
+ }
686
+ }
687
+ ```
688
+
689
+ ---
690
+
691
+ ## 7. Đồng bộ API Ngầm cho Widget kể cả khi Kill App (`Widget.setRemoteConfig`)
692
+
693
+ 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:
694
+
695
+ ```typescript
696
+ await Widget.setRemoteConfig({
697
+ url: 'https://api.yourcompany.com/v1/widget-summary',
698
+ method: 'GET',
699
+ headers: {
700
+ Authorization: `Bearer ${accessToken}`,
701
+ },
702
+ intervalMinutes: 15, // Tự động đồng bộ mỗi 15 phút ở tầng OS (WidgetKit Timeline / Android AlarmManager)
703
+ });
704
+ ```
705
+
706
+ - **Cách hoạt động:**
707
+ - Trên **iOS**: `DynamicWidgetProvider` tự động gọi API ngầm mỗi `intervalMinutes` (hoặc ngay lập tức khi bấm nút `actionId: 'refresh'`), lấy JSON trả về và điền vào các biến `{{ten_bien}}` trong cây UI DSL.
708
+ - Trên **Android**: `AlarmManager` tự động đánh thức `LiveActivityReceiver` (`ACTION_WIDGET_SYNC`), tải JSON mới và vẽ lại `DynamicHomeScreenWidgetProvider`.
709
+ - 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`).
710
+
711
+ ---
712
+
713
+ ## 8. Quản lý 3 loại Push Token (APNs & FCM) cho Live Activity
714
+
715
+ Để hệ thống Backend có thể điều khiển Live Activity từ xa:
716
+ 1. **`devicePushToken`**: APNs Device Token (iOS) / FCM Token (Android) cho thông báo đẩy thường.
717
+ 2. **`pushToStartToken` (iOS 17.2+)**: Token cho phép Server tự bật mới một Live Activity từ xa khi App đang tắt.
718
+ 3. **`activityUpdateToken`**: Token riêng của từng phiên Live Activity đang chạy để Server đẩy bản cập nhật hoặc kết thúc phiên đó.
719
+
720
+ ```typescript
721
+ // 1. Xin quyền và đăng ký nhận token
722
+ await LiveActivity.registerForPushNotifications();
723
+
724
+ // 2. Lấy toàn bộ 3 loại token hiện có
725
+ const tokens = await LiveActivity.getAllPushTokens();
726
+ console.log(tokens.devicePushToken, tokens.pushToStartToken, tokens.activityUpdateToken);
727
+
728
+ // 3. Lắng nghe token mới được cấp hoặc xoay tự động
729
+ const sub1 = LiveActivity.onDevicePushTokenChange(({ token }) => {
730
+ api.syncDeviceToken(token);
731
+ });
732
+ const sub2 = LiveActivity.onPushToStartTokenChange((token) => {
733
+ api.syncPushToStartToken(token);
734
+ });
735
+ const sub3 = LiveActivity.onActivityUpdateTokenChange(({ activityId, token }) => {
736
+ api.syncActivityUpdateToken(activityId, token);
737
+ });
738
+ ```
739
+
740
+ ---
741
+
742
+ ## 9. State Machine & Tự động cập nhật theo pha (Phases)
743
+
744
+ ```typescript
745
+ phases: [
746
+ {
747
+ id: 'warning_phase',
748
+ triggerTimestamp: targetTimestamp - 300, // Trước 5 phút
749
+ alertTitle: 'Sắp trễ ca!',
750
+ alertBody: 'Chỉ còn 5 phút nữa là vào ca làm!',
751
+ },
752
+ {
753
+ id: 'late_phase',
754
+ triggerTimestamp: targetTimestamp, // Đã đến giờ
755
+ alertTitle: 'Đã trễ ca!',
756
+ alertBody: 'Bạn đã quá giờ ca làm việc!',
757
+ },
758
+ ]
759
+ ```
760
+
761
+ ---
762
+
763
+ ## 10. Cấu trúc Payload Server Push (APNs & FCM)
764
+
765
+ ### Headers gửi lên APNs (iOS Live Activity):
766
+ - `apns-push-type`: `liveactivity`
767
+ - `apns-topic`: `<bundle_id>.push-type.liveactivity`
768
+ - `apns-priority`: `10`
769
+
770
+ ### Body JSON gửi lên APNs:
771
+ ```json
772
+ {
773
+ "aps": {
774
+ "timestamp": 1711890000,
775
+ "event": "update",
776
+ "content-state": {
777
+ "layoutJson": "{\"lockScreen\":{...},\"dynamicIsland\":{...}}"
778
+ },
779
+ "alert": {
780
+ "title": "Đơn hàng đã giao!",
781
+ "body": "Chúc bạn ngon miệng."
782
+ }
783
+ }
784
+ }
785
+ ```
786
+
787
+ ---
788
+
789
+ ## 11. Xử lý sự cố thường gặp (Troubleshooting)
790
+
791
+ 1. **Widget ngoài màn hình chính hiển thị chữ "Chọn 1 mẫu UI trong app để hiển thị":**
792
+ - Kiểm tra App Group ID giữa Main App và Widget Extension đã khớp nhau chưa (mặc định thư viện tự động dò `group.<bundle_id>`).
793
+ - Đảm bảo đã gọi `await Widget.setLayout('main', ...)` trong code React Native.
794
+ 2. **Dynamic Island Compact bị tràn chiều ngang khi dùng `UI.Timer`:**
795
+ - Truyền `showsHours: false` vào `UI.Timer` ở `compactTrailing`. Thư viện đã tự động giới hạn khung `compactWidth` để không làm giãn viên thuốc Dynamic Island.
796
+ 3. **Ảnh từ URL mạng (`https://...`) không hiện trên Widget:**
797
+ - Đảm bảo URL ảnh là `https://` hợp lệ. Thư viện sẽ tự động tải, nén xuống `360px` và reload lại Widget ngay khi tải xong.
798
+
799
+ ---
800
+
801
+ ## 📄 License
802
+ MIT © vu-tran