@capgo/capacitor-downloader 8.3.21 → 8.4.1

package/README.md

@@ -36,6 +36,25 @@ We build, improve and fix our plugins with heavy use of AI, so issues usually ge
 - **Status and files**: `checkStatus()` for a task and `getFileInfo()` for a downloaded file.
 - **Platforms**: iOS and Android. iOS uses a background `URLSession`, Android uses `DownloadManager`. Not available on web.
 
+## Download completed notifications
+
+Long downloads often finish while your user is in another app. Set `downloadCompletedNotificationText` on `download()` to show an opt-in, caller-localized system notification when the file is ready. Tapping it returns to your app.
+
+- **Opt in**: omit the option (or pass empty text) to rely on `downloadCompleted` events only.
+- **Permissions**: request notification permission in your app. If the user denies it, downloads still complete and the plugin skips the alert.
+- **Android**: the plugin manifest already merges `POST_NOTIFICATIONS`; on Android 13+ your app only needs to request it at runtime. Works alongside the DownloadManager `notification` visibility option. While your app is in the foreground, Android still posts the completion alert when the download succeeds.
+- **iOS**: request authorization with `UNUserNotificationCenter` before the download finishes. While your app is in the foreground, iOS shows a delivered notification only if your app's `UNUserNotificationCenter` delegate presents it, so without a notifications plugin it is usually silent; use `downloadCompleted` events in that case.
+
+```typescript
+await Downloader.download({
+  id: 'episode-12',
+  url: audioUrl,
+  destination: 'podcasts/episode-12.mp3',
+  notification: 'hidden',
+  downloadCompletedNotificationText: t('downloads.episodeReady'),
+});
+```
+
 ## Why Capacitor Downloader?
 
 A reliable **native file downloader** built for Capacitor apps that continues downloads even when your app is backgrounded or closed:
@@ -311,15 +330,16 @@ Represents the current state and progress of a download task.
 
 Configuration options for starting a download.
 
-| Prop               | Type                                               | Description                                                                                                                                                                                                                                                                                                                     | Since |
-| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **`id`**           | <code>string</code>                                | Unique identifier for this download task                                                                                                                                                                                                                                                                                        |       |
-| **`url`**          | <code>string</code>                                | URL of the file to download                                                                                                                                                                                                                                                                                                     |       |
-| **`destination`**  | <code>string</code>                                | Local file path where the download will be saved                                                                                                                                                                                                                                                                                |       |
-| **`headers`**      | <code>{ [key: string]: string; }</code>            | Optional HTTP headers to include in the request                                                                                                                                                                                                                                                                                 |       |
-| **`network`**      | <code>'cellular' \| 'wifi-only'</code>             | Network type requirement for download                                                                                                                                                                                                                                                                                           |       |
-| **`priority`**     | <code>'high' \| 'normal' \| 'low'</code>           | Download priority level                                                                                                                                                                                                                                                                                                         |       |
-| **`notification`** | <code>'completed' \| 'progress' \| 'hidden'</code> | Android DownloadManager notification visibility. - `'completed'` (default): show while downloading and keep the notification after completion. - `'progress'`: show while downloading, remove the notification when finished. - `'hidden'`: no system notification; use plugin progress events instead. Ignored on iOS and Web. | 8.2.0 |
+| Prop                                    | Type                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Since |
+| --------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`id`**                                | <code>string</code>                                | Unique identifier for this download task                                                                                                                                                                                                                                                                                                                                                                                                                               |       |
+| **`url`**                               | <code>string</code>                                | URL of the file to download                                                                                                                                                                                                                                                                                                                                                                                                                                            |       |
+| **`destination`**                       | <code>string</code>                                | Local file path where the download will be saved                                                                                                                                                                                                                                                                                                                                                                                                                       |       |
+| **`headers`**                           | <code>{ [key: string]: string; }</code>            | Optional HTTP headers to include in the request                                                                                                                                                                                                                                                                                                                                                                                                                        |       |
+| **`network`**                           | <code>'cellular' \| 'wifi-only'</code>             | Network type requirement for download                                                                                                                                                                                                                                                                                                                                                                                                                                  |       |
+| **`priority`**                          | <code>'high' \| 'normal' \| 'low'</code>           | Download priority level                                                                                                                                                                                                                                                                                                                                                                                                                                                |       |
+| **`notification`**                      | <code>'completed' \| 'progress' \| 'hidden'</code> | Android DownloadManager notification visibility. - `'completed'` (default): show while downloading and keep the notification after completion. - `'progress'`: show while downloading, remove the notification when finished. - `'hidden'`: no system notification; use plugin progress events instead. Ignored on iOS and Web.                                                                                                                                        | 8.2.0 |
+| **`downloadCompletedNotificationText`** | <code>string</code>                                | Optional localized text for a system notification when the download finishes. When set, iOS and Android may show a local notification after a successful download if the user granted notification permission. If permission is denied, the download still completes and no notification is shown. Tapping the notification reopens the app. Omitted or empty means no completion notification from the plugin (use `downloadCompleted` events while the app is open). | 8.4.0 |
 
 
 #### PluginListenerHandle

package/android/src/main/AndroidManifest.xml

@@ -1,3 +1,4 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
     <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 </manifest>

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/CapacitorDownloaderPlugin.java

