A plugin for creating and managing download tasks. Supports iOS and Android.
This plugin is based on WorkManager
in Android and NSURLSessionDownloadTask
in iOS to run download tasks in the background.
iOS
Note: following steps requires to open your ios
project in Xcode.
- Enable background mode.
- Add sqlite library.
- Configure
AppDelegate
:
Objective-C:
/// AppDelegate.h
#import <Flutter/Flutter.h>
#import <UIKit/UIKit.h>
@interface AppDelegate : FlutterAppDelegate
@end
// AppDelegate.m
#include "AppDelegate.h"
#include "GeneratedPluginRegistrant.h"
#include "FlutterDownloaderPlugin.h"
@implementation AppDelegate
void registerPlugins(NSObject<FlutterPluginRegistry>* registry) {
if (![registry hasPlugin:@"FlutterDownloaderPlugin"]) {
[FlutterDownloaderPlugin registerWithRegistrar:[registry registrarForPlugin:@"FlutterDownloaderPlugin"]];
}
}
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[GeneratedPluginRegistrant registerWithRegistry:self];
[FlutterDownloaderPlugin setPluginRegistrantCallback:registerPlugins];
// Override point for customization after application launch.
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
@end
Or Swift:
import UIKit
import Flutter
import flutter_downloader
@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
GeneratedPluginRegistrant.register(with: self)
FlutterDownloaderPlugin.setPluginRegistrantCallback(registerPlugins)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}
private func registerPlugins(registry: FlutterPluginRegistry) {
if (!registry.hasPlugin("FlutterDownloaderPlugin")) {
FlutterDownloaderPlugin.register(with: registry.registrar(forPlugin: "FlutterDownloaderPlugin"))
}
}
- Support HTTP request: If you want to download file via HTTP request, you need to disable Apple Transport Security (ATS). There are two options:
- Disable ATS for a specific domain only: Add following codes to your
Info.plist
file.
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>www.yourserver.com</key>
<dict>
<!-- add this key to enable subdomains such as sub.yourserver.com -->
<key>NSIncludesSubdomains</key>
<true/>
<!-- add this key to allow standard HTTP requests, thus negating the ATS -->
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
<!-- add this key to specify the minimum TLS version to accept -->
<key>NSTemporaryExceptionMinimumTLSVersion</key>
<string>TLSv1.1</string>
</dict>
</dict>
</dict>
- Completely disable ATS: Add following codes to your
Info.plist
file.
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key><true/>
</dict>
- Configure maximum number of concurrent tasks: the plugin allows 3
DownloadTask
s running simultaneously by default. If you enqueue more than 3 tasks, there're only 3 tasks running, other tasks are put in a pending state. You can change this number by adding the following code to yourInfo.plist
file:
<!-- changes this number to configure the maximum number of concurrent tasks -->
<key>FDMaximumConcurrentTasks</key>
<integer>5</integer>
- Localize notification messages: The plugin will send a notification message to notify the user in case all files are downloaded while your application is not running in foreground. This message is in English by default. You can localize this message by adding and localizing the following message in
Info.plist
file. You can find the detail ofInfo.plist
localization in this link.
<key>FDAllFilesDownloadedMessage</key>
<string>All files have been downloaded</string>
Note: This plugin only supports saving files in NSDocumentDirectory
.
Android
-
If your project is running on Flutter versions prior v1.12, have a look at this document to configure your Android project.
-
From Flutter v1.12 with Android v2 embedding there's no additional configurations required to work with background isolation in Android, but you need to setup your project properly. See upgrading pre 1.12 Android projects.
-
In order to handle notification clicks to open the downloaded file, you need to add some additional configurations. Add the following codes to your
AndroidManifest.xml
:
<provider
android:name="vn.hunghd.flutterdownloader.DownloadedFileProvider"
android:authorities="${applicationId}.flutter_downloader.provider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/provider_paths"/>
</provider>
Note:
- You have to save your downloaded files in external storage, where the other applications have permission to read your files.
- The downloaded files can only be opened if your device has at least one application that can read these file types (mp3, pdf, etc).
- Configure maximum number of concurrent tasks: The plugin depends on
WorkManager
library andWorkManager
depends on the number of available processor to configure the maximum number of tasks running at a moment. You can setup a fixed number for this configuration by adding the following code to yourAndroidManifest.xml
:
<provider
android:name="androidx.work.impl.WorkManagerInitializer"
android:authorities="${applicationId}.workmanager-init"
tools:node="remove" />
<provider
android:name="vn.hunghd.flutterdownloader.FlutterDownloaderInitializer"
android:authorities="${applicationId}.flutter-downloader-init"
android:exported="false">
<!-- changes this number to configure the maximum number of concurrent tasks -->
<meta-data
android:name="vn.hunghd.flutterdownloader.MAX_CONCURRENT_TASKS"
android:value="5" />
</provider>
- Localize notification messages: you can localize notification messages of download progress by localizing following messages. You can find more details about string localization on Android here.
<string name="flutter_downloader_notification_started">Download started</string>
<string name="flutter_downloader_notification_in_progress">Download in progress</string>
<string name="flutter_downloader_notification_canceled">Download canceled</string>
<string name="flutter_downloader_notification_failed">Download failed</string>
<string name="flutter_downloader_notification_complete">Download complete</string>
<string name="flutter_downloader_notification_paused">Download paused</string>
- PackageInstaller: In order to open APK files, your application needs
REQUEST_INSTALL_PACKAGES
permission. Add the following code in yourAndroidManifest.xml
:
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
At the beginning of your main
method, initialize the package:
await FlutterDownloader.initialize();
Then, you can create new DownloadTask
s anywhere in your app:
final task = await DownloadTask.create(
url: 'https://...',
downloadDirectory: await getExternalStorageDirectory(),
);
Note: The
getExternalStorageDirectory
method used here is from the path_provider package.
Once you got a task, you can do stuff with it.
For example, you can wait until the download completed and then open the downloaded file:
await task.wait();
final wasSuccessfullyOpened = await task.openFile();
Note: in Android, you can only open a downloaded file if it is placed in the external storage and there's at least one application that can read that file type on your device.
You can also listen for taks.updates
, which is especially useful when showing progress to the user:
StreamBuilder<DownloadTask>(
stream: task.updates,
initialData: task,
builder: (_, __) => LinearProgressIndicator(value: task.progress),
);
And there's so much more you can do: You can pause
and resume
tasks, cancel
them and retry
failed or canceled tasks.
For a demonstration of all of these, check out the example.
There's also some global methods under the FlutterDownloader
, for example to load or cancel all tasks.
Advanced stuff
Internally, all DownloadTask
s are stored in an SQL database.
You can directly query into this database:
final tasks = await FlutterDownloader.loadTasksWithRawQuery(query: 'SELECT * FROM task WHERE status=3');
Note: This is the schema of the
task
table:CREATE TABLE `task` ( `id` INTEGER PRIMARY KEY AUTOINCREMENT, `task_id` VARCHAR ( 256 ), `url` TEXT, `status` INTEGER DEFAULT 0, `progress` INTEGER DEFAULT 0, `file_name` TEXT, `saved_dir` TEXT, `resumable` TINYINT DEFAULT 0, `headers` TEXT, `show_notification` TINYINT DEFAULT 0, `open_file_from_notification` TINYINT DEFAULT 0, `time_created` INTEGER DEFAULT 0 );
If you encounter any problems or feel the library is missing a feature, feel free to open an issue on GitHub.