@kesha-antonov/react-native-background-downloader 4.5.2 → 4.5.4

package/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+## v4.5.3
+
+### ✨ New Features
+
+- **Android: Notification Grouping Mode (`summaryOnly`):** Added `mode` option to `NotificationsGroupingConfig`. Set `mode: 'summaryOnly'` to show only the summary notification for a group while individual download notifications are minimized (ultra-silent, no alert). Useful for keeping the notification shade clean during large batch downloads.
+  - `'individual'` (default) — all notifications shown, current behavior unchanged
+  - `'summaryOnly'` — only the group summary notification is shown with aggregate progress; individual notifications are invisible/silent
+- **Android: Progress-Based Summary Notification:** In `summaryOnly` mode, the group summary notification now displays aggregate progress (total bytes downloaded / total bytes) across all downloads in the group.
+- **Android: Auto-Remove Completed Downloads from Group:** Completed downloads are now automatically removed from notification groups, keeping the summary accurate.
+
+### 🏗️ Architecture Changes
+
+- **JS: `NotificationGroupingMode` Type:** New exported type `'individual' | 'summaryOnly'` for the `mode` field in `NotificationsGroupingConfig`.
+- **Android: Ultra-Silent Notification Channel:** Added `NOTIFICATION_CHANNEL_ULTRA_SILENT_ID` (`IMPORTANCE_MIN`) channel used for individual notifications in `summaryOnly` mode.
+- **Android: `updateSummaryNotificationForGroup()`:** New method that dispatches to the correct summary update strategy based on grouping mode.
+
+---
+
+## v4.5.2
+
+### ✨ New Features
+
+- **Update Headers on Paused Downloads:** Added ability to update headers (e.g., refresh auth tokens) on paused download tasks before resuming. Use `task.setDownloadParams()` to update headers while paused, then `task.resume()` to continue the download with new headers.
+  - **Use case:** User pauses a large download, returns hours/days later when auth token has expired. Now you can refresh the token and resume without restarting the download.
+  - **iOS:** Creates a fresh request with HTTP Range header and updated headers on resume
+  - **Android:** Updates both in-memory headers and persisted paused download state
+
+### 🏗️ Architecture Changes
+
+- **JS: `setDownloadParams()` Now Async:** The `DownloadTask.setDownloadParams()` method is now async and returns `Promise<boolean>` indicating whether native headers were updated (true when task is paused).
+- **Native: Added `updateTaskHeaders` Method:** New native method on iOS and Android to update headers for paused tasks.
+
+### 📚 Documentation
+
+- Added "Updating headers on paused downloads" section to README
+- Added `setDownloadParams()` method documentation to API.md
+- Added iOS "Updating Headers on Paused Downloads" section to PLATFORM_NOTES.md
+
+---
+
+## v4.5.1
+
+### 🏗️ Architecture Changes
+
+- **Android: UIDT Code Refactoring:** Extracted 980-line monolithic `UIDTDownloadJobService.kt` into modular components:
+  - `uidt/UIDTJobState.kt` - Data classes, constants, job registry
+  - `uidt/UIDTNotificationManager.kt` - All notification logic
+  - `uidt/UIDTJobManager.kt` - Job scheduling, cancel, pause, resume
+  - `utils/ProgressUtils.kt` - Progress calculation utilities
+  - Backward compatibility maintained via companion object delegates
+- **Android: Removed Redundant jobScheduler.cancel():** In `pauseJob()`, removed unnecessary `jobScheduler.cancel()` after `jobFinished(params, false)` since `wantsReschedule=false` already tells the system the job is complete.
+
+---
+
+## v4.5.0
+
+### ✨ New Features
+
+- **Android: Global Notification Configuration:** Added `showNotificationsEnabled` and `notificationsGrouping` config options for controlling UIDT notifications globally via `setConfig()`.
+- **Android: Customizable Paused Notification Text:** Added `downloadPaused` to `NotificationTexts` interface for customizing the "Paused" notification text.
+- **Android: Notification Update Throttling:** Notification updates are now synced with `progressInterval` for consistent UI/notification progress display.
+
+### 🐛 Bug Fixes
+
+- **Android: Paused Downloads Continuing in Background:** Fixed paused UIDT downloads continuing to download in background after app restart. Now UIDT job is fully cancelled on pause, with a detached "Paused" notification shown.
+- **Android: Duplicate Notifications After Resume:** Fixed duplicate notifications appearing when resuming downloads after app restart. Now uses stable notification IDs based on `configId.hashCode()`.
+- **Android: Notification Not Updating After Resume:** Fixed notification stuck on old progress after resuming. Now resets notification timing on resume and shows correct progress immediately.
+- **Android: Notification Updating While Paused:** Fixed notification progress updating even when download is paused.
+- **Android: Stale Notifications on App Close:** All download notifications are now cancelled when the app closes via `invalidate()`.
+
+### 💥 Breaking Changes
+
+- **Removed Per-Task Notification Options:** `isNotificationVisible` and `notificationTitle` removed from `DownloadParams` and `UploadParams`. Use global `setConfig({ showNotificationsEnabled, notificationsGrouping })` instead.
+
+### 🏗️ Architecture Changes
+
+- **Android: Pause Behavior on Android 14+:** Complete redesign of pause/resume for User-Initiated Data Transfer (UIDT) jobs:
+  - **Problem:** UIDT jobs continue running in background even after app closes, causing "paused" downloads to secretly continue downloading.
+  - **Solution:** On pause, the UIDT job is properly terminated via `jobFinished(params, false)`. Download state is persisted to disk for resumption via HTTP Range headers.
+  - **UX:** A detached "Paused" notification (using `JOB_END_NOTIFICATION_POLICY_DETACH`) remains visible after job termination. On resume, a new UIDT job is created.
+  - **Follows Google's UIDT best practices:** State saved even without `onStopJob`, `jobFinished()` called on completion, notifications updated periodically with throttling.
+- **Android: Separate Notification Channels:** Added separate channels for visible (`IMPORTANCE_LOW`) and silent (`IMPORTANCE_MIN`) notifications.
+
+### ✨ Improvements
+
+- **Android: Cleaner Notifications:** Added `setOnlyAlertOnce(true)` and `setShowWhen(false)` to all notifications for less intrusive updates.
+- **Example App: Persistent Notification Settings:** Show Notifications and Notification Grouping toggles are now persisted with MMKV.
+- **Example App: Android 13+ Permission Request:** Added POST_NOTIFICATIONS permission request when enabling notifications.
+
+### 📚 Documentation
+
+- Updated README with notification behavior during pause/resume
+- Updated API.md with new notification configuration options
+- Documented that notifications are removed when app closes
+
+---
+
+## v4.4.5
+
+### 🐛 Bug Fixes
+
+- **Android: Stop Task Not Working on Android 14+:** Fixed `stopTask()` not actually stopping UIDT downloads on Android 14+. The JobScheduler job was cancelled but the underlying HTTP download continued. Now properly calls `resumableDownloader.cancel()` before removing from active jobs.
+- **Android: Paused Tasks Not Persisting Across App Restarts:** Fixed paused UIDT downloads losing their state when the app was restarted. Added `getJobDownloadState()` to retrieve download state from active UIDT jobs and `savePausedDownloadState()` to properly persist pause state.
+- **Android: ACCESS_NETWORK_STATE Permission:** Added missing permission required for JobScheduler network connectivity constraints on Android 14+.
+- **Android: Downloaded Files List Showing Incomplete Files:** The "Downloaded Files" section in the example app now correctly filters out files that have active (non-DONE) download tasks, preventing incomplete files from appearing in the list.
+
+### 🧹 Code Cleanup
+
+- **Removed Verbose Debug Logs:** Cleaned up extensive debug logging in `StorageManager`, `Downloader`, and `RNBackgroundDownloaderModuleImpl` that was cluttering production logs. Removed serialization/deserialization logs, verification reads, and per-item iteration logs while keeping error logging.
+- **Simplified Kotlin Code:** Removed unnecessary `else` blocks containing only debug/warning logs from `pauseTask()` and `resumeTask()` methods for cleaner code.
+
+### ✨ Improvements
+
+- **TypeScript: Added `destination` to Task Info:** The `destination` field is now returned from `getExistingDownloadTasks()` for paused downloads, allowing the app to know where the file will be saved.
+
+### 📚 Documentation
+
+- Added `skipMmkvDependency` option documentation to README for Expo plugin
+
+---
+
+## v4.4.4
+
+### 🐛 Bug Fixes
+
+- **Expo Plugin: Fixed TypeScript Types:** Corrected TypeScript type definitions in the Expo config plugin.
+
+---
+
+## v4.4.3
+
+### ✨ New Features
+
+- **Expo Plugin: Auto-detect react-native-mmkv:** The Expo config plugin now automatically detects if `react-native-mmkv` is installed and skips adding the MMKV dependency to avoid duplicate class errors. Use `skipMmkvDependency: true` option to manually skip if needed.
+- **Android: Version from package.json:** Android native code now reads the library version from `package.json` instead of hardcoding it.
+
+---
+
+## v4.4.2
+
+### 🐛 Bug Fixes
+
+- **Kotlin 2.0 Compatibility:** Fixed compilation error with Kotlin 2.0 (React Native 0.77+) by updating `progressReporter` to use named parameter syntax. This ensures compatibility with both Kotlin 1.9 (RN 0.76) and Kotlin 2.x (RN 0.77+).
+
+---
+
+## v4.4.1
+
+### 🐛 Bug Fixes
+
+- **Android: Paused Tasks Persistence:** Fixed paused downloads not being restored after app restart on Android. Added persistent storage for paused download state using MMKV/SharedPreferences.
+- **iOS: Improved Pause/Resume Handling:** Better handling of pause/resume operations on app restarts for iOS.
+- **Upload Task App Restart Recovery:** Fixed upload tasks not being recoverable after app restart (#143). Added persistent storage for upload task configurations.
+
+### ✨ Improvements
+
+- **Example App:** Added task list display with animations and improved UI for managing downloads.
+
+### 📚 Documentation
+
+- Updated README with clearer MMKV dependency instructions
+- Added information about resuming tasks after app restarts
+- Updated authors section
+
+---
+
+## v4.4.0
+
+### ✨ New Features
+
+- **Android 16 UIDT Support:** Downloads are now automatically marked as User-Initiated Data Transfers on Android 16+ (API 36) to prevent thermal throttling and job quota restrictions. Downloads will continue reliably even under moderate thermal conditions (~40°C).
+
+### 🐛 Bug Fixes
+
+- **iOS MMKV Conflict Fix:** Removed hard MMKV dependency from iOS podspec to prevent symbol conflicts with `react-native-mmkv`. Apps using `react-native-mmkv` no longer experience crashes (EXC_BAD_ACCESS) on iOS.
+
+### 📦 Dependencies & Infrastructure
+
+- **New Android Permission:** Added `RUN_USER_INITIATED_JOBS` permission for Android 16+ UIDT support
+- **iOS MMKV Dependency:** MMKV is no longer a hard dependency in the podspec. Apps not using `react-native-mmkv` must add `pod 'MMKV', '>= 1.0.0'` to their Podfile.
+
+### 📚 Documentation
+
+- Added documentation about Android 16+ UIDT support in README
+- Added iOS MMKV dependency section in README (similar to Android section)
+- Added migration guide for iOS MMKV dependency change
+
+---
+
+## v4.2.0
+
+> 📖 **Upgrading from v4.1.x?** See the [Migration Guide](./MIGRATION.md) for details on the new Android pause/resume functionality.
+
+### ✨ New Features
+
+- **Android Pause/Resume Support:** Android now fully supports `task.pause()` and `task.resume()` methods using HTTP Range headers. Downloads can be paused and resumed just like on iOS.
+- **Background Download Service:** Added `ResumableDownloadService` - a foreground service that ensures downloads continue even when the app is in the background or the screen is off.
+- **WakeLock Support:** Downloads maintain a partial wake lock to prevent the device from sleeping during active downloads.
+- **`bytesTotal` Unknown Size Handling:** When the server doesn't provide a `Content-Length` header, `bytesTotal` now returns `-1` instead of `0` to distinguish "unknown size" from "zero bytes".
+
+### 🐛 Bug Fixes
+
+- **Android Pause Error:** Fixed `COULD_NOT_FIND` error when pausing downloads on Android by properly tracking pausing state
+- **Temp File Cleanup:** Fixed temp files (`.tmp`) not being deleted when stopping or deleting paused downloads
+- **Content-Length Handling:** Fixed progress percentage calculation when server doesn't provide Content-Length header
+
+### 📦 Dependencies & Infrastructure
+
+- **New Android Permissions:** Added `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_DATA_SYNC`, and `WAKE_LOCK` permissions for background download support
+- **New Service:** Added `ResumableDownloadService` with `dataSync` foreground service type
+
+### 📚 Documentation
+
+- Updated README to reflect Android pause/resume support
+- Removed "iOS only" notes from pause/resume documentation
+- Added documentation about `bytesTotal` returning `-1` for unknown sizes
+- Updated Android DownloadManager Limitations section with new pause/resume implementation details
+
+---
+
+## v4.1.0
+
+> 📖 **Upgrading from v4.0.x?** See the [Migration Guide](./MIGRATION.md) for the MMKV dependency change.
+
+### ⚠️ Breaking Changes
+
+- **MMKV Dependency Changed to `compileOnly`:** The MMKV dependency is now `compileOnly` instead of `implementation` to avoid duplicate class errors when the app also uses `react-native-mmkv`. Apps not using `react-native-mmkv` must now explicitly add the MMKV dependency.
+
+### ✨ New Features
+
+- **Expo Plugin Android Support:** The Expo config plugin now automatically adds the MMKV dependency on Android. Use `addMmkvDependency: false` option if you're already using `react-native-mmkv`.
+
+### 🐛 Bug Fixes
+
+- **Duplicate Class Errors:** Fixed potential duplicate class errors when app uses both this library and `react-native-mmkv` by changing MMKV to `compileOnly` dependency
+
+### 📚 Documentation
+
+- Added documentation for MMKV dependency requirements in README
+- Updated Platform-Specific Limitations section with MMKV setup instructions
+- Added Expo plugin options documentation
+
+---
+
+## v4.0.0
+
+> 📖 **Upgrading from v3.x?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
+
+### ⚠️ Breaking Changes
+
+- **API Renamed:** `checkForExistingDownloads()` → `getExistingDownloadTasks()` - Now returns a Promise with better naming
+- **API Renamed:** `download()` → `createDownloadTask()` - Downloads now require explicit `.start()` call
+- **Download Tasks Start Explicitly:** Tasks created with `createDownloadTask()` are now in `PENDING` state and must call `.start()` to begin downloading
+- **New Config Option:** Added `progressMinBytes` to `setConfig()` - controls minimum bytes change before progress callback fires (default: 1MB)
+- **Source Structure Changed:** Code moved from `lib/` to `src/` directory with proper TypeScript types
+
+### ✨ New Features
+
+- **React Native New Architecture Support:** Full TurboModules support for both iOS and Android
+- **Expo Config Plugin:** Added automatic iOS native code integration for Expo projects via `app.plugin.js`
+- **Android Kotlin Migration:** All Java code converted to Kotlin
+- **`maxRedirects` Option:** Configure maximum redirects for Android downloads (resolves #15)
+- **`progressMinBytes` Option:** Hybrid progress reporting - callbacks fire based on time interval OR bytes downloaded
+- **Android 15+ Support:** Added support for 16KB memory page sizes
+- **Architecture Fallback:** Comprehensive x86/ARMv7 support with SharedPreferences fallback
+
+### 🐛 Bug Fixes
+
+- **iOS Pause/Resume:** Fixed pause and resume functionality on iOS
+- **RN 0.78+ Compatibility:** Fixed bridge checks with safe emitter checks
+- **New Architecture Events:** Fixed `downloadBegin` and `downloadProgress` events emission
+- **Android Background Downloads:** Fixed completed files not moving to destination
+- **Progress Callback Unknown Total:** Fixed progress callback not firing when total bytes unknown
+- **Android 12 MMKV Crash:** Added robust error handling
+- **`checkForExistingDownloads` TypeError:** Fixed TypeError on Android with architecture fallback
+- **Firebase Performance Compatibility:** Fixed `completeHandler` method compatibility on Android
+- **Slow Connection Handling:** Better handling of slow-responding URLs with timeouts
+- **Android OldArch Export:** Fixed module method export issue (#79)
+- **MMKV Compatibility:** Support for react-native-mmkv 4+ with mmkv-shared dependency
+
+### 📦 Dependencies & Infrastructure
+
+- **React Native:** Updated example app to RN 0.81.4
+- **TypeScript:** Full TypeScript types in `src/types.ts`
+- **iOS Native:** Converted from `.m` to `.mm` (Objective-C++)
+- **Package Manager:** Switched to yarn as preferred package manager
+
+### 📚 Documentation
+
+- Added documentation for `progressMinBytes` option
+- Updated README for React Native 0.77+ instructions
+- Improved Expo config plugin examples

package/README.md

@@ -15,14 +15,14 @@
 <h1 align="center">React Native Background Downloader</h1>
 
 <p align="center">
-  Download and upload large files on iOS & Android — even when your app is in the background or terminated.
+  Download and upload large files on iOS & Android — even when your app is in the background or terminated by the OS.
 </p>
 
 ---
 
 ## ✨ Features
 
-- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated
+- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated by the OS
 - 📤 **Background Uploads** - Upload files reliably in the background
 - ⏸️ **Pause/Resume** - Full pause and resume support on both iOS and Android
 - 🔄 **Re-attach to Downloads** - Reconnect to ongoing downloads after app restart
@@ -37,7 +37,7 @@
 **The Problem:** Standard network requests in React Native are tied to your app's lifecycle. When the user switches to another app or the OS terminates your app to free memory, your downloads stop. For small files this is fine, but for large files (videos, podcasts, documents) this creates a frustrating user experience.
 
 **The Solution:** Both iOS and Android provide system-level APIs for background file transfers:
-- **iOS:** [`NSURLSession`](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background) - handles downloads in a separate process, continuing even after your app is terminated
+- **iOS:** [`NSURLSession`](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background) - handles downloads in a separate process, continuing even after your app is terminated by the OS. Note: if the user explicitly force-kills the app via the App Switcher, iOS cancels all background tasks — this is an iOS system limitation that cannot be overridden
 - **Android:** A combination of [`DownloadManager`](https://developer.android.com/reference/android/app/DownloadManager) for system-managed downloads, [Foreground Services](https://developer.android.com/develop/background-work/services/foreground-services) for pause/resume support, and [MMKV](https://github.com/Tencent/MMKV) for persistent state storage
 
 **The Challenge:** These APIs are powerful but complex. Downloads run in a separate process, so your app might restart from scratch while downloads are still in progress. Keeping your UI in sync with background downloads requires careful state management.
@@ -53,6 +53,7 @@
 - [📦 Installation](#-installation)
   - [Expo Projects](#expo-projects)
   - [Bare React Native Projects](#bare-react-native-projects)
+    - [MMKV version comparison](#mmkv-version-comparison)
 - [🚀 Usage](#-usage)
   - [Downloading a file](#downloading-a-file)
   - [Re-Attaching to background tasks](#re-attaching-to-background-tasks)
@@ -113,7 +114,7 @@ export default {
   expo: {
     plugins: [
       ["@kesha-antonov/react-native-background-downloader", {
-        mmkvVersion: "2.2.4",  // Customize MMKV version on Android
+        mmkvVersion: "1.3.16",  // Customize MMKV version on Android
         skipMmkvDependency: true  // Skip if you want to add MMKV manually
       }]
     ]
@@ -123,8 +124,8 @@ export default {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `mmkvVersion` | string | `'2.2.4'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. |
-| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. |
+| `mmkvVersion` | string | `'1.3.16'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. See [MMKV version comparison](#mmkv-version-comparison) for details. |
+| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. See [MMKV version comparison](#mmkv-version-comparison). |
 
 </details>
 
@@ -214,11 +215,29 @@ Add MMKV to your `android/app/build.gradle`:
 
 ```gradle
 dependencies {
-    implementation 'com.tencent:mmkv-shared:2.2.4'
+    implementation 'com.tencent:mmkv-shared:1.3.16'
 }
 ```
 
-> **Note:** If you're already using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) in your project, skip this step — it already includes MMKV.
+> **Note:** If you're already using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) in your project, skip this step — it already includes MMKV. Note that `react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support that was dropped in the official MMKV 2.x release.
+
+> **⚠️ armeabi-v7a (32-bit ARM) users:** MMKV 2.x dropped 32-bit ABI support (since v2.0.0). If you need armeabi-v7a support and get a CMake error like `No compatible library found for //mmkv/mmkv`, use the MMKV 1.3.x LTS series instead — it supports both armeabi-v7a **and** 16KB page sizes (since v1.3.14):
+> ```gradle
+> dependencies {
+>     implementation 'com.tencent:mmkv-shared:1.3.16'
+> }
+> ```
+
+#### MMKV version comparison
+
+| Dependency | armeabi-v7a (32-bit) | arm64-v8a | 16KB page size | Recommended for |
+|---|:---:|:---:|:---:|---|
+| `com.tencent:mmkv-shared:1.3.16` (**default**) | ✅ | ✅ | ✅ (since 1.3.14) | Most apps — broadest device coverage |
+| `com.tencent:mmkv-shared:2.x` | ❌ | ✅ | ✅ | 64-bit only apps (no legacy devices) |
+| `io.github.zhongwuzw:mmkv:2.3.0` ([Margelo fork](https://github.com/margelo/MMKV)) | ✅ | ✅ | ✅ | Used automatically by `react-native-mmkv` v4.x — skip manual dependency |
+| `react-native-mmkv` (already in project) | ✅ | ✅ | ✅ | If you already use `react-native-mmkv` — skip Step 4 entirely |
+
+**TL;DR:** Use the default `1.3.16`. If you already have `react-native-mmkv` in your project, skip Step 4.
 
 ## 🚀 Usage
 
@@ -636,9 +655,92 @@ setConfig({
 })
 ```
 
+**Notification grouping modes:**
+
+When downloading many files (e.g., thousands of photos), you can use the `mode` option to control how notifications are displayed:
+
+| Mode | Description |
+|------|-------------|
+| `'individual'` | Default. Shows all individual notifications grouped together with a summary |
+| `'summaryOnly'` | Shows only ONE notification with real-time aggregate progress (e.g., "45% - 5 files"). Individual UIDT notifications are collapsed into an invisible group. Ideal for bulk downloads |
+
+```javascript
+import { setConfig } from '@kesha-antonov/react-native-background-downloader'
+
+// For bulk downloads (e.g., syncing thousands of photos)
+// Use 'summaryOnly' mode to show only ONE notification with aggregate progress
+setConfig({
+  showNotificationsEnabled: true,
+  notificationsGrouping: {
+    enabled: true,
+    mode: 'summaryOnly', // Only show summary notification with progress bar
+    texts: {
+      groupTitle: 'Syncing Photos',
+      groupText: '{count} files downloading',
+    },
+  },
+})
+```
+
+**Example: Batch downloading multiple files with grouped notifications:**
+
+```javascript
+import { setConfig, createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+// Configure for bulk downloads with single summary notification
+setConfig({
+  showNotificationsEnabled: true,
+  notificationsGrouping: {
+    enabled: true,
+    mode: 'summaryOnly',
+    texts: {
+      groupTitle: 'Photo Sync',
+      groupText: '{count} photos downloading',
+    },
+  },
+})
+
+// Download multiple files - they all share ONE notification with aggregate progress
+const photos = [
+  { id: 'photo-1', url: 'https://example.com/photo1.jpg' },
+  { id: 'photo-2', url: 'https://example.com/photo2.jpg' },
+  { id: 'photo-3', url: 'https://example.com/photo3.jpg' },
+  // ... potentially thousands of files
+]
+
+const GROUP_ID = 'photo-sync-batch'
+
+for (const photo of photos) {
+  const task = createDownloadTask({
+    id: photo.id,
+    url: photo.url,
+    destination: `${directories.documents}/${photo.id}.jpg`,
+    metadata: {
+      groupId: GROUP_ID,        // Required for grouping
+      groupName: 'Photo Sync',  // Displayed in notification title
+    },
+  })
+    .progress(({ bytesDownloaded, bytesTotal }) => {
+      // Progress tracked per file, notification shows aggregate progress
+    })
+    .done(() => {
+      console.log(`Downloaded ${photo.id}`)
+    })
+    .error(({ error }) => {
+      console.error(`Failed ${photo.id}:`, error)
+    })
+
+  task.start()
+}
+
+// User sees: ONE notification showing "45% - 3 files" with progress bar
+// instead of 3 separate notifications cluttering the notification shade
+// Notification automatically disappears when all downloads complete
+```
+
 **Grouping downloads by category:**
 
-When notification grouping is enabled, you can group related downloads (e.g., by album, playlist, podcast) by passing `groupId` and `groupName` in the task metadata:
+When notification grouping is enabled, you can group related downloads (e.g., by album, playlist, podcast) by passing `groupId` and `groupName` in the task `metadata`:
 
 ```javascript
 import { createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
@@ -650,7 +752,7 @@ const task = createDownloadTask({
   destination: `${directories.documents}/track01.mp3`,
   metadata: {
     groupId: 'album-summer-hits',  // Unique identifier for the group
-    groupName: 'Summer Hits 2024', // Display name in notification
+    groupName: 'Summer Hits 2024', // Display name in notification title
   },
 })
 
@@ -674,6 +776,7 @@ This ensures users always see the download status without unexpected background
 |--------|------|---------|-------------|
 | `showNotificationsEnabled` | boolean | `false` | Show full download notifications. When `false`, creates minimal silent notifications (UIDT jobs require a notification, but it will be barely visible). This is a top-level config option. |
 | `notificationsGrouping.enabled` | boolean | `false` | Enable notification grouping |
+| `notificationsGrouping.mode` | `'individual'` \| `'summaryOnly'` | `'individual'` | Notification display mode. Use `'summaryOnly'` for bulk downloads to show only ONE notification with real-time aggregate progress |
 | `notificationsGrouping.texts` | object | See below | Customizable notification texts |
 
 **Notification texts (`notificationsGrouping.texts`):**
@@ -696,6 +799,7 @@ This ensures users always see the download status without unexpected background
 - This feature only affects Android 14+ (API 34) where UIDT jobs are used
 - On older Android versions, the standard DownloadManager notifications are shown
 - iOS uses system download notifications and doesn't support custom grouping
+- **Use `mode: 'summaryOnly'` when downloading many files** to prevent notification spam - shows ONE notification with aggregate progress bar that updates in real-time
 
 </details>
 
@@ -751,6 +855,8 @@ This can happen with slow-responding servers. The library automatically adds kee
 <summary><strong>Duplicate class errors with react-native-mmkv (Android)</strong></summary>
 
 If you're using `react-native-mmkv`, you don't need to add the MMKV dependency manually - it's already included. The library uses `compileOnly` to avoid conflicts.
+
+`react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support, so you have full ABI coverage including 32-bit devices when using `react-native-mmkv`.
 </details>
 
 <details>

package/android/build.gradle

@@ -36,6 +36,8 @@ android {
         versionName '1.0'
 
         // Support for 16KB memory page sizes (Android 15+)
+        // Note: MMKV 2.x dropped armeabi-v7a support. If your app targets armeabi-v7a,
+        // downgrade to MMKV 1.x in your app's build.gradle (see README for details).
         ndk {
             abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
         }
@@ -78,8 +80,8 @@ dependencies {
     // MMKV dependency for persistent download state storage
     // Uses compileOnly to avoid duplicate class errors when app also uses react-native-mmkv
     // The app must provide MMKV dependency (either directly or via react-native-mmkv)
-    // MMKV 2.0.0+ is required for 16KB memory page size support (Android 15+)
-    compileOnly 'com.tencent:mmkv-shared:2.0.0'
+    // MMKV 1.3.14+ supports both armeabi-v7a (32-bit) and 16KB page sizes (Android 15+)
+    compileOnly 'com.tencent:mmkv-shared:1.3.16'
 
     implementation 'com.google.code.gson:gson:2.12.1'
 }

package/android/src/main/java/com/eko/Downloader.kt

@@ -111,8 +111,18 @@ class Downloader(private val context: Context, private val storageManager: com.e
 
   /**
    * Set the download listener for resumable downloads.
+   * Also sets the UIDT listener on Android 14+ so that ongoing UIDT jobs
+   * (e.g. ones that survived app termination) can forward events to JS after
+   * the app is reopened.
    */
   fun setResumableDownloadListener(listener: ResumableDownloader.DownloadListener) {
+    // For UIDT jobs (Android 14+), set the listener directly on the registry.
+    // This reconnects event forwarding after app restart when UIDT jobs are
+    // already running but UIDTJobRegistry.downloadListener was null in the
+    // fresh process.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+      UIDTDownloadJobService.downloadListener = listener
+    }
     executeWhenServiceReady {
       downloadService?.setDownloadListener(listener)
     }