Download large files in the background or foreground from your Capacitor app, with pause, resume and progress events. Downloads keep going when users leave the screen.
Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.
14-day unlimited free trial. No credit card required
🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use
@capgo/capacitor-downloaderin your Capacitor app:npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-downloader to my Capacitor app and wire it up." Agent setup guides · Hosted MCP
We build, improve and fix our plugins with heavy use of AI, so issues usually get fixed in under a day and pull requests get feedback the same day. A human still reviews, tests and merges 50+ pull requests daily.
- Most plugin issues get a fix pull request the same day, often within a couple of hours, and are usually resolved in one to two days.
- Every pull request goes through our AI review system, usually within minutes.
- Our AI pre-checks tests, code review, conventions and security, then a human reviews, tests and merges.
- A human, Martin, reviews, tests and merges 50+ pull requests every day.
- In the last 90 days, 95% of plugin issues were resolved.
Learn more about how we build with AI
Use this when users fetch several large files and keep using other apps:
- iOS: background
URLSessioninstances warm up at launch. WireCapacitorDownloaderLifecycleinAppDelegate(see below) sohandleEventsForBackgroundURLSessionfinishes relaunched work. - iOS paths:
files/...andcache/...stay under Documents as in 8.7.0. Useprivate/...(iOS only) for Application Support. Reject..in path segments. - iOS 26+: set
iosContinuedProcessingTitle(and optionaliosContinuedProcessingSubtitle) for a continued-processing task while the device is locked. If it expires, the download is cancelled (not resumed on relaunch). - Android OkHttp: default
notification: 'completed'matches 8.7.0 (no ongoing notification, no foreground service). Setnotification: 'progress'to opt in to ongoing progress and an optionaldataSyncforeground service (minSdk 24; Android 12+ may block background starts). Downloads continue if the service cannot start. The manifest mergesPOST_NOTIFICATIONS; on Android 13+ request it at runtime when you use'progress'.
await CapacitorDownloader.download({
id: 'offline-pack',
url: mapPackUrl,
destination: 'files/offline/pack.zip',
androidHttpEngine: 'auto',
notification: 'progress',
title: 'Offline maps',
description: 'Downloading map data',
iosContinuedProcessingTitle: 'Offline maps',
iosContinuedProcessingSubtitle: 'Pack 3 of 5',
downloadCompletedNotificationText: 'Maps are ready',
});Forward background URL session events from AppDelegate (required for relaunch completion; warmup alone is not enough):
import CapacitorDownloaderPlugin // SPM. CocoaPods: import CapgoCapacitorDownloader
func application(_ application: UIApplication, didFinishLaunchingWithOptions ...) -> Bool {
CapacitorDownloaderLifecycle.warmUpBackgroundSessions()
return true
}
func application(_ application: UIApplication,
handleEventsForBackgroundURLSession identifier: String,
completionHandler: @escaping () -> Void) {
CapacitorDownloaderLifecycle.handleEventsForBackgroundURLSession(
identifier: identifier,
completionHandler: completionHandler
)
}For iosContinuedProcessingTitle, add a permitted identifier prefix to Info.plist:
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>$(PRODUCT_BUNDLE_IDENTIFIER).CapacitorDownloader.continuedProcessing.*</string>
</array>(Documentation: https://capgo.app/docs/plugins/downloader/)
Use this when: the server sends
Content-Encoding: gzip(or similar),Content-Lengthis missing or reflects compressed bytes, and your CDN still exposes the uncompressed size in a custom header (for exampleX-Uncompressed-Length).
Without lengthHeader, downloadProgress can sit at 0, jump early to 1, or report bytesTotal that does not match the file on disk. With lengthHeader, native code reads that header from the HTTP response and uses it for progress totals. Progress is always clamped at 1.
Do not add Accept-Encoding: gzip (or similar) to headers. That disables OkHttp transparent decompression on Android and leaves Content-Encoding on the response, so Android OkHttp ignores lengthHeader and progress can stall.
| Scope | lengthHeader |
|---|---|
| Single download, iOS | Supported |
| Single download, Android OkHttp | androidHttpEngine: 'okhttp' or 'auto' on app-private paths |
| Batch download, iOS | Supported (one header name for every file in files) |
| Batch download, Android | Ignored (batches always use DownloadManager) |
| Android DownloadManager (single) | Ignored |
| Web | Ignored |
import { CapacitorDownloader } from '@capgo/capacitor-downloader';
await CapacitorDownloader.addListener('downloadProgress', (event) => {
console.log(event.id, event.progress, event.bytesTotal, event.bytesWritten);
});
await CapacitorDownloader.download({
id: 'gzip-pack',
url: 'https://cdn.example.com/bundle.tar.gz',
destination: 'files/updates/bundle.tar.gz',
androidHttpEngine: 'okhttp',
lengthHeader: 'X-Uncompressed-Length',
});On iOS, batch downloads share one lengthHeader name for every file in files. Android batches always use DownloadManager and ignore lengthHeader.
Full docs: Capgo downloader guide (once released on the website). Tracked with capacitor-downloader#144.
- Downloads:
download()starts a task with optional HTTP headers and awifi-onlyor cellular network rule. - Control:
pause(),resume()andstop()for each download ID. - Progress events:
downloadProgress,downloadCompletedanddownloadFailedlisteners. - Status and files:
checkStatus()for a task andgetFileInfo()for a downloaded file. - Platforms: iOS and Android. iOS uses a background
URLSession. Android usesDownloadManagerby default (same as earlier releases). OkHttp is opt in viaandroidHttpEnginefor app-private destinations. Not available on web. - Android private storage: set
androidHttpEngine: 'auto'or'okhttp'and usecache/...orfiles/...for internal storage.notification: 'hidden'hides DownloadManager progress UI;downloadCompletedNotificationTextcan still alert on success. - Batch downloads (8.7.0): pass
filesondownload()to let native code own a multi-file batch (overall plus per-file progress, one completion when all succeed). Up to 32 files per batch. - Android notification copy (8.6.0): optional
titleanddescriptionon DownloadManager progress notifications (ignored on iOS, Web, and OkHttp).
For several large assets, start one batch instead of many independent downloads. The top-level id is the batch id. Each entry in files needs url and destination. Shared options such as headers, network, and notification apply to every file in the batch.
import { CapacitorDownloader } from '@capgo/capacitor-downloader';
await CapacitorDownloader.addListener('downloadProgress', (event) => {
console.log(event.id, event.progress, event.fileIndex, event.fileProgress);
});
await CapacitorDownloader.download({
id: 'offline-pack',
files: [
{ url: 'https://example.com/a.zip', destination: 'pack/a.zip' },
{ url: 'https://example.com/b.zip', destination: 'pack/b.zip' },
],
notification: 'hidden',
});downloadProgress uses progress and fileProgress from 0 to 1 (same scale as single downloads and checkStatus). Events also include fileIndex while a batch is running. downloadCompleted fires once when every file succeeds. If any file fails, the plugin emits downloadFailed for the batch id (with fileIndex when known) and cancels the rest. Files that already finished successfully stay on disk; only remaining transfers are cancelled.
stop() on a batch: On iOS, deletes paths recorded by recordMovedDestination for that batch (including files that finished before stop()). Batch failure alone does not remove those paths. On Android, removes active DownloadManager entries for in-flight children; completed batch files stay on disk.
Pause and resume: iOS supports pause() and resume() on the batch id. Android rejects pause and resume for batches and single downloads (use stop()).
Process death: On Android, batch state is memory-only and is lost when the process is killed (DownloadManager work may still finish, but the plugin does not rebuild batch progress). On iOS, batch metadata is persisted and restored when the plugin loads (DownloadBatchStore / DownloadBatchCoordinator).
Opt in: set androidHttpEngine to 'auto' or 'okhttp' for downloads into app-private storage (offline packs, encrypted assets, cache). When the option is omitted, every destination uses DownloadManager and legacy app external file paths, including existing cache/... and files/... strings.
await CapacitorDownloader.download({
id: 'offline-pack',
url: 'https://cdn.example.com/pack.zip',
destination: 'files/offline/pack.zip',
androidHttpEngine: 'auto', // OkHttp for files/... and cache/...
notification: 'hidden', // no system notification during transfer; listen to downloadProgress
});androidHttpEngine |
Behavior |
|---|---|
| Omitted | DownloadManager only, legacy destination paths (matches pre-option releases) |
'auto' |
OkHttp for cache/..., files/..., and paths under internal cache/data/files; DownloadManager for external app storage and public-downloads/... |
'okhttp' |
Always OkHttp; rejects public-downloads/... paths |
'downloadManager' |
Always system DownloadManager with legacy destination paths |
Android destination prefixes
| Prefix | Storage when androidHttpEngine is 'auto' or 'okhttp' |
Storage when option is omitted |
|---|---|---|
cache/... |
App cache dir (OkHttp with 'auto') |
App external files (DownloadManager) |
files/... |
App-private files dir (OkHttp with 'auto') |
App external files (DownloadManager) |
public-downloads/... |
Public Downloads folder (DownloadManager) | App external files under public-downloads/... (DownloadManager) |
| Other relative paths | App external files dir (DownloadManager) | App external files dir (DownloadManager) |
Notifications on OkHttp (8.8.0): Only notification: 'progress' opts in to ongoing progress and the optional dataSync foreground service. One ongoing notification covers every concurrent progress download (titles and combined progress when several run at once); the foreground service reuses that same notification instead of posting an extra empty one. Default 'completed' matches 8.7.0, including one "Download complete" notification on success via DownloadCompletionNotifier. downloadCompletedNotificationText is unchanged.
iOS paths (8.8.0): files/ and cache/ still resolve under Documents. New private/ prefix (iOS only) writes under Application Support/CapacitorDownloader/.
Full guide: https://capgo.app/docs/plugins/downloader/getting-started/#android-okhttp-engine
Available since 8.6.0: set title and description on download() so the Android DownloadManager progress notification shows a user-facing label instead of the raw destination file name. Omit either field (or pass empty text) to keep the system default. Applies only on the DownloadManager path; iOS, Web, and OkHttp Android downloads ignore both options.
await CapacitorDownloader.download({
id: 'offline-pack',
url: 'https://cdn.example.com/large-pack.zip',
destination: 'downloads/offline-pack.zip',
notification: 'progress',
title: 'Offline map pack',
description: 'Downloading region data for offline use',
});Full guide: https://capgo.app/docs/plugins/downloader/getting-started/#android-downloadmanager-notification-labels
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
downloadCompletedevents 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 DownloadManagernotificationvisibility option. While your app is in the foreground, Android still posts the completion alert when the download succeeds. - iOS: request authorization with
UNUserNotificationCenterbefore the download finishes. While your app is in the foreground, iOS shows a delivered notification only if your app'sUNUserNotificationCenterdelegate presents it, so without a notifications plugin it is usually silent; usedownloadCompletedevents in that case.
await Downloader.download({
id: 'episode-12',
url: audioUrl,
destination: 'podcasts/episode-12.mp3',
notification: 'hidden',
downloadCompletedNotificationText: t('downloads.episodeReady'),
});A reliable native file downloader built for Capacitor apps that continues downloads even when your app is backgrounded or closed:
- Background downloads - Downloads continue even when app is minimized, backgrounded, or closed (main advantage)
- Progress tracking - Real-time progress updates during downloads
- Network control - Choose between WiFi-only or cellular network downloads
- Custom headers - Add authentication tokens and custom HTTP headers
- Resumable downloads - Pause and resume downloads (platform dependent)
- Event listeners - Monitor download progress, completion, and failures
- Large file support - Handle multi-gigabyte files without memory issues
- Free and open source - No paid services required
Perfect for downloading large media files, offline content, app updates, and any scenario where downloads need to survive app lifecycle events.
The most complete doc is available here: https://capgo.app/docs/plugins/downloader/
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-pluginsThen use the following prompt:
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-downloader` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
npm install @capgo/capacitor-downloader
npx cap syncdownload(...)pause(...)resume(...)stop(...)checkStatus(...)getFileInfo(...)addListener('downloadProgress', ...)addListener('downloadCompleted', ...)addListener('downloadFailed', ...)removeAllListeners()getPluginVersion()- Interfaces
Capacitor plugin for downloading files with background support. Provides resumable downloads with progress tracking.
download(options: DownloadOptions | DownloadBatchOptions) => Promise<DownloadTask>Start a new download task.
| Param | Type | Description |
|---|---|---|
options |
DownloadOptions | DownloadBatchOptions |
- Download configuration |
Returns: Promise<DownloadTask>
pause(options: { id: string; }) => Promise<void>Pause an active download. Download can be resumed later from the same position.
iOS supports pause and resume for single downloads and batches. Android rejects pause and resume for every download, including batches (use stop() instead).
| Param | Type | Description |
|---|---|---|
options |
{ id: string; } |
- Options containing the download task ID |
resume(options: { id: string; }) => Promise<void>Resume a paused download. Continues from where it was paused.
iOS supports pause and resume for single downloads and batches. Android rejects pause and resume for every download, including batches.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; } |
- Options containing the download task ID |
stop(options: { id: string; }) => Promise<void>Stop and cancel a download permanently.
Single downloads: Cancels the transfer. Platform cleanup depends on the OS; the plugin does not guarantee file removal for singles.
Batch id on iOS: Deletes each path recorded by recordMovedDestination for that batch. Batch failure alone does not delete finished files.
Batch id on Android: Removes DownloadManager work for non-finished children. Completed batch files (marked complete or STATUS_SUCCESSFUL in DownloadManager) stay on disk.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; } |
- Options containing the download task ID |
checkStatus(options: { id: string; }) => Promise<DownloadTask>Check the current status of a download.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; } |
- Options containing the download task ID |
Returns: Promise<DownloadTask>
getFileInfo(options: { path: string; }) => Promise<{ size: number; type: string; }>Get information about a downloaded file.
| Param | Type | Description |
|---|---|---|
options |
{ path: string; } |
- Options containing the file path |
Returns: Promise<{ size: number; type: string; }>
addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; fileIndex?: number | undefined; fileProgress?: number | undefined; }) => void) => Promise<PluginListenerHandle>Listen for download progress updates. Fired periodically as download progresses.
For batch downloads, progress and fileProgress use the same 0 to 1 scale as DownloadTask.
| Param | Type | Description |
|---|---|---|
eventName |
'downloadProgress' |
- Must be 'downloadProgress' |
listenerFunc |
(progress: { id: string; progress: number; bytesWritten?: number; bytesTotal?: number; fileIndex?: number; fileProgress?: number; }) => void |
- Callback receiving progress updates |
Returns: Promise<PluginListenerHandle>
addListener(eventName: 'downloadCompleted', listenerFunc: (result: { id: string; }) => void) => Promise<PluginListenerHandle>Listen for download completion. Fired when a download finishes successfully.
| Param | Type | Description |
|---|---|---|
eventName |
'downloadCompleted' |
- Must be 'downloadCompleted' |
listenerFunc |
(result: { id: string; }) => void |
- Callback receiving completion notification |
Returns: Promise<PluginListenerHandle>
addListener(eventName: 'downloadFailed', listenerFunc: (error: { id: string; error: string; fileIndex?: number | undefined; }) => void) => Promise<PluginListenerHandle>Listen for download failures. Fired when a download encounters an error.
| Param | Type | Description |
|---|---|---|
eventName |
'downloadFailed' |
- Must be 'downloadFailed' |
listenerFunc |
(error: { id: string; error: string; fileIndex?: number; }) => void |
- Callback receiving error information |
Returns: Promise<PluginListenerHandle>
removeAllListeners() => Promise<void>Remove all event listeners. Cleanup method to prevent memory leaks.
getPluginVersion() => Promise<{ version: string; }>Get the plugin version number.
Returns: Promise<{ version: string; }>
Represents the current state and progress of a download task.
| Prop | Type | Description |
|---|---|---|
id |
string |
Unique identifier for the download task |
progress |
number |
Download progress from 0 to 1 |
state |
'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR' |
Current state of the download |
Configuration options for starting a single-file download.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Unique identifier for this download task | |
url |
string |
URL of the file to download | |
destination |
string |
Local file path where the download will be saved. On Android, relative paths without androidHttpEngine behave like earlier releases: every relative path, including cache/... and files/..., is stored under app external files via DownloadManager. When you set androidHttpEngine to 'auto' or 'okhttp', optional roots apply: - cache/... saves under app cache (OkHttp with 'auto'). - files/... saves under app-private internal storage (OkHttp with 'auto'). - public-downloads/... saves to the public Downloads folder (DownloadManager). - Any other relative path saves under app external files (DownloadManager with 'auto'). Absolute paths and file:// URIs are supported; 'auto' picks OkHttp when the path is under cache, data, or files dirs. On iOS, optional roots match batch entries (see {@link DownloadFileSpec.destination}). |
|
headers |
{ [key: string]: string; } |
Optional HTTP headers to include in the request | |
network |
'cellular' | 'wifi-only' |
Network type requirement for download | |
priority |
'high' | 'normal' | 'low' |
Download priority level | |
notification |
'completed' | 'progress' | 'hidden' |
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 DownloadManager progress notification; use plugin progress events instead. downloadCompletedNotificationText can still post a completion notification when the transfer succeeds. On the OkHttp Android path, 'completed' (default) keeps 8.7.0 behavior: no ongoing notification and no foreground service. Set 'progress' to opt in to ongoing progress notifications and an optional dataSync foreground service (API 24+; may be blocked in the background on Android 12+). Downloads continue if the service cannot start. Android 13+ requires runtime POST_NOTIFICATIONS when notifications are shown. Ignored on iOS and Web. |
8.2.0 |
title |
string |
Title shown on the Android DownloadManager progress notification. When omitted or empty, the system uses its default (typically the destination file name). Ignored on iOS, Web, and the OkHttp Android download path. | 8.6.0 |
description |
string |
Description shown on the Android DownloadManager progress notification. When omitted or empty, the system uses its default. Ignored on iOS, Web, and the OkHttp Android download path. | 8.6.0 |
androidHttpEngine |
'auto' | 'okhttp' | 'downloadManager' |
Android HTTP stack used for the download. - Omitted: always DownloadManager with legacy destination resolution (same as releases before this option). - 'auto': OkHttp for app-private destinations (cache/..., files/..., or an absolute path under cache/data/files when extended roots apply); DownloadManager for legacy relative paths under app external storage and public-downloads/.... - 'okhttp': always use OkHttp for extended-root destinations. Rejects public-downloads/... paths. Transfers run in the app process and do not continue after the process is killed (unlike DownloadManager on those paths). - 'downloadManager': always use the system DownloadManager with legacy destination resolution. Ignored on iOS and Web. |
8.5.0 |
downloadCompletedNotificationText |
string |
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.5.0 |
lengthHeader |
string |
HTTP response header that carries the uncompressed byte length when the body is transferred compressed (for example Content-Encoding: gzip) and Content-Length is missing or wrong. When the response includes this header with a positive integer, native code uses it for downloadProgress totals and progress is clamped at 1. Examples: X-Uncompressed-Length. Single downloads: Android OkHttp and iOS. Ignored on Web and Android DownloadManager. On Android OkHttp, ignored when the response still includes Content-Encoding (for example after setting Accept-Encoding: gzip on the request). Do not set request Accept-Encoding; OkHttp handles decompression by default. |
8.9.0 |
iosContinuedProcessingTitle |
string |
iOS 26 and later: opt in to a BGContinuedProcessingTask so the system can show download progress while the device is locked. Falls back to the background URL session when the task does not launch in time. If the continued processing task expires, the active transfer is cancelled with downloadFailed and is not resumed automatically. Ignored on Android and Web. The host app must allow $(PRODUCT_BUNDLE_IDENTIFIER).CapacitorDownloader.continuedProcessing.* in BGTaskSchedulerPermittedIdentifiers (see plugin README). |
8.8.0 |
iosContinuedProcessingSubtitle |
string |
Subtitle for the iOS continued processing task. Ignored when iosContinuedProcessingTitle is omitted. |
8.8.0 |
files |
Multi-file batches use files instead. Omit for single-file downloads. |
8.7.0 |
Configuration options for a multi-file batch download.
On Android, multi-file batches use the system DownloadManager only. Each file uses the same androidHttpEngine destination rules as a single download; download() rejects before enqueue if any file would use OkHttp.
Process death: On Android, batch state lives in memory only and is lost when the host process is killed (DownloadManager work may still finish, but the plugin does not rebuild batch progress). On iOS, batch metadata is persisted in DownloadBatchStore (UserDefaults) and restored when the plugin initializes.
When one file fails, remaining transfers are cancelled. Files that already finished successfully stay on disk (Android stops tracking completed children without calling DownloadManager.remove on them).
stop({ id }) on a batch id: On iOS, deletes every path stored via recordMovedDestination for that batch (files written before stop()). A later batch failure does not delete those paths; only stop() removes them. On Android, removes active DownloadManager entries for in-flight children. Finished children stay on disk (plugin marks them complete or STATUS_SUCCESSFUL), including files finished before stop().
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Unique identifier for this batch (shared by every file in files) |
|
files |
DownloadFileSpec[] |
Download multiple files as one native-owned batch. The batch shares the top-level id. Progress events use progress and fileProgress from 0 to 1 (same scale as DownloadTask). downloadCompleted fires once when every file succeeds. Any failure cancels the batch. At most 32 entries are allowed. |
8.7.0 |
url |
|||
destination |
|||
headers |
{ [key: string]: string; } |
Optional HTTP headers to include in the request | |
network |
'cellular' | 'wifi-only' |
Network type requirement for download | |
priority |
'high' | 'normal' | 'low' |
Download priority level | |
notification |
'completed' | 'progress' | 'hidden' |
Android DownloadManager notification visibility for batch transfers only (batches reject OkHttp). - 'completed' (default): show while downloading and keep the notification after completion. - 'progress': show while downloading, remove the notification when finished. - 'hidden': no DownloadManager progress notification; use plugin progress events instead. downloadCompletedNotificationText can still post a completion notification when the transfer succeeds. Ignored on iOS and Web. |
8.2.0 |
title |
string |
Title shown on the Android DownloadManager progress notification. When omitted or empty, the system uses its default (typically the destination file name). Ignored on iOS and Web. | 8.6.0 |
description |
string |
Description shown on the Android DownloadManager progress notification. When omitted or empty, the system uses its default. Ignored on iOS and Web. | 8.6.0 |
androidHttpEngine |
'auto' | 'okhttp' | 'downloadManager' |
Android HTTP stack used for the download. - Omitted: always DownloadManager with legacy destination resolution (same as releases before this option). - 'auto': OkHttp for app-private destinations (cache/..., files/..., or an absolute path under cache/data/files when extended roots apply); DownloadManager for legacy relative paths under app external storage and public-downloads/.... - 'okhttp': always use OkHttp for extended-root destinations. Rejects public-downloads/... paths. Transfers run in the app process and do not continue after the process is killed (unlike DownloadManager on those paths). - 'downloadManager': always use the system DownloadManager with legacy destination resolution. Ignored on iOS and Web. On Android batches, each file uses these rules; the call is rejected if any file would use OkHttp. |
8.5.0 |
downloadCompletedNotificationText |
string |
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.5.0 |
lengthHeader |
string |
HTTP response header that carries the uncompressed byte length when the body is transferred compressed (for example Content-Encoding: gzip) and Content-Length is missing or wrong. When the response includes this header with a positive integer, native code uses it for downloadProgress totals and progress is clamped at 1. Examples: X-Uncompressed-Length. Batch downloads: iOS only (same header name applies to every file in files). Android batches always use DownloadManager and ignore this option. Ignored on Web. |
8.9.0 |
One file entry inside a multi-file download batch.
| Prop | Type | Description |
|---|---|---|
url |
string |
URL of the file to download |
destination |
string |
Local file path where the download will be saved. On Android single-file downloads, relative paths without androidHttpEngine behave like earlier releases: every relative path, including cache/... and files/..., is stored under app external files via DownloadManager. When you set androidHttpEngine to 'auto' or 'okhttp' on a single download, optional roots apply: - cache/... saves under app cache (OkHttp with 'auto'). - files/... saves under app-private internal storage (OkHttp with 'auto'). - public-downloads/... saves to the public Downloads folder (DownloadManager). - Any other relative path saves under app external files (DownloadManager with 'auto'). Multi-file batches on Android use the same destination rules as single downloads for the batch androidHttpEngine value (including extended roots when 'auto' or 'okhttp' is set). The batch is rejected only when a file would use OkHttp (for example cache/... or files/... with 'okhttp'). Absolute paths and file:// URIs are supported on iOS and on Android single downloads. On iOS (since 8.8.0), optional roots: - files/... and cache/... stay under Documents as in 8.7.0 (Documents/files/..., Documents/cache/...). - private/... (iOS only) writes under Application Support/CapacitorDownloader/. Path segments containing .. are rejected. On Android, private/ is not special (treated as a relative path under app storage). Any other relative path still uses the app Documents directory. |
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader
