native-update 1.0.7 → 1.0.9
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.
|
@@ -15,20 +15,4 @@
|
|
|
15
15
|
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
|
16
16
|
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
|
|
17
17
|
|
|
18
|
-
<!-- WorkManager service -->
|
|
19
|
-
<service
|
|
20
|
-
android:name="androidx.work.impl.foreground.SystemForegroundService"
|
|
21
|
-
android:foregroundServiceType="dataSync" />
|
|
22
|
-
|
|
23
|
-
<!-- Broadcast receiver for notification actions -->
|
|
24
|
-
<receiver
|
|
25
|
-
android:name="com.aoneahsan.nativeupdate.NotificationActionReceiver"
|
|
26
|
-
android:exported="false">
|
|
27
|
-
<intent-filter>
|
|
28
|
-
<action android:name="com.aoneahsan.nativeupdate.UPDATE_NOW" />
|
|
29
|
-
<action android:name="com.aoneahsan.nativeupdate.UPDATE_LATER" />
|
|
30
|
-
<action android:name="com.aoneahsan.nativeupdate.DISMISS" />
|
|
31
|
-
</intent-filter>
|
|
32
|
-
</receiver>
|
|
33
|
-
|
|
34
18
|
</manifest>
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!--
|
|
3
|
+
EXAMPLE: Complete Android Manifest for apps using native-update plugin
|
|
4
|
+
Location: android/app/src/main/AndroidManifest.xml (in YOUR app, not the plugin)
|
|
5
|
+
|
|
6
|
+
This example shows the correct placement of all required elements for the
|
|
7
|
+
native-update plugin with background update support.
|
|
8
|
+
-->
|
|
9
|
+
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
|
|
10
|
+
xmlns:tools="http://schemas.android.com/tools"
|
|
11
|
+
package="com.yourcompany.yourapp">
|
|
12
|
+
|
|
13
|
+
<!-- Permissions are added automatically by the plugin, but listed here for reference -->
|
|
14
|
+
<!-- These permissions allow the plugin to function properly -->
|
|
15
|
+
<uses-permission android:name="android.permission.INTERNET" />
|
|
16
|
+
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
|
|
17
|
+
<uses-permission android:name="android.permission.WAKE_LOCK" />
|
|
18
|
+
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
|
|
19
|
+
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
|
|
20
|
+
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
|
|
21
|
+
|
|
22
|
+
<application
|
|
23
|
+
android:allowBackup="true"
|
|
24
|
+
android:icon="@mipmap/ic_launcher"
|
|
25
|
+
android:label="@string/app_name"
|
|
26
|
+
android:roundIcon="@mipmap/ic_launcher_round"
|
|
27
|
+
android:supportsRtl="true"
|
|
28
|
+
android:theme="@style/AppTheme">
|
|
29
|
+
|
|
30
|
+
<!-- Your main activity and other components -->
|
|
31
|
+
<activity
|
|
32
|
+
android:name=".MainActivity"
|
|
33
|
+
android:label="@string/app_name"
|
|
34
|
+
android:theme="@style/AppTheme.NoActionBar"
|
|
35
|
+
android:launchMode="singleTask"
|
|
36
|
+
android:exported="true">
|
|
37
|
+
<intent-filter>
|
|
38
|
+
<action android:name="android.intent.action.MAIN" />
|
|
39
|
+
<category android:name="android.intent.category.LAUNCHER" />
|
|
40
|
+
</intent-filter>
|
|
41
|
+
</activity>
|
|
42
|
+
|
|
43
|
+
<!-- ============================================= -->
|
|
44
|
+
<!-- REQUIRED FOR NATIVE-UPDATE BACKGROUND UPDATES -->
|
|
45
|
+
<!-- ============================================= -->
|
|
46
|
+
|
|
47
|
+
<!-- WorkManager Foreground Service -->
|
|
48
|
+
<!-- This service is REQUIRED for background downloads to work -->
|
|
49
|
+
<!-- Without it: Downloads will fail with ServiceNotFoundException -->
|
|
50
|
+
<!-- Purpose: Keeps downloads running when app is in background -->
|
|
51
|
+
<service
|
|
52
|
+
android:name="androidx.work.impl.foreground.SystemForegroundService"
|
|
53
|
+
android:foregroundServiceType="dataSync"
|
|
54
|
+
tools:node="merge" />
|
|
55
|
+
|
|
56
|
+
<!-- Notification Action Receiver -->
|
|
57
|
+
<!-- This receiver is REQUIRED for notification buttons to work -->
|
|
58
|
+
<!-- Without it: Update notifications will show but buttons won't work -->
|
|
59
|
+
<!-- Purpose: Handles "Update Now", "Update Later", and "Dismiss" actions -->
|
|
60
|
+
<receiver
|
|
61
|
+
android:name="com.aoneahsan.nativeupdate.NotificationActionReceiver"
|
|
62
|
+
android:exported="false">
|
|
63
|
+
<intent-filter>
|
|
64
|
+
<!-- Action triggered when user taps "Update Now" -->
|
|
65
|
+
<action android:name="com.aoneahsan.nativeupdate.UPDATE_NOW" />
|
|
66
|
+
<!-- Action triggered when user taps "Update Later" -->
|
|
67
|
+
<action android:name="com.aoneahsan.nativeupdate.UPDATE_LATER" />
|
|
68
|
+
<!-- Action triggered when user dismisses the notification -->
|
|
69
|
+
<action android:name="com.aoneahsan.nativeupdate.DISMISS" />
|
|
70
|
+
</intent-filter>
|
|
71
|
+
</receiver>
|
|
72
|
+
|
|
73
|
+
<!-- Other app components like providers, services, etc. -->
|
|
74
|
+
|
|
75
|
+
</application>
|
|
76
|
+
|
|
77
|
+
</manifest>
|
|
@@ -98,8 +98,73 @@ This command will:
|
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
3. The plugin automatically adds required permissions to the manifest:
|
|
101
|
-
-
|
|
102
|
-
-
|
|
101
|
+
- **`INTERNET`** - Required for downloading update bundles from your server
|
|
102
|
+
- **`ACCESS_NETWORK_STATE`** - Required to check network availability before downloading
|
|
103
|
+
- **`WAKE_LOCK`** - Required to keep the device awake during background downloads
|
|
104
|
+
- **`FOREGROUND_SERVICE`** - Required for showing download progress notifications
|
|
105
|
+
- **`POST_NOTIFICATIONS`** - Required for update notifications on Android 13+ ([API 33](https://developer.android.com/develop/ui/views/notifications/notification-permission))
|
|
106
|
+
- **`RECEIVE_BOOT_COMPLETED`** - Required to resume interrupted downloads after device restart
|
|
107
|
+
|
|
108
|
+
4. **CRITICAL: Android Manifest Configuration for Background Updates**
|
|
109
|
+
|
|
110
|
+
If you're using background updates, you **MUST** add these elements to your app's `AndroidManifest.xml` inside the `<application>` tag. Without these, background updates will fail silently:
|
|
111
|
+
|
|
112
|
+
```xml
|
|
113
|
+
<application>
|
|
114
|
+
<!-- Your existing application configuration -->
|
|
115
|
+
|
|
116
|
+
<!-- WorkManager Foreground Service (REQUIRED for background downloads) -->
|
|
117
|
+
<!-- Without this: Background downloads will be killed by the system after ~10 minutes -->
|
|
118
|
+
<!-- Documentation: https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running -->
|
|
119
|
+
<service
|
|
120
|
+
android:name="androidx.work.impl.foreground.SystemForegroundService"
|
|
121
|
+
android:foregroundServiceType="dataSync"
|
|
122
|
+
tools:node="merge" />
|
|
123
|
+
|
|
124
|
+
<!-- Notification Action Receiver (REQUIRED for update notifications) -->
|
|
125
|
+
<!-- Without this: "Update Now" and "Dismiss" buttons in notifications won't work -->
|
|
126
|
+
<!-- The receiver handles user actions from update notifications -->
|
|
127
|
+
<receiver
|
|
128
|
+
android:name="com.aoneahsan.nativeupdate.NotificationActionReceiver"
|
|
129
|
+
android:exported="false">
|
|
130
|
+
<intent-filter>
|
|
131
|
+
<action android:name="com.aoneahsan.nativeupdate.UPDATE_NOW" />
|
|
132
|
+
<action android:name="com.aoneahsan.nativeupdate.UPDATE_LATER" />
|
|
133
|
+
<action android:name="com.aoneahsan.nativeupdate.DISMISS" />
|
|
134
|
+
</intent-filter>
|
|
135
|
+
</receiver>
|
|
136
|
+
</application>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
**What happens if you skip this step:**
|
|
140
|
+
- ❌ Background downloads will be terminated by Android after ~10 minutes
|
|
141
|
+
- ❌ Update notifications won't display progress
|
|
142
|
+
- ❌ Notification action buttons won't respond to taps
|
|
143
|
+
- ❌ Downloads won't resume after app restart
|
|
144
|
+
- ❌ Users will experience failed or incomplete updates
|
|
145
|
+
|
|
146
|
+
**Detailed Explanation of Each Component:**
|
|
147
|
+
|
|
148
|
+
- **SystemForegroundService**: Android's WorkManager service that handles long-running background tasks
|
|
149
|
+
- **Purpose**: Keeps downloads alive when app is backgrounded or device is locked
|
|
150
|
+
- **`foregroundServiceType="dataSync"`**: Tells Android this service downloads/syncs data
|
|
151
|
+
- **What breaks without it**: Background downloads crash with `ServiceNotFoundException`
|
|
152
|
+
- **Reference**: [WorkManager Long-running Workers](https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running)
|
|
153
|
+
|
|
154
|
+
- **NotificationActionReceiver**: Handles user interactions with update notifications
|
|
155
|
+
- **`UPDATE_NOW`**: Triggered when user taps "Update Now" - starts immediate installation
|
|
156
|
+
- **`UPDATE_LATER`**: Triggered when user taps "Update Later" - schedules for later
|
|
157
|
+
- **`DISMISS`**: Triggered when user dismisses notification - cancels pending update
|
|
158
|
+
- **What breaks without it**: Buttons appear in notifications but don't do anything when tapped
|
|
159
|
+
- **Reference**: [Notification Actions](https://developer.android.com/develop/ui/views/notifications/notification-actions)
|
|
160
|
+
|
|
161
|
+
- **Security Attributes Explained**:
|
|
162
|
+
- **`android:exported="false"`**: Prevents other apps from sending intents to your receiver (security best practice)
|
|
163
|
+
- **`tools:node="merge"`**: Handles conflicts if multiple libraries define the same service
|
|
164
|
+
|
|
165
|
+
**Note:** If you're only using immediate (foreground) updates, these additions are optional.
|
|
166
|
+
|
|
167
|
+
📋 **[View Complete Android Manifest Example](../examples/android-manifest-example.xml)** - Shows the correct placement of all elements
|
|
103
168
|
|
|
104
169
|
#### Web Setup
|
|
105
170
|
|
|
@@ -165,6 +230,40 @@ import type {
|
|
|
165
230
|
|
|
166
231
|
## Troubleshooting Installation
|
|
167
232
|
|
|
233
|
+
### Android Manifest Errors
|
|
234
|
+
|
|
235
|
+
1. **"AAPT: error: unexpected element <service> found in <manifest>"**
|
|
236
|
+
- **Cause**: Service/receiver elements placed outside `<application>` tag or in wrong manifest
|
|
237
|
+
- **Fix**: Add to your **app's** manifest at `android/app/src/main/AndroidManifest.xml`, NOT the plugin's manifest
|
|
238
|
+
- **Example of CORRECT placement**:
|
|
239
|
+
```xml
|
|
240
|
+
<manifest>
|
|
241
|
+
<uses-permission ... />
|
|
242
|
+
<application>
|
|
243
|
+
<!-- HERE is where service and receiver go -->
|
|
244
|
+
<service ... />
|
|
245
|
+
<receiver ... />
|
|
246
|
+
</application>
|
|
247
|
+
</manifest>
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
2. **"ServiceNotFoundException" when downloading updates**
|
|
251
|
+
- **Cause**: Missing WorkManager service declaration
|
|
252
|
+
- **Symptoms**: App crashes when starting background download
|
|
253
|
+
- **Fix**: Add the SystemForegroundService to your app's manifest as shown above
|
|
254
|
+
- **Log message**: `java.lang.IllegalArgumentException: Service not registered: androidx.work.impl.foreground.SystemForegroundService`
|
|
255
|
+
|
|
256
|
+
3. **Notification buttons don't work**
|
|
257
|
+
- **Cause**: Missing NotificationActionReceiver declaration
|
|
258
|
+
- **Symptoms**: Update notification appears but buttons don't respond
|
|
259
|
+
- **Fix**: Add the receiver with all three action filters to your app's manifest
|
|
260
|
+
- **Test**: Send a test notification and verify buttons trigger actions
|
|
261
|
+
|
|
262
|
+
4. **"Permission denied" errors on Android 13+**
|
|
263
|
+
- **Cause**: Missing runtime permission request for notifications
|
|
264
|
+
- **Fix**: Request `POST_NOTIFICATIONS` permission at runtime
|
|
265
|
+
- **Reference**: [Android 13 Notification Permission](https://developer.android.com/develop/ui/views/notifications/notification-permission)
|
|
266
|
+
|
|
168
267
|
### Common Issues
|
|
169
268
|
|
|
170
269
|
1. **"Module not found" error**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "native-update",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.9",
|
|
4
4
|
"description": "Foundation package for building a comprehensive update system for Capacitor apps. Provides architecture and interfaces but requires backend implementation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/plugin.cjs.js",
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
"@rollup/plugin-json": "^6.1.0",
|
|
65
65
|
"@rollup/plugin-node-resolve": "^16.0.1",
|
|
66
66
|
"@rollup/plugin-terser": "^0.4.4",
|
|
67
|
-
"@types/node": "^24.
|
|
67
|
+
"@types/node": "^24.3.0",
|
|
68
68
|
"@typescript-eslint/eslint-plugin": "^8.39.1",
|
|
69
69
|
"@typescript-eslint/parser": "^8.39.1",
|
|
70
70
|
"@vitest/ui": "^3.2.4",
|