Available on Android only
You should read about the limitations and tradeoffs of background downloading before you start using it.
Before continuing with usage, make ensure you comply with the appropriate rules and terms of service set by your tile server.
OpenStreetMap's can be found here: specifically bulk downloading is discouraged, and forbidden after zoom level 13. Other servers may have different terms.
This library and/or the creator(s) are not responsible for any violations you make using this package. Remember that this library automatically adds a clear 'with flutter_map_tile_caching' to the User-Agent header.
You should also wrap your application's root widget (such as a Scaffold
) with the FMTCBackgroundDownload
widget.
This is designed to stop the app from terminating when it is taken off the widget tree, such as when the user closes the application. It is safe to leave there even when not downloading: it is intelligent enough to only keep the application alive if there is an ongoing background download.
Unfortunately, background downloading is available on Android only, due to the strict limitations imposed by iOS. This is unlikely to change in the future, especially as I am currently unable to develop for iOS.
In addition, there is no planned support for other platforms.
There is some confusion about the way background process handling works on Android, so let me clear it up for you: it is confusing.
Each vendor (eg. Samsung, Huawei, Motorola) has their own methods of handling background processes.
Some manage it by providing the bare minimum user-end management, resulting in process that drain battery because they can't be stopped easily; others manage it by altogether banning/strictly limiting background processes, resulting in weird problems and buggy apps; many manage it by some layer of control on top of Android's original controls, making things more confusing for everyone.
Therefore there is no guaranteed behaviour when using this functionality. You can see how many vendors will treat background processes here: dontkillmyapp.com; you may wish to link your users to this site so they can properly configure your app to run in the background.
To try and help your users get to the right settings quicker, use the requestIgnoreBatteryOptimizations()
method before starting a background download. This will interrupt the app with either a dialog or a settings page where they can opt-in to reduced throttling. There is no guarantee that this will work, but it should help: this is not required and the background download will still try to run even if the user denies the permissions.
Internally, a foreground service is actually used. This allows the service to run as long as the app hasn't been force stopped.
The effectiveness of the Recovery system is reduced by background downloading.
If the user leaves the application, then the recovery system may report the ongoing background download as failed, as it has no way of knowing about it. If the user tries to retry the download, both downloads may then fail, and the recovery system may fail also.
There is no way of resolving this situation. You may prefer to disable recovery on background downloads all together.
Unlike foreground downloading, where you can Listen For Progress, background downloading does not provide any way to do this, so it is much less customisable.
The download progress notification only displays the percentage progress and number of tiles attempted/max number of tiles (see #available-statistics).