@@ -27,19 +27,22 @@ import java.util.concurrent.atomic.AtomicLong;
 @CapacitorPlugin(name = "CapacitorDownloader")
 public class CapacitorDownloaderPlugin extends Plugin {
 
-    private final String pluginVersion = "8.3.21";
+    private final String pluginVersion = "8.4.1";
 
     private DownloadManager downloadManager;
     private final Map<String, Long> downloads = new ConcurrentHashMap<>();
+    private final Map<String, Long> downloadGenerations = new ConcurrentHashMap<>();
     private final AtomicLong pendingDownloadSequence = new AtomicLong(0);
     private ExecutorService downloadManagerExecutor;
     private final Handler handler = new Handler(Looper.getMainLooper());
     private BroadcastReceiver downloadReceiver;
+    private DownloadCompletedNotificationStore completedNotificationStore;
 
     @Override
     public void load() {
         downloadManager = (DownloadManager) getContext().getSystemService(Context.DOWNLOAD_SERVICE);
         downloadManagerExecutor = Executors.newCachedThreadPool();
+        completedNotificationStore = new DownloadCompletedNotificationStore(getContext());
         registerDownloadReceiver();
     }
 
@@ -84,6 +87,24 @@ public class CapacitorDownloaderPlugin extends Plugin {
         return trackedDownloadId != null && trackedDownloadId.longValue() == systemDownloadId;
     }
 
+    private long nextGeneration(String id) {
+        while (true) {
+            Long current = downloadGenerations.get(id);
+            long next = (current == null ? 0L : current.longValue()) + 1L;
+            if (current == null) {
+                if (downloadGenerations.putIfAbsent(id, next) == null) {
+                    return next;
+                }
+            } else if (downloadGenerations.replace(id, current, next)) {
+                return next;
+            }
+        }
+    }
+
+    private Long generationFor(String id) {
+        return downloadGenerations.get(id);
+    }
+
     @PluginMethod
     public void download(PluginCall call) {
         String id = call.getString("id");
@@ -95,41 +116,54 @@ public class CapacitorDownloaderPlugin extends Plugin {
             return;
         }
 
-        DownloadManager.Request request = new DownloadManager.Request(Uri.parse(url))
-            .setNotificationVisibility(DownloadNotificationVisibility.resolve(call.getString("notification")))
-            .setAllowedOverMetered(true)
-            .setAllowedOverRoaming(true);
-
-        // Handle custom destination
-        File destinationFile = new File(getContext().getExternalFilesDir(null), destination);
-        Uri destinationUri = Uri.fromFile(destinationFile);
-        request.setDestinationUri(destinationUri);
-
-        JSObject headers = call.getObject("headers");
-        if (headers != null) {
-            for (Iterator<String> it = headers.keys(); it.hasNext(); ) {
-                String key = it.next();
-                request.addRequestHeader(key, headers.getString(key));
-            }
+        if (downloads.containsKey(id)) {
+            call.reject("Download already exists");
+            return;
         }
 
-        String network = call.getString("network");
-        if ("wifi-only".equals(network)) {
-            request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_WIFI);
-        } else {
-            request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_MOBILE | DownloadManager.Request.NETWORK_WIFI);
+        final String notification = call.getString("notification");
+        final DownloadManager.Request request;
+        try {
+            request = new DownloadManager.Request(Uri.parse(url))
+                .setNotificationVisibility(DownloadNotificationVisibility.resolve(notification))
+                .setAllowedOverMetered(true)
+                .setAllowedOverRoaming(true);
+
+            File destinationFile = new File(getContext().getExternalFilesDir(null), destination);
+            Uri destinationUri = Uri.fromFile(destinationFile);
+            request.setDestinationUri(destinationUri);
+
+            JSObject headers = call.getObject("headers");
+            if (headers != null) {
+                for (Iterator<String> it = headers.keys(); it.hasNext(); ) {
+                    String key = it.next();
+                    request.addRequestHeader(key, headers.getString(key));
+                }
+            }
+
+            String network = call.getString("network");
+            if ("wifi-only".equals(network)) {
+                request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_WIFI);
+            } else {
+                request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_MOBILE | DownloadManager.Request.NETWORK_WIFI);
+            }
+        } catch (RuntimeException e) {
+            call.reject("Invalid download request", e);
+            return;
         }
 
-        final String notification = call.getString("notification");
         final long pendingToken = reservePendingDownload();
         if (downloads.putIfAbsent(id, pendingToken) != null) {
             call.reject("Download already exists");
             return;
         }
