react-native-live-widgets 0.0.0-stage → 1.1.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 +21 -0
- package/LICENSE +21 -0
- package/README.md +367 -2
- package/android/build.gradle +49 -0
- package/android/src/main/AndroidManifest.xml +38 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityModule.kt +441 -0
- package/android/src/main/java/com/reactnativeliveactivity/bridge/LiveActivityPackage.kt +17 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityHeadlessTaskService.kt +24 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityNotifier.kt +410 -0
- package/android/src/main/java/com/reactnativeliveactivity/liveactivity/LiveActivityReceiver.kt +67 -0
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicNodeRegistry.kt +64 -0
- package/android/src/main/java/com/reactnativeliveactivity/renderer/DynamicWidgetCanvasRenderer.kt +1223 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetImageCache.kt +120 -0
- package/android/src/main/java/com/reactnativeliveactivity/storage/DynamicWidgetStateStore.kt +281 -0
- package/android/src/main/java/com/reactnativeliveactivity/widgets/DynamicHomeScreenWidgetProvider.kt +229 -0
- package/android/src/main/res/layout/rn_live_widget_host.xml +113 -0
- package/android/src/main/res/xml/rn_live_widget_info.xml +14 -0
- package/app.plugin.js +114 -0
- package/assets/cross_platform_parity.png +0 -0
- package/assets/dashboard_features.png +0 -0
- package/assets/donate_qr.png +0 -0
- package/assets/dynamic_island_expanded.png +0 -0
- package/assets/home_widget_interactive.png +0 -0
- package/assets/lock_screen_live_activity.png +0 -0
- package/cli/setup.js +491 -0
- package/docs/EXPO-GUIDE-EN.md +405 -0
- package/docs/EXPO-GUIDE-VI.md +427 -0
- package/docs/GUIDE-EN.md +847 -0
- package/docs/GUIDE-VI.md +845 -0
- package/docs/widgets.md +52 -0
- package/ios/Bridge/LiveActivityModule.m +105 -0
- package/ios/Bridge/LiveActivityModule.swift +957 -0
- package/ios/Intents/DynamicWidgetActionIntent.swift +38 -0
- package/ios/Models/DynamicActivityAttributes.swift +22 -0
- package/ios/Models/DynamicLayoutModels.swift +243 -0
- package/ios/Renderer/ColorHexExtension.swift +49 -0
- package/ios/Renderer/DynamicNodeRegistry.swift +54 -0
- package/ios/Renderer/DynamicNodeView.swift +1060 -0
- package/ios/Storage/DynamicWidgetImageCache.swift +137 -0
- package/ios/Storage/DynamicWidgetStateStore.swift +162 -0
- package/ios/Widgets/DynamicHomeScreenWidget.swift +435 -0
- package/ios/Widgets/DynamicLiveActivityWidget.swift +79 -0
- package/lib/builder.d.ts +60 -0
- package/lib/builder.d.ts.map +1 -0
- package/lib/builder.js +292 -0
- package/lib/builder.js.map +1 -0
- package/lib/dispatcher.d.ts +16 -0
- package/lib/dispatcher.d.ts.map +1 -0
- package/lib/dispatcher.js +18 -0
- package/lib/dispatcher.js.map +1 -0
- package/lib/index.d.ts +199 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +621 -0
- package/lib/index.js.map +1 -0
- package/lib/types.d.ts +489 -0
- package/lib/types.d.ts.map +1 -0
- package/lib/types.js +9 -0
- package/lib/types.js.map +1 -0
- package/package.json +85 -4
- package/react-native-live-widgets.podspec +38 -0
- package/src/builder.ts +409 -0
- package/src/dispatcher.ts +25 -0
- package/src/index.ts +689 -0
- package/src/react-native-env.d.ts +29 -0
- package/src/types.ts +595 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `react-native-live-widgets` will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [1.1.0] - 2026-11-16
|
|
6
|
+
### Added
|
|
7
|
+
- **Expo Config Plugin (`app.plugin.js`)**: Full Expo & EAS Build support (`npx expo prebuild` / `npx expo run:ios` / `npx expo run:android`). Automatically configures `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` in iOS `Info.plist`, App Groups entitlements, and Android notifications & foreground service permissions.
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
- **TypeScript Module Resolution**: Fixed `error TS7016` when resolving React Native package exports by updating to `moduleResolution: bundler` and `module: ES2020`.
|
|
11
|
+
- **Global `__DEV__` Declaration**: Fixed `error TS2304: Cannot find name '__DEV__'` with safe typing and fallback checks.
|
|
12
|
+
|
|
13
|
+
## [1.0.0] - 2026-11-15
|
|
14
|
+
### Added
|
|
15
|
+
- **Declarative UI Engine (`UI.*`)**: Build Home Screen Widgets (`small`, `medium`, `large`) and Live Activities (`lockScreen`, `dynamicIsland`) 100% in React Native using `UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Timer`, `UI.Progress` (`bar`, `segmented`, `circular`), `UI.Image`, and `UI.Button`.
|
|
16
|
+
- **Interactive Multi-Page & Checklist Widgets (iOS & Android)**: In-place page switching (`actionId: 'page:<id>'`, `'page:next'`, `'page:prev'`) and task checklist toggling (`actionId: 'toggle:<key>'`) via iOS 17+ `AppIntents` and Android `PendingIntent` hit zones.
|
|
17
|
+
- **Background API Auto-Sync (`Widget.setRemoteConfig`)**: Autonomous background HTTP JSON fetch and `{{field}}` template interpolation even when the main app is force-killed.
|
|
18
|
+
- **Multi-Source Image Loader & Cache (`UI.Image`)**: Remote `https://` URLs (auto-prefetched, downscaled to `360px` max dimension, and cached), `base64`, `filePath`, `assetName`, and `systemName` (SF Symbols / Android Vector mapping).
|
|
19
|
+
- **Unified Push Token Management**: `devicePushToken`, `pushToStartToken` (iOS 17.2+), and `activityUpdateToken` across iOS APNs and Android FCM.
|
|
20
|
+
- **CLI Setup Wizard**: `npx react-native-live-widgets init` for automatic iOS & Android project configuration.
|
|
21
|
+
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 vu-tran
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,368 @@
|
|
|
1
|
-
#
|
|
1
|
+
# react-native-live-widgets 🚀
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/react-native-live-widgets)
|
|
6
|
+
[](https://expo.dev)
|
|
7
|
+
[](https://github.com/React-Native-Vu/react-native-live-widgets)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
**The Ultimate All-in-One Engine for Live Activities, Dynamic Island, and Interactive Home Screen Widgets in React Native & Expo.**
|
|
12
|
+
|
|
13
|
+
*Write 100% Declarative TypeScript. Render dynamically to Native SwiftUI (WidgetKit) & Android 2D Canvas without touching Xcode or Android Studio.*
|
|
14
|
+
|
|
15
|
+
[📖 English Guide](docs/GUIDE-EN.md) • [🇻🇳 Hướng dẫn Tiếng Việt](docs/GUIDE-VI.md) • [⚡ Expo Guide](docs/EXPO-GUIDE-VI.md) • [📱 Bare RN Demo](https://github.com/React-Native-Vu/LiveWidgetsExample) • [⚡ Expo Demo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo) • [✨ Tính năng](#-key-features) • [⚡ Cài đặt](#-quick-start) • [☕ Ủng hộ tác giả](#-sponsor--donate-ủng-hộ-tác-giả)
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
## 📱 Live Demo Example Apps
|
|
22
|
+
|
|
23
|
+
Full, ready-to-run demo applications are available on GitHub for both architectures:
|
|
24
|
+
|
|
25
|
+
| Platform | Repository | Description |
|
|
26
|
+
| :--- | :--- | :--- |
|
|
27
|
+
| **⚛️ Bare React Native CLI** | 👉 **[React-Native-Vu/LiveWidgetsExample](https://github.com/React-Native-Vu/LiveWidgetsExample)** | Full Xcode Widget Extension & Android Studio setup |
|
|
28
|
+
| **🚀 Expo (SDK 58 / CNG)** | 👉 **[React-Native-Vu/LiveWidgetsExampleExpo](https://github.com/React-Native-Vu/LiveWidgetsExampleExpo)** | Continuous Native Generation via Expo Config Plugin |
|
|
29
|
+
|
|
30
|
+
### ✨ Highlights of Both Demos:
|
|
31
|
+
- 🚀 **100% Pre-configured**: Xcode App Groups, `WidgetExtension`, and Android `AppWidgetProvider` ready out of the box.
|
|
32
|
+
- 🎨 **5 Real-world Presets**:
|
|
33
|
+
1. **Executive KPI Dashboard**: Live sales sync, circular progress ring, and weekly chart.
|
|
34
|
+
2. **Coffee Delivery Tracker**: Dynamic Island countdown and delivery driver status.
|
|
35
|
+
3. **Interactive Task Checklist**: Check off items right from your Home Screen without opening the app.
|
|
36
|
+
4. **Music & Audio Player**: Dynamic Island equalizer animation and lock screen media style.
|
|
37
|
+
5. **Flight Status**: Real-time gate, departure time, and airport progress bar.
|
|
38
|
+
- 🔄 **Bidirectional Real-Time Sync**: Instant state updates between Main App and WidgetKit.
|
|
39
|
+
|
|
40
|
+
#### 1. Clone & Run Bare React Native Demo:
|
|
41
|
+
```bash
|
|
42
|
+
git clone https://github.com/React-Native-Vu/LiveWidgetsExample.git
|
|
43
|
+
cd LiveWidgetsExample && npm install
|
|
44
|
+
npx react-native run-ios # or npx react-native run-android
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
#### 2. Clone & Run Expo Demo:
|
|
48
|
+
```bash
|
|
49
|
+
git clone https://github.com/React-Native-Vu/LiveWidgetsExampleExpo.git
|
|
50
|
+
cd LiveWidgetsExampleExpo && npm install
|
|
51
|
+
npx expo prebuild
|
|
52
|
+
npx expo run:ios # or npx expo run:android
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 📸 Showcase & Demos
|
|
58
|
+
|
|
59
|
+
<div align="center">
|
|
60
|
+
<table>
|
|
61
|
+
<tr>
|
|
62
|
+
<td width="50%" align="center">
|
|
63
|
+
<b>🏝️ Dynamic Island Expanded & KPI Dashboard</b><br/><br/>
|
|
64
|
+
<img src="assets/dynamic_island_expanded.png" alt="Dynamic Island Expanded" width="380" />
|
|
65
|
+
</td>
|
|
66
|
+
<td width="50%" align="center">
|
|
67
|
+
<b>📱 Interactive Home Screen Widget (iOS)</b><br/><br/>
|
|
68
|
+
<img src="assets/home_widget_interactive.png" alt="Home Screen Widget Interactive" width="380" />
|
|
69
|
+
</td>
|
|
70
|
+
</tr>
|
|
71
|
+
<tr>
|
|
72
|
+
<td width="50%" align="center">
|
|
73
|
+
<b>🔒 Lock Screen Live Activity & Gauges</b><br/><br/>
|
|
74
|
+
<img src="assets/lock_screen_live_activity.png" alt="Lock Screen Live Activity" width="380" />
|
|
75
|
+
</td>
|
|
76
|
+
<td width="50%" align="center">
|
|
77
|
+
<b>🤖 100% Feature Parity (Android & iOS)</b><br/><br/>
|
|
78
|
+
<img src="assets/cross_platform_parity.png" alt="Cross Platform Parity" width="380" />
|
|
79
|
+
</td>
|
|
80
|
+
</tr>
|
|
81
|
+
</table>
|
|
82
|
+
</div>
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 💡 Why `react-native-live-widgets`?
|
|
87
|
+
|
|
88
|
+
Until now, adding **Live Activities** or **Home Screen Widgets** to a React Native app required writing hundreds of lines of complex Swift, SwiftUI, and Kotlin code, managing App Groups, Darwin notifications, and separate native target builds.
|
|
89
|
+
|
|
90
|
+
`react-native-live-widgets` solves this with a **Declarative TypeScript UI DSL**:
|
|
91
|
+
- 🚫 **No SwiftUI / Kotlin coding required** for custom screens.
|
|
92
|
+
- 🎨 **100% Declarative UI in React Native (`UI.VStack`, `UI.HStack`, `UI.Text`, `UI.Button`, `UI.Progress`, `UI.Image`)**.
|
|
93
|
+
- 🚀 **Full Expo & EAS Build Support** via automated Expo Config Plugin (`app.plugin.js`).
|
|
94
|
+
- ⚡ **Interactive Buttons**: Tap buttons on the Home Screen Widget to run native Swift extensions or wake up TypeScript handlers.
|
|
95
|
+
- 🔄 **Realtime Data Sync (`SharedStorage`)**: Single source of truth across Main App, Lock Screen, and Home Screen.
|
|
96
|
+
- 🌐 **Silent Background Remote API Sync**: Automatically fetch REST APIs and update Widgets even when the App is **Force-Killed**.
|
|
97
|
+
- 🤖 **Android Parity**: Supports Android 16+ Promoted Live Notifications and Home Screen AppWidgets.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## ✨ Key Features
|
|
102
|
+
|
|
103
|
+
### 1. 🏝️ Dynamic Island & Lock Screen Live Activities (iOS 16.1+)
|
|
104
|
+
- **All Dynamic Island Modes**: `compactLeading`, `compactTrailing`, `minimal`, and `expanded`.
|
|
105
|
+
- **Realtime Timers & Progress**: Countdown timers, segmented progress bars, and battery/progress rings with zero battery drain.
|
|
106
|
+
- **Smart Dismissal Policies**: `immediate`, `afterDate`, or `default`.
|
|
107
|
+
|
|
108
|
+
### 2. 📱 Interactive Home Screen Widgets (iOS WidgetKit & Android AppWidget)
|
|
109
|
+
- Supports **Small**, **Medium**, and **Large** widget families.
|
|
110
|
+
- **Multi-page & Tabs**: Switch tabs or carousel pages directly on the widget (`actionId: "page:next"`).
|
|
111
|
+
- **Checklist & Toggles**: Toggle checkboxes and switch states without opening the app (`actionId: "toggle:<key>"`).
|
|
112
|
+
- **Dark & Light Mode**: Declarative color tokens `{ light: '#FFF', dark: '#0F172A' }`.
|
|
113
|
+
|
|
114
|
+
### 3. ⚡ Bi-directional Action Dispatcher (TypeScript + Native)
|
|
115
|
+
- Tap a widget button outside on the Home Screen to trigger a registered TypeScript function:
|
|
116
|
+
```ts
|
|
117
|
+
LiveActivity.registerAction('action_checkin', async (payload) => {
|
|
118
|
+
// Runs inside React Native JS engine!
|
|
119
|
+
console.log('Action triggered from Home Screen Widget:', payload);
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
- **App-Killed Protection**: Native fallback ensures UI responds instantly and persists data even if the main app is terminated.
|
|
123
|
+
|
|
124
|
+
### 4. 🌐 Background Remote API Sync (Zero Code Backend)
|
|
125
|
+
- Configure an API endpoint with `Widget.setRemoteConfig`:
|
|
126
|
+
```ts
|
|
127
|
+
await Widget.setRemoteConfig('main', {
|
|
128
|
+
url: 'https://api.yourcompany.com/v1/shifts/current',
|
|
129
|
+
method: 'GET',
|
|
130
|
+
refreshIntervalMinutes: 15
|
|
131
|
+
}, APP_GROUP);
|
|
132
|
+
```
|
|
133
|
+
- The native Extension fetches fresh JSON and dynamically replaces `{{variables}}` in your widget layout in the background.
|
|
134
|
+
|
|
135
|
+
### 5. 🔔 APNs & FCM Token Management
|
|
136
|
+
- One-call retrieval for all push tokens:
|
|
137
|
+
```ts
|
|
138
|
+
const tokens = await LiveActivity.getAllPushTokens();
|
|
139
|
+
// tokens.devicePushToken
|
|
140
|
+
// tokens.pushToStartToken (iOS 17.2+)
|
|
141
|
+
// tokens.activityUpdateToken
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## ⚡ Quick Start
|
|
147
|
+
|
|
148
|
+
### 1. Installation
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
# React Native CLI
|
|
152
|
+
npm install react-native-live-widgets
|
|
153
|
+
|
|
154
|
+
# Expo (Managed or Bare)
|
|
155
|
+
npx expo install react-native-live-widgets
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
### 2. Configuration
|
|
161
|
+
|
|
162
|
+
#### A. If using Expo (Config Plugin)
|
|
163
|
+
|
|
164
|
+
Add `react-native-live-widgets` to your `app.json` or `app.config.js`:
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"expo": {
|
|
169
|
+
"name": "My Expo App",
|
|
170
|
+
"plugins": [
|
|
171
|
+
[
|
|
172
|
+
"react-native-live-widgets",
|
|
173
|
+
{
|
|
174
|
+
"appGroup": "group.com.yourcompany.app",
|
|
175
|
+
"enableLiveActivities": true,
|
|
176
|
+
"frequentUpdates": true
|
|
177
|
+
}
|
|
178
|
+
]
|
|
179
|
+
]
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Then generate native projects or run with Expo Dev Client:
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
# 1. Generate native folders
|
|
188
|
+
npx expo prebuild
|
|
189
|
+
|
|
190
|
+
# 2. Automatically scaffold & link Xcode Widget Extension target
|
|
191
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
192
|
+
|
|
193
|
+
# 3. Run on iOS Simulator & Android Emulator:
|
|
194
|
+
npx expo run:ios
|
|
195
|
+
npx expo run:android
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
> 📖 **Detailed Step-by-Step Expo Guide**: [English](docs/EXPO-GUIDE-EN.md) • [Tiếng Việt](docs/EXPO-GUIDE-VI.md)
|
|
199
|
+
|
|
200
|
+
#### B. If using Bare React Native CLI
|
|
201
|
+
|
|
202
|
+
Run the automated scaffolding script in your React Native project root:
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
npx react-native-live-widgets init --group group.com.yourcompany.app
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
This will automatically:
|
|
209
|
+
- Inject `NSSupportsLiveActivities` and `NSSupportsLiveActivitiesFrequentUpdates` into `Info.plist`.
|
|
210
|
+
- Scaffold the `LiveWidgetsExtension` bundle in your `ios/` folder.
|
|
211
|
+
- Configure `AndroidManifest.xml` with required notification permissions.
|
|
212
|
+
|
|
213
|
+
And install CocoaPods dependencies:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
cd ios && pod install
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 💻 Code Example
|
|
222
|
+
|
|
223
|
+
### 1. Start a Live Activity with Dynamic Island
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
import { UI, LiveActivity } from 'react-native-live-widgets';
|
|
227
|
+
|
|
228
|
+
await LiveActivity.start({
|
|
229
|
+
activityId: 'kpi_q4_2026',
|
|
230
|
+
dynamicIsland: {
|
|
231
|
+
compactLeading: UI.Text('KPI Q4', { color: '#38BDF8', fontWeight: 'bold' }),
|
|
232
|
+
compactTrailing: UI.Text('86%', { color: '#10B981', fontWeight: 'bold' }),
|
|
233
|
+
minimal: UI.Text('86%', { color: '#10B981' }),
|
|
234
|
+
expanded: UI.VStack(
|
|
235
|
+
{ padding: 14, spacing: 8, backgroundColor: '#0F172A' },
|
|
236
|
+
UI.HStack(
|
|
237
|
+
{ justifyContent: 'spaceBetween' },
|
|
238
|
+
UI.Text('BẢNG ĐIỀU HÀNH KPI', { fontSize: 11, color: '#94A3B8' }),
|
|
239
|
+
UI.Badge({ text: '86% Hoàn thành', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
|
|
240
|
+
),
|
|
241
|
+
UI.Text('Mục tiêu Q4/2026', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }),
|
|
242
|
+
UI.Progress({
|
|
243
|
+
style: 'bar',
|
|
244
|
+
value: 0.86,
|
|
245
|
+
tintColor: '#10B981',
|
|
246
|
+
trackColor: '#334155'
|
|
247
|
+
}),
|
|
248
|
+
UI.Text('Doanh số 12.8 tỷ / 15 tỷ VNĐ • Tăng trưởng +22%', { fontSize: 12, color: '#94A3B8' })
|
|
249
|
+
)
|
|
250
|
+
},
|
|
251
|
+
lockScreen: UI.VStack(
|
|
252
|
+
{ padding: 16, backgroundColor: '#0F172A', cornerRadius: 16 },
|
|
253
|
+
UI.HStack(
|
|
254
|
+
{ justifyContent: 'spaceBetween' },
|
|
255
|
+
UI.Text('KPI Quý 4: Đạt 86% mục tiêu', { fontSize: 14, fontWeight: 'bold', color: '#FFFFFF' }),
|
|
256
|
+
UI.Badge({ text: '+18%', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
|
|
257
|
+
),
|
|
258
|
+
UI.Progress({
|
|
259
|
+
style: 'segmented',
|
|
260
|
+
segments: 7,
|
|
261
|
+
currentSegment: 6,
|
|
262
|
+
tintColor: '#38BDF8',
|
|
263
|
+
trackColor: '#1E293B'
|
|
264
|
+
})
|
|
265
|
+
)
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### 2. Configure Home Screen Widget with Live Sync
|
|
270
|
+
|
|
271
|
+
```tsx
|
|
272
|
+
import { UI, Widget, SharedStorage } from 'react-native-live-widgets';
|
|
273
|
+
|
|
274
|
+
const APP_GROUP = 'group.com.yourcompany.app';
|
|
275
|
+
|
|
276
|
+
// Set shared data
|
|
277
|
+
await SharedStorage.set('kpi_percent', '86', APP_GROUP);
|
|
278
|
+
await SharedStorage.set('revenue_month', '4.85 Tỷ đ', APP_GROUP);
|
|
279
|
+
|
|
280
|
+
// Build Declarative Layout
|
|
281
|
+
await Widget.setLayout('main', {
|
|
282
|
+
large: UI.VStack(
|
|
283
|
+
{ padding: 16, backgroundColor: '#0B132B', cornerRadius: 20 },
|
|
284
|
+
UI.HStack(
|
|
285
|
+
{ justifyContent: 'spaceBetween' },
|
|
286
|
+
UI.Text('TỔNG QUAN ĐIỀU HÀNH (KPI & BIỂU ĐỒ)', { fontSize: 11, color: '#38BDF8', fontWeight: 'bold' }),
|
|
287
|
+
UI.Badge({ text: 'LIVE SYNC', backgroundColor: '#064E3B', textColor: '#6EE7B7' })
|
|
288
|
+
),
|
|
289
|
+
UI.HStack(
|
|
290
|
+
{ spacing: 12, marginTop: 10 },
|
|
291
|
+
UI.VStack(
|
|
292
|
+
{ width: 90, alignItems: 'center' },
|
|
293
|
+
UI.Progress({ style: 'circular', value: 0.86, tintColor: '#38BDF8', trackColor: '#1E293B' }),
|
|
294
|
+
UI.Text('86%', { fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }),
|
|
295
|
+
UI.Text('KPI Quý', { fontSize: 10, color: '#94A3B8' })
|
|
296
|
+
)
|
|
297
|
+
),
|
|
298
|
+
UI.Spacer(),
|
|
299
|
+
UI.Button('Duyệt báo cáo doanh thu tuần', {
|
|
300
|
+
actionId: 'action_approve_report',
|
|
301
|
+
backgroundColor: '#1E293B',
|
|
302
|
+
textColor: '#FFFFFF'
|
|
303
|
+
})
|
|
304
|
+
)
|
|
305
|
+
}, APP_GROUP);
|
|
306
|
+
|
|
307
|
+
await Widget.reloadAll();
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## 📊 Platform Feature Parity Matrix
|
|
313
|
+
|
|
314
|
+
| Feature | iOS 16.1+ | Android (API 24 - 36) |
|
|
315
|
+
| :--- | :---: | :---: |
|
|
316
|
+
| **Declarative UI Engine (`UI.*`)** | SwiftUI dynamic tree | High-DPI Canvas 2D Bitmap |
|
|
317
|
+
| **Dynamic Island (All 4 layouts)** | ✅ Supported | 🔄 Mapped to Promoted Ongoing (Android 16+) |
|
|
318
|
+
| **Lock Screen Live Activity** | ✅ Supported | ✅ Ongoing Rich Notification |
|
|
319
|
+
| **Home Screen Widgets** | Small, Medium, Large | Resizable Grid AppWidgets |
|
|
320
|
+
| **Interactive Buttons** | iOS 17+ AppIntents | RemoteViews PendingIntent |
|
|
321
|
+
| **SharedStorage Data Sync** | App Group UserDefaults | Context SharedPreferences |
|
|
322
|
+
| **Remote API Silent Sync** | Background Timeline URLSession | WorkManager / Background Fetch |
|
|
323
|
+
| **Push Remote Updates** | Apple APNs Activity Tokens | Firebase Cloud Messaging (FCM) |
|
|
324
|
+
| **Expo & EAS Build Ready** | ✅ Automated Config Plugin | ✅ Automated Config Plugin |
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
## ☕ Sponsor & Donate (Ủng hộ tác giả)
|
|
329
|
+
|
|
330
|
+
`react-native-live-widgets` là dự án mã nguồn mở **hoàn toàn miễn phí (100% Free & MIT License)**, được phát triển và duy trì với tâm huyết mang lại giải pháp Live Activities & Widgets tốt nhất cho cộng đồng React Native Việt Nam và quốc tế.
|
|
331
|
+
|
|
332
|
+
Nếu thư viện này giúp ích cho dự án hoặc công ty của bạn, bạn có thể **mời tác giả một tách cà phê** để tiếp thêm động lực phát triển thêm nhiều tính năng mới nhé! ☕❤️
|
|
333
|
+
|
|
334
|
+
<div align="center">
|
|
335
|
+
|
|
336
|
+
<img src="assets/donate_qr.png" alt="Donate qua VietQR VPBank" width="300" style="border-radius: 16px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);" />
|
|
337
|
+
|
|
338
|
+
### 🏦 Thông tin chuyển khoản ủng hộ:
|
|
339
|
+
- **Ngân hàng**: VPBank (Ngân hàng TMCP Việt Nam Thịnh Vượng)
|
|
340
|
+
- **Số tài khoản / Số điện thoại**: `0906472426`
|
|
341
|
+
- **Chủ tài khoản**: `TRAN LE VU`
|
|
342
|
+
- **Nội dung**: `LiveWidgets Support` hoặc lời nhắn của bạn
|
|
343
|
+
|
|
344
|
+
*Chân thành cảm ơn sự đồng hành và ủng hộ quý báu của bạn!* 🙏✨
|
|
345
|
+
|
|
346
|
+
</div>
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## 📚 Documentation & Guides
|
|
351
|
+
|
|
352
|
+
- 📱 **[LiveWidgetsExample Demo Project](https://github.com/React-Native-Vu/LiveWidgetsExample)**: Complete working sample app demonstrating all 5 presets with bidirectional sync on iOS & Android.
|
|
353
|
+
- 🇬🇧 **[Full English Developer Guide](docs/GUIDE-EN.md)**: Architecture, DSL specs, push notification server configuration, and best practices.
|
|
354
|
+
- 🇻🇳 **[Hướng dẫn Chi tiết bằng Tiếng Việt](docs/GUIDE-VI.md)**: Hướng dẫn tích hợp từng bước, thiết lập App Group, giải quyết lỗi thường gặp.
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## 🤝 Contributing
|
|
359
|
+
|
|
360
|
+
Contributions are welcome! Please feel free to submit a Pull Request or open an Issue on [GitHub Repository](https://github.com/React-Native-Vu/react-native-live-widgets).
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
## 📄 License
|
|
365
|
+
|
|
366
|
+
Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.
|
|
367
|
+
|
|
368
|
+
Developed with ❤️ by **vu-tran** for high-performance React Native & Expo applications.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
buildscript {
|
|
2
|
+
ext.kotlin_version = '1.9.22'
|
|
3
|
+
repositories {
|
|
4
|
+
google()
|
|
5
|
+
mavenCentral()
|
|
6
|
+
}
|
|
7
|
+
dependencies {
|
|
8
|
+
classpath "com.android.tools.build:gradle:8.2.1"
|
|
9
|
+
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
apply plugin: 'com.android.library'
|
|
14
|
+
apply plugin: 'kotlin-android'
|
|
15
|
+
|
|
16
|
+
def safeExtGet(prop, fallback) {
|
|
17
|
+
rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
android {
|
|
21
|
+
namespace "com.reactnativeliveactivity"
|
|
22
|
+
compileSdkVersion safeExtGet('compileSdkVersion', 34)
|
|
23
|
+
|
|
24
|
+
defaultConfig {
|
|
25
|
+
minSdkVersion safeExtGet('minSdkVersion', 24)
|
|
26
|
+
targetSdkVersion safeExtGet('targetSdkVersion', 34)
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
compileOptions {
|
|
30
|
+
sourceCompatibility JavaVersion.VERSION_17
|
|
31
|
+
targetCompatibility JavaVersion.VERSION_17
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
kotlinOptions {
|
|
35
|
+
jvmTarget = '17'
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
repositories {
|
|
40
|
+
google()
|
|
41
|
+
mavenCentral()
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
dependencies {
|
|
45
|
+
implementation 'com.facebook.react:react-android:+'
|
|
46
|
+
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
|
|
47
|
+
implementation 'androidx.core:core-ktx:1.12.0'
|
|
48
|
+
}
|
|
49
|
+
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
|
|
2
|
+
|
|
3
|
+
<uses-permission android:name="android.permission.INTERNET" />
|
|
4
|
+
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
|
5
|
+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
|
|
6
|
+
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
|
|
7
|
+
|
|
8
|
+
<application>
|
|
9
|
+
<!-- Receiver xử lý Live Update, Background API Sync & Interactive Widget Actions -->
|
|
10
|
+
<receiver
|
|
11
|
+
android:name=".LiveActivityReceiver"
|
|
12
|
+
android:exported="false">
|
|
13
|
+
<intent-filter>
|
|
14
|
+
<action android:name="com.reactnativeliveactivity.ACTION_REFRESH" />
|
|
15
|
+
<action android:name="com.reactnativeliveactivity.ACTION_WIDGET_ACTION" />
|
|
16
|
+
<action android:name="com.reactnativeliveactivity.ACTION_WIDGET_SYNC" />
|
|
17
|
+
</intent-filter>
|
|
18
|
+
</receiver>
|
|
19
|
+
|
|
20
|
+
<!-- Service Headless JS chạy tác vụ ngầm khi người dùng bấm nút trên Widget mà App đang đóng -->
|
|
21
|
+
<service
|
|
22
|
+
android:name=".LiveActivityHeadlessTaskService"
|
|
23
|
+
android:exported="false" />
|
|
24
|
+
|
|
25
|
+
<!-- Home Screen AppWidgetProvider tự động tích hợp cho Android -->
|
|
26
|
+
<receiver
|
|
27
|
+
android:name=".DynamicHomeScreenWidgetProvider"
|
|
28
|
+
android:label="Live Widgets"
|
|
29
|
+
android:exported="true">
|
|
30
|
+
<intent-filter>
|
|
31
|
+
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
|
|
32
|
+
</intent-filter>
|
|
33
|
+
<meta-data
|
|
34
|
+
android:name="android.appwidget.provider"
|
|
35
|
+
android:resource="@xml/rn_live_widget_info" />
|
|
36
|
+
</receiver>
|
|
37
|
+
</application>
|
|
38
|
+
</manifest>
|