+        final long downloadGeneration = nextGeneration(id);
+        completedNotificationStore.setText(id, call.getString("downloadCompletedNotificationText"), downloadGeneration);
         runDownloadManagerWork(
             call,
             () -> {
                 if (!isTrackedDownload(id, pendingToken)) {
+                    completedNotificationStore.remove(id, downloadGeneration);
                     call.reject("Download was cancelled");
                     return;
                 }
@@ -139,6 +173,7 @@ public class CapacitorDownloaderPlugin extends Plugin {
                     downloadId = downloadManager.enqueue(request);
                 } catch (SecurityException e) {
                     downloads.remove(id, pendingToken);
+                    completedNotificationStore.remove(id, downloadGeneration);
                     if ("hidden".equals(notification)) {
                         call.reject("Hidden downloads require android.permission.DOWNLOAD_WITHOUT_NOTIFICATION in the app manifest", e);
                     } else {
@@ -147,6 +182,7 @@ public class CapacitorDownloaderPlugin extends Plugin {
                     return;
                 } catch (RuntimeException e) {
                     downloads.remove(id, pendingToken);
+                    completedNotificationStore.remove(id, downloadGeneration);
                     call.reject("Download could not be enqueued", e);
                     return;
                 }
@@ -155,9 +191,11 @@ public class CapacitorDownloaderPlugin extends Plugin {
                     try {
                         downloadManager.remove(downloadId);
                     } catch (RuntimeException e) {
+                        completedNotificationStore.remove(id, downloadGeneration);
                         call.reject("Download was cancelled", e);
                         return;
                     }
+                    completedNotificationStore.remove(id, downloadGeneration);
                     call.reject("Download was cancelled");
                     return;
                 }
@@ -170,7 +208,10 @@ public class CapacitorDownloaderPlugin extends Plugin {
                 // Start a periodic progress check
                 startProgressCheck(id, downloadId);
             },
-            () -> downloads.remove(id, pendingToken)
+            () -> {
+                downloads.remove(id, pendingToken);
+                completedNotificationStore.remove(id, downloadGeneration);
+            }
         );
     }
 
@@ -191,6 +232,8 @@ public class CapacitorDownloaderPlugin extends Plugin {
             return;
         }
 
+        final Long capturedGeneration = generationFor(id);
+
         ExecutorService executor = downloadManagerExecutor;
         if (executor == null) {
             return;
@@ -199,7 +242,7 @@ public class CapacitorDownloaderPlugin extends Plugin {
         try {
             executor.execute(() -> {
                 ProgressSnapshot snapshot = queryProgressSnapshot(id, systemDownloadId);
-                handler.post(() -> deliverProgressSnapshot(id, systemDownloadId, scheduleNext, snapshot));
+                handler.post(() -> deliverProgressSnapshot(id, systemDownloadId, scheduleNext, snapshot, capturedGeneration));
             });
         } catch (RejectedExecutionException ignored) {
             // Plugin is shutting down; stop polling quietly.
@@ -229,7 +272,13 @@ public class CapacitorDownloaderPlugin extends Plugin {
         }
     }
 
-    private void deliverProgressSnapshot(String id, long systemDownloadId, boolean scheduleNext, ProgressSnapshot snapshot) {
+    private void deliverProgressSnapshot(
+        String id,
+        long systemDownloadId,
+        boolean scheduleNext,
+        ProgressSnapshot snapshot,
+        Long capturedGeneration
+    ) {
         if (snapshot == null || !snapshot.found || !isTrackedDownload(id, systemDownloadId)) {
             return;
         }
@@ -244,12 +293,20 @@ public class CapacitorDownloaderPlugin extends Plugin {
             JSObject completedData = new JSObject();
             completedData.put("id", snapshot.id);
             notifyListeners("downloadCompleted", completedData);
+            String completionText =
+                capturedGeneration != null ? completedNotificationStore.takeText(snapshot.id, capturedGeneration) : null;
+            if (completionText != null) {
+                DownloadCompletedNotificationPresenter.showIfAllowed(getContext(), snapshot.id, completionText);
+            }
             shouldContinue = false;
         } else if (snapshot.status == DownloadManager.STATUS_FAILED) {
             JSObject failedData = new JSObject();
             failedData.put("id", snapshot.id);
             failedData.put("error", "Download failed");
             notifyListeners("downloadFailed", failedData);
+            if (capturedGeneration != null) {
+                completedNotificationStore.remove(snapshot.id, capturedGeneration);
+            }
             shouldContinue = false;
         }
 
@@ -297,6 +354,7 @@ public class CapacitorDownloaderPlugin extends Plugin {
             return;
         }
 
+        final Long stoppedGeneration = generationFor(id);
         Long downloadId = downloads.remove(id);
         if (downloadId == null) {
             call.reject("Download not found");
@@ -304,17 +362,24 @@ public class CapacitorDownloaderPlugin extends Plugin {
         }
 
         if (isPendingDownload(downloadId)) {
+            if (stoppedGeneration != null) {
+                completedNotificationStore.remove(id, stoppedGeneration);
+            }
             call.resolve(new JSObject().put("removed", false));
             return;
         }
 
         final long systemDownloadId = downloadId;
         final String stoppedId = id;
+        final long generation = stoppedGeneration != null ? stoppedGeneration.longValue() : 0L;
         runDownloadManagerWork(
             call,
             () -> {
                 try {
                     int removedDownloads = downloadManager.remove(systemDownloadId);
+                    if (stoppedGeneration != null) {
+                        completedNotificationStore.remove(stoppedId, generation);
+                    }
                     call.resolve(new JSObject().put("removed", removedDownloads > 0));
                 } catch (RuntimeException e) {
                     downloads.putIfAbsent(stoppedId, systemDownloadId);

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/DownloadCompletedNotificationPresenter.java

@@ -0,0 +1,91 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+import android.Manifest;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import androidx.core.app.NotificationCompat;
+import androidx.core.app.NotificationManagerCompat;
+import androidx.core.content.ContextCompat;
+
+final class DownloadCompletedNotificationPresenter {
+
+    static final String CHANNEL_ID = "capacitor_downloader_completed";
+
+    private DownloadCompletedNotificationPresenter() {}
+
+    static boolean canPostNotifications(Context context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            return NotificationManagerCompat.from(context).areNotificationsEnabled();
+        }
+        return ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED;
+    }
+
+    static void showIfAllowed(Context context, String downloadId, String bodyText) {
+        String body = DownloadCompletedNotificationText.normalize(bodyText);
+        if (body == null || downloadId == null) {
+            return;
+        }
+        if (!canPostNotifications(context)) {
+            return;
+        }
+
+        NotificationManagerCompat notificationManager = NotificationManagerCompat.from(context);
+        ensureChannel(context);
+
+        Intent launchIntent = context.getPackageManager().getLaunchIntentForPackage(context.getPackageName());
+        if (launchIntent == null) {
+            return;
+        }
+        launchIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP);
+
+        int pendingIntentFlags = PendingIntent.FLAG_UPDATE_CURRENT;
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+            pendingIntentFlags |= PendingIntent.FLAG_IMMUTABLE;
+        }
+
+        PendingIntent contentIntent = PendingIntent.getActivity(context, downloadId.hashCode(), launchIntent, pendingIntentFlags);
+
+        CharSequence appLabel = context.getApplicationInfo().loadLabel(context.getPackageManager());
+
+        NotificationCompat.Builder builder = new NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(android.R.drawable.stat_sys_download_done)
+            .setContentTitle(appLabel)
+            .setContentText(body)
+            .setStyle(new NotificationCompat.BigTextStyle().bigText(body))
+            .setContentIntent(contentIntent)
+            .setAutoCancel(true)
+            .setPriority(NotificationCompat.PRIORITY_DEFAULT);
+
+        try {
+            notificationManager.notify(notificationIdFor(downloadId), builder.build());
+        } catch (SecurityException ignored) {
+            // POST_NOTIFICATIONS denied at show time.
+        }
+    }
+
+    private static void ensureChannel(Context context) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            return;
+        }
+        NotificationManager manager = context.getSystemService(NotificationManager.class);
+        if (manager == null) {
+            return;
+        }
+        NotificationChannel existing = manager.getNotificationChannel(CHANNEL_ID);
+        if (existing != null) {
+            return;
+        }
+        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, "Download completed", NotificationManager.IMPORTANCE_DEFAULT);
+        channel.setDescription("Shown when a Capacitor Downloader task finishes");
+        manager.createNotificationChannel(channel);
+    }
+
+    static int notificationIdFor(String downloadId) {
+        return ("capacitor-downloader-completed-" + downloadId).hashCode();
+    }
+}

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/DownloadCompletedNotificationStore.java

@@ -0,0 +1,138 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+final class DownloadCompletedNotificationStore {
+
+    private static final String PREFS_NAME = "CapacitorDownloaderCompletedNotificationTexts";
+    private static final String MAP_KEY = "texts";
+
+    private final SharedPreferences prefs;
+    private final ConcurrentHashMap<String, Entry> inMemoryEntries;
+    private final Object lock = new Object();
+
+    DownloadCompletedNotificationStore(Context context) {
+        prefs = context.getApplicationContext().getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        inMemoryEntries = null;
+        clearPersistedTexts();
+    }
+
+    DownloadCompletedNotificationStore() {
+        prefs = null;
+        inMemoryEntries = new ConcurrentHashMap<>();
+    }
+
+    void setText(String downloadId, String text, long generation) {
+        if (downloadId == null) {
+            return;
+        }
+        String normalized = DownloadCompletedNotificationText.normalize(text);
+        synchronized (lock) {
+            Map<String, Entry> entries = loadEntriesLocked();
+            if (normalized == null) {
+                entries.remove(downloadId);
+            } else {
+                entries.put(downloadId, new Entry(normalized, generation));
+            }
+            saveEntriesLocked(entries);
+        }
+    }
+
+    String takeText(String downloadId, long generation) {
+        if (downloadId == null) {
+            return null;
+        }
+        synchronized (lock) {
+            Map<String, Entry> entries = loadEntriesLocked();
+            Entry entry = entries.get(downloadId);
+            if (entry == null || entry.generation != generation) {
+                return null;
+            }
+            entries.remove(downloadId);
+            saveEntriesLocked(entries);
+            return entry.text;
+        }
+    }
+
+    void clearPersistedTexts() {
+        if (prefs == null) {
+            return;
+        }
+        synchronized (lock) {
+            prefs.edit().remove(MAP_KEY).apply();
+        }
+    }
+
+    void remove(String downloadId, long generation) {
+        if (downloadId == null) {
+            return;
+        }
+        synchronized (lock) {
+            Map<String, Entry> entries = loadEntriesLocked();
+            Entry entry = entries.get(downloadId);
+            if (entry == null || entry.generation != generation) {
+                return;
+            }
+            entries.remove(downloadId);
+            saveEntriesLocked(entries);
+        }
+    }
+
+    private Map<String, Entry> loadEntriesLocked() {
+        if (inMemoryEntries != null) {
+            return new HashMap<>(inMemoryEntries);
+        }
+        String json = prefs.getString(MAP_KEY, "{}");
+        Map<String, Entry> entries = new HashMap<>();
+        try {
+            JSONObject object = new JSONObject(json);
+            Iterator<String> keys = object.keys();
+            while (keys.hasNext()) {
+                String key = keys.next();
+                JSONObject entryObject = object.getJSONObject(key);
+                entries.put(key, new Entry(entryObject.getString("text"), entryObject.getLong("generation")));
+            }
+        } catch (JSONException ignored) {
+            return new HashMap<>();
+        }
+        return entries;
+    }
+
+    private void saveEntriesLocked(Map<String, Entry> entries) {
+        if (inMemoryEntries != null) {
+            inMemoryEntries.clear();
+            inMemoryEntries.putAll(entries);
+            return;
+        }
+        JSONObject object = new JSONObject();
+        for (Map.Entry<String, Entry> entry : entries.entrySet()) {
+            try {
+                JSONObject entryObject = new JSONObject();
+                entryObject.put("text", entry.getValue().text);
+                entryObject.put("generation", entry.getValue().generation);
+                object.put(entry.getKey(), entryObject);
+            } catch (JSONException ignored) {
+                // Skip malformed serialization for a single key.
+            }
+        }
+        prefs.edit().putString(MAP_KEY, object.toString()).apply();
+    }
+
+    private static final class Entry {
+
+        private final String text;
+        private final long generation;
+
+        private Entry(String text, long generation) {
+            this.text = text;
+            this.generation = generation;
+        }
+    }
+}

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/DownloadCompletedNotificationText.java

@@ -0,0 +1,14 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+final class DownloadCompletedNotificationText {
+
+    private DownloadCompletedNotificationText() {}
+
+    static String normalize(String text) {
+        if (text == null) {
+            return null;
+        }
+        String trimmed = text.trim();
+        return trimmed.isEmpty() ? null : trimmed;
+    }
+}

package/dist/docs.json

@@ -27,7 +27,7 @@
           },
           {
             "name": "example",
-            "text": "```typescript\nconst task = await Downloader.download({\n  id: 'my-download',\n  url: 'https://example.com/file.pdf',\n  destination: 'downloads/file.pdf',\n  notification: 'hidden', // Android: no system notification; use downloadProgress events\n});\n```"
+            "text": "```typescript\nconst task = await Downloader.download({\n  id: 'my-download',\n  url: 'https://example.com/file.pdf',\n  destination: 'downloads/file.pdf',\n  notification: 'hidden', // Android: no system notification; use downloadProgress events\n  downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert\n});\n```"
           }
         ],
         "docs": "Start a new download task.",
@@ -400,6 +400,18 @@
           "docs": "Android DownloadManager notification visibility.\n\n- `'completed'` (default): show while downloading and keep the notification after completion.\n- `'progress'`: show while downloading, remove the notification when finished.\n- `'hidden'`: no system notification; use plugin progress events instead.\n\nIgnored on iOS and Web.",
           "complexTypes": [],
           "type": "'completed' | 'progress' | 'hidden' | undefined"
+        },
+        {
+          "name": "downloadCompletedNotificationText",
+          "tags": [
+            {
+              "text": "8.4.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Optional localized text for a system notification when the download finishes.\n\nWhen set, iOS and Android may show a local notification after a successful download\nif the user granted notification permission. If permission is denied, the download\nstill completes and no notification is shown. Tapping the notification reopens the app.\n\nOmitted or empty means no completion notification from the plugin (use\n`downloadCompleted` events while the app is open).",
+          "complexTypes": [],
+          "type": "string | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -40,6 +40,19 @@ export interface DownloadOptions {
      * @since 8.2.0
      */
     notification?: 'completed' | 'progress' | 'hidden';
+    /**
+     * Optional localized text for a system notification when the download finishes.
+     *
+     * When set, iOS and Android may show a local notification after a successful download
+     * if the user granted notification permission. If permission is denied, the download
+     * still completes and no notification is shown. Tapping the notification reopens the app.
+     *
+     * Omitted or empty means no completion notification from the plugin (use
+     * `downloadCompleted` events while the app is open).
+     *
+     * @since 8.4.0
+     */
+    downloadCompletedNotificationText?: string;
 }
 /**
  * Capacitor plugin for downloading files with background support.
@@ -58,6 +71,7 @@ export interface CapacitorDownloaderPlugin {
      *   url: 'https://example.com/file.pdf',
      *   destination: 'downloads/file.pdf',
      *   notification: 'hidden', // Android: no system notification; use downloadProgress events
+     *   downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert
      * });
      * ```
      */

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Represents the current state and progress of a download task.\n */\nexport interface DownloadTask {\n  /** Unique identifier for the download task */\n  id: string;\n  /** Download progress from 0 to 100 */\n  progress: number;\n  /** Current state of the download */\n  state: 'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR';\n}\n\n/**\n * Configuration options for starting a download.\n */\nexport interface DownloadOptions {\n  /** Unique identifier for this download task */\n  id: string;\n  /** URL of the file to download */\n  url: string;\n  /** Local file path where the download will be saved */\n  destination: string;\n  /** Optional HTTP headers to include in the request */\n  headers?: { [key: string]: string };\n  /** Network type requirement for download */\n  network?: 'cellular' | 'wifi-only';\n  /** Download priority level */\n  priority?: 'high' | 'normal' | 'low';\n  /**\n   * Android DownloadManager notification visibility.\n   *\n   * - `'completed'` (default): show while downloading and keep the notification after completion.\n   * - `'progress'`: show while downloading, remove the notification when finished.\n   * - `'hidden'`: no system notification; use plugin progress events instead.\n   *\n   * Ignored on iOS and Web.\n   *\n   * @since 8.2.0\n   */\n  notification?: 'completed' | 'progress' | 'hidden';\n}\n\n/**\n * Capacitor plugin for downloading files with background support.\n * Provides resumable downloads with progress tracking.\n */\nexport interface CapacitorDownloaderPlugin {\n  /**\n   * Start a new download task.\n   *\n   * @param options - Download configuration\n   * @returns Promise with initial download task status\n   * @example\n   * ```typescript\n   * const task = await Downloader.download({\n   *   id: 'my-download',\n   *   url: 'https://example.com/file.pdf',\n   *   destination: 'downloads/file.pdf',\n   *   notification: 'hidden', // Android: no system notification; use downloadProgress events\n   * });\n   * ```\n   */\n  download(options: DownloadOptions): Promise<DownloadTask>;\n\n  /**\n   * Pause an active download.\n   * Download can be resumed later from the same position.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when paused\n   */\n  pause(options: { id: string }): Promise<void>;\n\n  /**\n   * Resume a paused download.\n   * Continues from where it was paused.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when resumed\n   */\n  resume(options: { id: string }): Promise<void>;\n\n  /**\n   * Stop and cancel a download permanently.\n   * Downloaded data will be deleted.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when stopped\n   */\n  stop(options: { id: string }): Promise<void>;\n\n  /**\n   * Check the current status of a download.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise with current download task status\n   */\n  checkStatus(options: { id: string }): Promise<DownloadTask>;\n\n  /**\n   * Get information about a downloaded file.\n   *\n   * @param options - Options containing the file path\n   * @returns Promise with file size and MIME type\n   */\n  getFileInfo(options: { path: string }): Promise<{ size: number; type: string }>;\n\n  /**\n   * Listen for download progress updates.\n   * Fired periodically as download progresses.\n   *\n   * @param eventName - Must be 'downloadProgress'\n   * @param listenerFunc - Callback receiving progress updates\n   * @returns Promise with listener handle for removal\n   * @example\n   * ```typescript\n   * const listener = await Downloader.addListener('downloadProgress', (data) => {\n   *   console.log(`Download ${data.id}: ${data.progress}%`);\n   * });\n   * ```\n   */\n  addListener(\n    eventName: 'downloadProgress',\n    listenerFunc: (progress: {\n      id: string;\n      progress: number;\n      /** Bytes written so far */\n      bytesWritten?: number;\n      /** Total bytes expected, or 0 when the server did not report a length */\n      bytesTotal?: number;\n    }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download completion.\n   * Fired when a download finishes successfully.\n   *\n   * @param eventName - Must be 'downloadCompleted'\n   * @param listenerFunc - Callback receiving completion notification\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadCompleted',\n    listenerFunc: (result: { id: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download failures.\n   * Fired when a download encounters an error.\n   *\n   * @param eventName - Must be 'downloadFailed'\n   * @param listenerFunc - Callback receiving error information\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadFailed',\n    listenerFunc: (error: { id: string; error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Remove all event listeners.\n   * Cleanup method to prevent memory leaks.\n   *\n   * @returns Promise that resolves when all listeners removed\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the plugin version number.\n   *\n   * @returns Promise with version string\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Represents the current state and progress of a download task.\n */\nexport interface DownloadTask {\n  /** Unique identifier for the download task */\n  id: string;\n  /** Download progress from 0 to 100 */\n  progress: number;\n  /** Current state of the download */\n  state: 'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR';\n}\n\n/**\n * Configuration options for starting a download.\n */\nexport interface DownloadOptions {\n  /** Unique identifier for this download task */\n  id: string;\n  /** URL of the file to download */\n  url: string;\n  /** Local file path where the download will be saved */\n  destination: string;\n  /** Optional HTTP headers to include in the request */\n  headers?: { [key: string]: string };\n  /** Network type requirement for download */\n  network?: 'cellular' | 'wifi-only';\n  /** Download priority level */\n  priority?: 'high' | 'normal' | 'low';\n  /**\n   * Android DownloadManager notification visibility.\n   *\n   * - `'completed'` (default): show while downloading and keep the notification after completion.\n   * - `'progress'`: show while downloading, remove the notification when finished.\n   * - `'hidden'`: no system notification; use plugin progress events instead.\n   *\n   * Ignored on iOS and Web.\n   *\n   * @since 8.2.0\n   */\n  notification?: 'completed' | 'progress' | 'hidden';\n  /**\n   * Optional localized text for a system notification when the download finishes.\n   *\n   * When set, iOS and Android may show a local notification after a successful download\n   * if the user granted notification permission. If permission is denied, the download\n   * still completes and no notification is shown. Tapping the notification reopens the app.\n   *\n   * Omitted or empty means no completion notification from the plugin (use\n   * `downloadCompleted` events while the app is open).\n   *\n   * @since 8.4.0\n   */\n  downloadCompletedNotificationText?: string;\n}\n\n/**\n * Capacitor plugin for downloading files with background support.\n * Provides resumable downloads with progress tracking.\n */\nexport interface CapacitorDownloaderPlugin {\n  /**\n   * Start a new download task.\n   *\n   * @param options - Download configuration\n   * @returns Promise with initial download task status\n   * @example\n   * ```typescript\n   * const task = await Downloader.download({\n   *   id: 'my-download',\n   *   url: 'https://example.com/file.pdf',\n   *   destination: 'downloads/file.pdf',\n   *   notification: 'hidden', // Android: no system notification; use downloadProgress events\n   *   downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert\n   * });\n   * ```\n   */\n  download(options: DownloadOptions): Promise<DownloadTask>;\n\n  /**\n   * Pause an active download.\n   * Download can be resumed later from the same position.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when paused\n   */\n  pause(options: { id: string }): Promise<void>;\n\n  /**\n   * Resume a paused download.\n   * Continues from where it was paused.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when resumed\n   */\n  resume(options: { id: string }): Promise<void>;\n\n  /**\n   * Stop and cancel a download permanently.\n   * Downloaded data will be deleted.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when stopped\n   */\n  stop(options: { id: string }): Promise<void>;\n\n  /**\n   * Check the current status of a download.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise with current download task status\n   */\n  checkStatus(options: { id: string }): Promise<DownloadTask>;\n\n  /**\n   * Get information about a downloaded file.\n   *\n   * @param options - Options containing the file path\n   * @returns Promise with file size and MIME type\n   */\n  getFileInfo(options: { path: string }): Promise<{ size: number; type: string }>;\n\n  /**\n   * Listen for download progress updates.\n   * Fired periodically as download progresses.\n   *\n   * @param eventName - Must be 'downloadProgress'\n   * @param listenerFunc - Callback receiving progress updates\n   * @returns Promise with listener handle for removal\n   * @example\n   * ```typescript\n   * const listener = await Downloader.addListener('downloadProgress', (data) => {\n   *   console.log(`Download ${data.id}: ${data.progress}%`);\n   * });\n   * ```\n   */\n  addListener(\n    eventName: 'downloadProgress',\n    listenerFunc: (progress: {\n      id: string;\n      progress: number;\n      /** Bytes written so far */\n      bytesWritten?: number;\n      /** Total bytes expected, or 0 when the server did not report a length */\n      bytesTotal?: number;\n    }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download completion.\n   * Fired when a download finishes successfully.\n   *\n   * @param eventName - Must be 'downloadCompleted'\n   * @param listenerFunc - Callback receiving completion notification\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadCompleted',\n    listenerFunc: (result: { id: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download failures.\n   * Fired when a download encounters an error.\n   *\n   * @param eventName - Must be 'downloadFailed'\n   * @param listenerFunc - Callback receiving error information\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadFailed',\n    listenerFunc: (error: { id: string; error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Remove all event listeners.\n   * Cleanup method to prevent memory leaks.\n   *\n   * @returns Promise that resolves when all listeners removed\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the plugin version number.\n   *\n   * @returns Promise with version string\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/CapacitorDownloaderPlugin/CapacitorDownloaderPlugin.swift

@@ -8,7 +8,7 @@ import Capacitor
 
 @objc(CapacitorDownloaderPlugin)
 public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.3.21"
+    private let pluginVersion: String = "8.4.1"
     public let identifier = "CapacitorDownloaderPlugin"
     public let jsName = "CapacitorDownloader"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -22,6 +22,8 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
     ]
 
     private var tasks: [String: URLSessionDownloadTask] = [:]
+    private var downloadGenerations: [String: UInt64] = [:]
+    private var taskGenerations: [Int: UInt64] = [:]
     private let tasksLock = NSLock()
     private lazy var session: URLSession = {
         let config = URLSessionConfiguration.background(withIdentifier: "CapacitorDownloader")
@@ -29,6 +31,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         return URLSession(configuration: config, delegate: self, delegateQueue: nil)
     }()
 
+    public override func load() {
+        tasksLock.lock()
+        downloadGenerations = DownloadIdGenerationStore.shared.allGenerations()
+        taskGenerations = DownloadTaskGenerationStore.shared.allGenerations()
+        tasksLock.unlock()
+    }
+
     private func setTask(_ task: URLSessionDownloadTask, for id: String) {
         tasksLock.lock()
         defer { tasksLock.unlock() }
@@ -41,10 +50,48 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         return tasks[id]
     }
 
-    private func removeTask(for id: String) {
+    private func removeTask(for id: String, completing task: URLSessionDownloadTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        if tasks[id] === task {
+            tasks.removeValue(forKey: id)
+        }
+        taskGenerations.removeValue(forKey: task.taskIdentifier)
+    }
+
+    private func nextGeneration(for id: String) -> UInt64 {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        let generation = (downloadGenerations[id] ?? 0) &+ 1
+        downloadGenerations[id] = generation
+        DownloadIdGenerationStore.shared.setGeneration(generation, forDownloadId: id)
+        return generation
+    }
+
+    private func generation(for id: String) -> UInt64? {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        return downloadGenerations[id]
+    }
+
+    private func setTaskGeneration(_ generation: UInt64, for task: URLSessionDownloadTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        taskGenerations[task.taskIdentifier] = generation
+        DownloadTaskGenerationStore.shared.setGeneration(generation, forTaskIdentifier: task.taskIdentifier)
+    }
+
+    private func generation(for task: URLSessionTask) -> UInt64? {
         tasksLock.lock()
         defer { tasksLock.unlock() }
-        tasks.removeValue(forKey: id)
+        return taskGenerations[task.taskIdentifier]
+    }
+
+    private func clearTaskGeneration(for task: URLSessionTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        taskGenerations.removeValue(forKey: task.taskIdentifier)
+        DownloadTaskGenerationStore.shared.removeGeneration(forTaskIdentifier: task.taskIdentifier)
     }
 
     private func idForTask(_ task: URLSessionDownloadTask) -> String? {
@@ -86,7 +133,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         let destination = call.getString("destination") ?? ""
+        let generation = nextGeneration(for: id)
         DownloadDestinationStore.shared.setDestination(destination, for: id)
+        DownloadCompletedNotificationStore.shared.setText(
+            call.getString("downloadCompletedNotificationText"),
+            for: id,
+            generation: generation
+        )
 
         var request = URLRequest(url: url)
         if let headers = call.getObject("headers") as? [String: String] {
@@ -98,6 +151,7 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         let task = session.downloadTask(with: request)
         task.taskDescription = id
         setTask(task, for: id)
+        setTaskGeneration(generation, for: task)
         task.resume()
 
         call.resolve([
@@ -136,9 +190,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
 
+        let generation = generation(for: id)
         task.cancel()
-        removeTask(for: id)
+        removeTask(for: id, completing: task)
         DownloadDestinationStore.shared.removeDestination(for: id)
+        if let generation {
+            DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+        }
         call.resolve()
     }
 
@@ -203,7 +261,12 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
         }
 
         let storedDestination = DownloadDestinationStore.shared.takeDestination(for: id)
+        let generation = generation(for: downloadTask)
+
         guard let destinationURL = destinationURL(for: id, storedDestination: storedDestination) else {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": "Unable to resolve destination"])
             return
         }
@@ -211,6 +274,9 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
         if let httpResponse = downloadTask.response as? HTTPURLResponse,
            !DownloadHTTPValidator.isSuccessfulStatusCode(httpResponse.statusCode) {
             try? FileManager.default.removeItem(at: location)
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners(
                 "downloadFailed",
                 data: ["id": id, "error": "HTTP \(httpResponse.statusCode)"]
@@ -225,9 +291,17 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
             }
             try FileManager.default.moveItem(at: location, to: destinationURL)
             notifyListeners("downloadCompleted", data: ["id": id])
+            if let completionText = DownloadCompletedNotificationStore.shared.takeText(for: id, generation: generation) {
+                DownloadCompletedNotificationPresenter.presentIfAllowed(downloadId: id, body: completionText)
+            }
         } catch {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": error.localizedDescription])
         }
+
+        clearTaskGeneration(for: downloadTask)
     }
 
     public func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
@@ -236,15 +310,21 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
             return
         }
 
-        removeTask(for: id)
+        let generation = generation(for: downloadTask)
+        removeTask(for: id, completing: downloadTask)
 
         if error != nil {
             _ = DownloadDestinationStore.shared.takeDestination(for: id)
         }
 
-        if let error = error {
+        if let error {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": error.localizedDescription])
         }
+
+        clearTaskGeneration(for: downloadTask)
     }
 
     public func urlSession(

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationPresenter.swift

@@ -0,0 +1,38 @@
+import Foundation
+import UserNotifications
+
+enum DownloadCompletedNotificationPresenter {
+    static func presentIfAllowed(downloadId: String, body: String) {
+        guard let bodyText = DownloadCompletedNotificationText.normalize(body) else {
+            return
+        }
+
+        UNUserNotificationCenter.current().getNotificationSettings { settings in
+            let allowed: Bool
+            switch settings.authorizationStatus {
+            case .authorized, .provisional, .ephemeral:
+                allowed = true
+            case .denied, .notDetermined:
+                allowed = false
+            @unknown default:
+                allowed = false
+            }
+
+            guard allowed else {
+                return
+            }
+
+            let content = UNMutableNotificationContent()
+            content.body = bodyText
+            content.sound = .default
+
+            let request = UNNotificationRequest(
+                identifier: "capacitor-downloader-completed-\(downloadId)",
+                content: content,
+                trigger: nil
+            )
+
+            UNUserNotificationCenter.current().add(request)
+        }
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationStore.swift

@@ -0,0 +1,74 @@
+import Foundation
+
+final class DownloadCompletedNotificationStore {
+    static let shared = DownloadCompletedNotificationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderCompletedNotificationTexts"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setText(_ text: String?, for id: String, generation: UInt64) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        if let normalized = DownloadCompletedNotificationText.normalize(text) {
+            map[id] = Self.encodeEntry(text: normalized, generation: generation)
+        } else {
+            map.removeValue(forKey: id)
+        }
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func takeText(for id: String, generation: UInt64?) -> String? {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        guard let entry = map[id] else {
+            return nil
+        }
+        if let generation, Self.generation(from: entry) != generation {
+            return nil
+        }
+        map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+        return Self.text(from: entry)
+    }
+
+    func removeText(for id: String, generation: UInt64?) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        guard let entry = map[id] else {
+            return
+        }
+        if let generation, Self.generation(from: entry) != generation {
+            return
+        }
+        map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    private func entriesMapUnlocked() -> [String: [String: Any]] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) as? [String: [String: Any]] ?? [:]
+    }
+
+    private static func encodeEntry(text: String, generation: UInt64) -> [String: Any] {
+        ["text": text, "generation": NSNumber(value: generation)]
+    }
+
+    private static func text(from entry: [String: Any]) -> String? {
+        entry["text"] as? String
+    }
+
+    private static func generation(from entry: [String: Any]) -> UInt64? {
+        if let number = entry["generation"] as? NSNumber {
+            return number.uint64Value
+        }
+        return entry["generation"] as? UInt64
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationText.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+enum DownloadCompletedNotificationText {
+    static func normalize(_ text: String?) -> String? {
+        guard let text else {
+            return nil
+        }
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadIdGenerationStore.swift

@@ -0,0 +1,39 @@
+import Foundation
+
+final class DownloadIdGenerationStore {
+    static let shared = DownloadIdGenerationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderDownloadGenerations"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setGeneration(_ generation: UInt64, forDownloadId id: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map[id] = NSNumber(value: generation)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func allGenerations() -> [String: UInt64] {
+        lock.lock()
+        defer { lock.unlock() }
+        var result: [String: UInt64] = [:]
+        for (key, value) in generationsMapUnlocked() {
+            guard let number = value as? NSNumber else {
+                continue
+            }
+            result[key] = number.uint64Value
+        }
+        return result
+    }
+
+    private func generationsMapUnlocked() -> [String: Any] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) ?? [:]
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadTaskGenerationStore.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+final class DownloadTaskGenerationStore {
+    static let shared = DownloadTaskGenerationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderTaskGenerations"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setGeneration(_ generation: UInt64, forTaskIdentifier taskIdentifier: Int) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map[String(taskIdentifier)] = NSNumber(value: generation)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func removeGeneration(forTaskIdentifier taskIdentifier: Int) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map.removeValue(forKey: String(taskIdentifier))
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func allGenerations() -> [Int: UInt64] {
+        lock.lock()
+        defer { lock.unlock() }
+        var result: [Int: UInt64] = [:]
+        for (key, value) in generationsMapUnlocked() {
+            guard let taskIdentifier = Int(key), let number = value as? NSNumber else {
+                continue
+            }
+            result[taskIdentifier] = number.uint64Value
+        }
+        return result
+    }
+
+    private func generationsMapUnlocked() -> [String: Any] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) ?? [:]
+    }
+}

package/ios/Tests/CapacitorDownloaderPluginTests/CapacitorDownloaderPluginTests.swift

@@ -87,6 +87,127 @@ final class DownloadDestinationStoreTests: XCTestCase {
     }
 }
 
+final class DownloadCompletedNotificationTextTests: XCTestCase {
+    func testNormalizeRejectsBlank() {
+        XCTAssertNil(DownloadCompletedNotificationText.normalize(nil))
+        XCTAssertNil(DownloadCompletedNotificationText.normalize(""))
+        XCTAssertNil(DownloadCompletedNotificationText.normalize("  "))
+    }
+
+    func testNormalizeTrims() {
+        XCTAssertEqual(DownloadCompletedNotificationText.normalize("  Ready  "), "Ready")
+    }
+}
+
+final class DownloadCompletedNotificationStoreTests: XCTestCase {
+    private var defaults: UserDefaults!
+    private var store: DownloadCompletedNotificationStore!
+
+    override func setUp() {
+        super.setUp()
+        defaults = UserDefaults(suiteName: "CapacitorDownloaderNotificationTests")!
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderNotificationTests")
+        store = DownloadCompletedNotificationStore(defaults: defaults)
+    }
+
+    override func tearDown() {
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderNotificationTests")
+        super.tearDown()
+    }
+
+    func testSetAndTakeText() {
+        store.setText("  Finished  ", for: "task-1", generation: 1)
+
+        XCTAssertEqual(store.takeText(for: "task-1", generation: 1), "Finished")
+        XCTAssertNil(store.takeText(for: "task-1", generation: 1))
+    }
+
+    func testRemoveText() {
+        store.setText("Done", for: "task-1", generation: 1)
+        store.removeText(for: "task-1", generation: 1)
+        XCTAssertNil(store.takeText(for: "task-1", generation: 1))
+    }
+
+    func testGenerationMismatchLeavesStoredText() {
+        store.setText("New", for: "task-1", generation: 2)
+        store.removeText(for: "task-1", generation: 1)
+        XCTAssertEqual(store.takeText(for: "task-1", generation: 2), "New")
+    }
+
+    func testTakeTextWithoutTaskGenerationUsesStoredEntry() {
+        store.setText("Ready", for: "task-1", generation: 3)
+        XCTAssertEqual(store.takeText(for: "task-1", generation: nil), "Ready")
+    }
+
+    func testConcurrentUpdatesDoNotDropEntries() {
+        let ids = (0..<50).map { "task-\($0)" }
+        DispatchQueue.concurrentPerform(iterations: ids.count) { index in
+            store.setText("Body \(index)", for: ids[index], generation: 1)
+        }
+
+        for (index, id) in ids.enumerated() {
+            XCTAssertEqual(store.takeText(for: id, generation: 1), "Body \(index)")
+        }
+    }
+}
+
+final class DownloadIdGenerationStoreTests: XCTestCase {
+    private var defaults: UserDefaults!
+    private var store: DownloadIdGenerationStore!
+
+    override func setUp() {
+        super.setUp()
+        defaults = UserDefaults(suiteName: "CapacitorDownloaderIdGenerationTests")!
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderIdGenerationTests")
+        store = DownloadIdGenerationStore(defaults: defaults)
+    }
+
+    override func tearDown() {
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderIdGenerationTests")
+        super.tearDown()
+    }
+
+    func testPersistedGenerationSurvivesRelaunch() {
+        store.setGeneration(3, forDownloadId: "episode-12")
+        let restored = DownloadIdGenerationStore(defaults: defaults)
+        XCTAssertEqual(restored.allGenerations()["episode-12"], 3)
+        let next = (restored.allGenerations()["episode-12"] ?? 0) &+ 1
+        XCTAssertEqual(next, 4)
+    }
+
+    func testNextGenerationAfterRelaunchDoesNotReuseStoredValue() {
+        store.setGeneration(1, forDownloadId: "shared-id")
+        let relaunched = DownloadIdGenerationStore(defaults: defaults)
+        let generations = relaunched.allGenerations()
+        let next = (generations["shared-id"] ?? 0) &+ 1
+        XCTAssertEqual(next, 2)
+    }
+}
+
+final class DownloadTaskGenerationStoreTests: XCTestCase {
+    private var defaults: UserDefaults!
+    private var store: DownloadTaskGenerationStore!
+
+    override func setUp() {
+        super.setUp()
+        defaults = UserDefaults(suiteName: "CapacitorDownloaderTaskGenerationTests")!
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderTaskGenerationTests")
+        store = DownloadTaskGenerationStore(defaults: defaults)
+    }
+
+    override func tearDown() {
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderTaskGenerationTests")
+        super.tearDown()
+    }
+
+    func testPersistAndRestoreGeneration() {
+        store.setGeneration(7, forTaskIdentifier: 42)
+        XCTAssertEqual(store.allGenerations()[42], 7)
+        store.removeGeneration(forTaskIdentifier: 42)
+        XCTAssertNil(store.allGenerations()[42])
+    }
+}
+
 final class DownloadHTTPValidatorTests: XCTestCase {
     func testSuccessfulStatusCodes() {
         XCTAssertTrue(DownloadHTTPValidator.isSuccessfulStatusCode(200))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-downloader",
-  "version": "8.3.21",
+  "version": "8.4.1",
   "description": "Download file in background or foreground",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",