Some migrations are necessary for a small number of users. These migrations are listed below, theoretically in decreasing number of affected users.

The underlying storage structure is directly compatible with v7, and so migration for that is not required.

Importing

• Return type is now ImportResult This contains both the real store name (may be different to the filename) and whether the import was successful.

• Collision handlers are now called with an additional argument The filename and real store name are now both passed to the collision handler. See .

FMTCInitialisationException's fields have changed to be more useful in debugging initialisation issues, both internally and externally. If processing these issues manually, you'll need to migrate. See the in-code documentation for more information.

FMTC now supports HTTP/2, through ! HTTP/2 support is enabled by default, with a fallback to HTTP/1.1 (both with a timeout of 5 seconds).

In many of the places where HttpClients where previously accepted as arguments, BaseClient subtypes are now required. To continue using a custom HttpClient, wrap it with an IOClient.

In a one word answer: Yes.

FMTC aims to provide all the functionality you will need for caching, in a way that requires little knowledge of the internals of 'flutter_map' and other caching fundamentals, and little effort from you (for most setups).

However, there are two main concerns that apply to most people:

• Can you abide by the GPL v3 license, or do you need an alternative proprietary license? See for more information about this

• Do you require all the functionality and control that FMTC offers?

Answering the second question is the more difficult than answering the first one, but it will tell you whether it's worth your while getting an alternative proprietary license if you need it.

---

You'll want to consider using FMTC over a custom DIY solution if you need any of the features below. These take a long time to reproduce and get right, but we've already done the hard work for you!

• You need to provide bulk downloading or import/export functionality to your users

• You or your users need a lot of fine-grain control over the cached tiles

However, if you match all of the following, you may find that a DIY/custom solution will work better for you.

• You are developing a proprietary application, and we can't reach an agreement for an alternative license I aim to agree a price or deal that works for the both of us, so please do get in touch even if you're unsure if you can afford a license

• You need only very basic caching

• You need only browse caching

If you're still not sure, please get in touch: . I'm always happy to offer guidance :)

Supporting Me

I work on all of my projects in my spare time, including maintaining (along with a team) Flutter's № 1 (non-commercially maintained) mapping library 'flutter_map', bringing it back from the brink of abandonment, as well as my own plugin for it ('flutter_map_tile_caching') that extends it with advanced caching and downloading. Additionally, I also own the Dart encoder/decoder for the QOI image format ('dqoi') - and I am slowly working on 'flutter_osrm', a wrapper for the Open Source Routing Machine.

Sponsorships & donations allow me to continue my projects and upgrade my hardware/setup, as well as allowing me to have some starting amount for further education and such-like. And of course, a small amount will find its way into my Jaffa Cakes fund (https://en.wikipedia.org/wiki/Jaffa_Cakes) - why do you think my username has "Jaffa" in it?

Many thanks for any amount you can spare, it means a lot to me!

(Proprietary) Licensing

I am not a lawyer, and this information is to the best of my understanding. You are urged to read the license yourself for a thorough understanding.

This project is released under GPL v3. For detailed information about this license, see . summarises the license with the following paragraph:

Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.

Essentially, whilst you can use this code within commercial projects, they must not be proprietary - they incorporate this 'licensed work' so they must be available under the same license. You must distribute your source code on request (under the same GPL v3 license) to anyone who uses your program.

However, I am willing to sell custom alternative proprietary licenses on a case-by-case basis and on request.

I learnt (and am still learning) to code with free, open-source software due to my age and lack of money, and for that reason, I believe in promoting open-source wherever possible to give equal opportunities to everybody, no matter their age or financial position. I'm not sure it's fair for commercial proprietary applications to use software made by people for free out of generosity. On the other hand, I am also trying to make a small amount of money from my projects, by donations or by selling licenses. And I recognise that commercial businesses may want to use my projects for their own proprietary applications.

Therefore, if you would like a license to use this software within a proprietary, I am willing to sell a (preferably yearly or usage based) license for a reasonable price. If this seems like what you want/need, please do not hesitate to get in touch at .

Not quite sure about something? No problem. Please get in touch via any of these methods, and I'll be with you as soon as possible:

• For bug reports & feature requests:

• For implementation/general support: The #plugin channel on the

• For other inquires:

The recovery system is designed to rescue failed bulk downloads, in the event of an unexpected error - such as a fatal crash or other external event.

FlutterMapTileCaching.settings;

Settings change the functionality of FMTC throughout a project, and can be useful to setup customizations that are needed across multiple calls.

For example, a project with multiple getTileProvider() calls can configure the here, to reduce duplication and improve maintainability.

This page guides you through a simple, fast setup of FMTC that just enables basic browse caching, without any of the bells and whistles that you can discover throughout the rest of this documentation.

Depend on the latest version of the package from pub.dev, then import it into the appropriate files of your project.

Perform the startup procedure to allow usage of FMTC's APIs and connect to the underlying systems.

Create an isolated space to store tiles and other information to be accessed by the map and other methods.

Enable your FlutterMap widget to use the caching and underlying systems of FMTC.

If you need to stop a bulk download early, you can use the cancel() method to safely exit. No more tiles will be downloaded, and any tiles still within the buffer (see ) will be written.

FlutterMapTileCaching.instance('storeName').metadata;

This library provides a very simple persistent key-value pair storage system, designed to store any custom information about the store. These are stored alongside tiles in the tile database.

For example, your application may use one store per urlTemplate, in which case, the URL can be stored in the metadata.

Add

Add a new key-value pair to the store. For example:

    add(
        key: String,
        value: String,
    );

Read

Read all the key-value pairs from the store, and return them in a Map<String, String>. For example:

    read; // This is a getter

Remove

Remove a key-value pair from the store. For example:

    remove(key: String);

Reset

Remove all the key-value pairs from the store. For example:

It is possible to export an entire store (including tiles and metadata) to a standalone file that can be easily shared and distributed between devices, then imported on any device.

For example, they can be used to create backup systems, sharing systems, or to distribute a preset package of tiles to all users without worrying about managing IO or managing assets!

Without Buffering

Without buffering, every tile is written directly to the database before continuing to the next one (within each simultaneous thread). This requires a write transaction for every tile, which are relatively slow. Without buffering, the database write speed is usually the limiting factor in the download speed.

With Buffering

To avoid this problem, buffering can be used. Tiles are written to an intermediate buffer before being written to the database, in bulk. This means a transaction is only needed for every bulk write operation, which can lead to huge speed improvements (>2x is possible). However, there are two major cons that you should consider before implementing this in your application:

• Memory usage increases significantly When in use, the Memory usage graph within DevTools will likely look like a sawtooth wave. The peak memory usage may be too high for some devices, so you should consider your audience.

• An app crash can lead to data loss Tiles in the buffer will be lost in the event of an app crash, meaning their download will have been wasted. Tiles that have been written previously will not be lost.

It may be appropriate to leave the decision up to each user individually. In this case, ensure you thoroughly explain these cons to the user, to allow them to make an informed decision. Alternatively, you might make a decision based on the platform. Desktop platforms are likely to have enough RAM capable of holding the buffer, whereas some older mobile devices may struggle.

Buffering is disabled by default, and can be enabled in the startForeground method call (the property is not part of the DownloadableRegion).

Buffering can be defined by one of two types of limit, shown below. Neither has a disadvantage in terms of performance, but memory allows finer grain control, at the expense of being less obvious to the user.

• Memory (buffer bytes size)

• Tiles (buffer length)

FMTC.instance('storeName').download.startBackground();

Available Parameters

Additional Preparation

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.

It is possible to re-import a store generated by an Exporting.

With Platform GUI (withGUI)

With A Known File (manual)

Collision/Conflict Resolution

In the event that a store with the same name already exists as the store that is trying to be imported, FMTC has only simple conflict resolution behaviour.

When a collision is detected, the defined callback collisionHandler is called asynchronously, with the filename of the import file in addition to the real name of the contained store. It can return either:

• true: Override the entire existing store and its contents

• false: Skip/cancel the import

Isar Stability Issues

Exporting a store copies the internal store database, 'compresses' it slightly, then renames it appropriately. The files are in the binary format that Isar uses, so they cannot easily be read or modified.

They can have any file extension applied to them - '.fmtc' is used in the example application. The name of the file dictates the name of the store that will be used when importing (without the 'export_' prefix, if still present).

With Platform GUI (withGUI)

With A Known File (manual)

Creating regions is designed to be easy for the user and you (the developer).

The contains a great way you might want to allow your users to choose a region to download, and it shows how to use Provider to share a created region and the number of approximate tiles it has to a download screen.

All regions (before conversion to DownloadableRegion) implement BaseRegion.

must be converted to DownloadableRegions before they can be used to download tiles.

These contain the original BaseRegion, but also some other information necessary for downloading, such as zoom levels and URL templates.

See this basic example:

By not storing pure tiles of sea, we can save a bunch of space on the user's device with every download. But how to do this?

Well, this package does it by analysing the bytes of the tile and checking if it's identical to a sample taken at lat/lng 0, 0 (Null Island) with zoom level 17. This tile should always be sea, and therefore any matching tile must also be sea.

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.

This package contains a full example application - prebuilt for Android and Windows - showcasing the most important features of this package and it's modules.

There are prebuilt applications for Android and Windows available on GitHub.

These are automatically built (using GitHub Actions) from the latest available commits every time the source files change, so may include functionality not yet available via pub.dev installation.

To run the prebuilt Android application on most devices, download the .apk package (from ) to your device, then execute it to install it.

After installation, it will appear in the launcher like any other application.

To run the prebuilt Windows application on most devices, download the .exe package (from ) to your device, then execute it to install it.

To start downloading tiles, you must , even if you do not plan to use the .

It is possible to watch for changes in structures, which can be useful to create dynamic UIs (using StreamBuilders) that consume the other statistics. There are lots of customization options to increase efficiency and reduce junk/useless rebuilds.

To listen for progress events, you can listen to the Stream of DownloadProgress events returned by the startForeground() method, which contains useful statistics about the download.

Listening can be done through any method, such as listen() or the await for loop.

flutter_map Installation & Setup

You must make sure you follow flutter_map's installation and additional setup instructions.

Installation & Setup

To install this module, follow the Installation instructions for this package.

Background Processes

Add the following to 'android\app\src\main\AndroidManifest.xml' and any other manifests:

 <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="packageName">
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS"/>
 <application android:label="appName" android:icon="appIcon">

This will allow the application to acquire the necessary permissions (should the user allow them at runtime) to a background process.

• FOREGROUND_SERVICE: allows the application to start a foreground service - a type of Android service that can run in the background, as long as the application isn't force stopped.

• WAKE_LOCK: allows the background process (technically foreground service) to run even when the device is locked/asleep. Also allows the acquisition of a WiFi lock.

• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS (must be requested at runtime): assists with the background process not being killed by the system.

Background downloading needs to show notifications, which requires a 3rd party package. See it's installation/setup instructions:

To install this module, follow the instructions for this package.

Please follow these additional instructions for supporting Android versions above 11 and building for release:

It is unknown whether this setup is needed in all cases, so it is recommended to follow these only when you receive errors during building your app.

Some developers may have issues when releasing the app or uploading to TestFlight - see for the first report of this problem. This is due to some of this library's dependencies on platform plugins.

• Annotate that access is not needed to the Media, Audio, and Documents directories - this package uses only custom file types. Add these lines to your Podfile just before target 'Runner' do.

• Add UIBackgroundModes capability with the fetch and remote-notifications keys to Xcode, to describe why your app needs to access background tasks - in this case to bulk download maps in the background.

The main basis of this package is the FlutterMapTileCaching object, which exposes the majority of FMTC's APIs (through FMTC.instance), and also contains most of the state needed to connect and communicate with the underlying systems.

Therefore, it must be asynchronously initialised on every app startup, usually in the main method that runs directly after the Flutter environment starts.

import 'package:flutter/widgets.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();   
    
    await FlutterMapTileCaching.initialise();
    // FMTC.instance;
    
    // Run your app and do all of that other stuff
}

Initialisation Safety

Whilst it is (almost) impossible for one of the underlying Isar databases to become corrupted during normal usage, or even due to a bug, it can happen if the database file is modified manually.

In this case, it is currently impossible to avoid a fatal crash during initialisation, as the database reader/parser crashes all Dart threads & isolates without warning. Please see this issue I opened:

However, FMTC has a workaround.

By using a basic temporary text file, the IDs/filenames of successfully opened databases can be recorded. Once all databases have been opened, the file is deleted, meaning that the safety system will not intervene on the next app launch. However, if a database open attempt crashes the app, the file will not be deleted, and it will contain the list of safe databases.

Because the order in which databases are opened is determinate (alphabetical), the app can open every database one by one, (metaphorically) crossing it off the list. When there are no more safe databases, but more database files, the next database is deleted instead of being opened. The initialisation then continues as normal, still using the file appropriatley.

Therefore, one fatal crash is enough to detect one faulty database, and delete it, allowing the app to initialise normally on the next launch.

If there are multiple corrupted databases (n), one fatal crash is needed per database, so the app will successfully open after n + 1.

All of this means that FMTC can usually recover from a database corruption with minimal data loss. However, if the database filenames/IDs are also changed, the behaviour is unspecified, especially if the initialisation file already exists.

Depend On

From

This is the recommended method of installing this package as it ensures you only receive the latest stable versions, and you can be sure pub.dev is reliable.

Just import the package as you would normally, from the command line:

flutter pub add flutter_map_tile_caching
flutter pub add fmtc_plus_background_downloading # OPTIONAL
flutter pub add fmtc_plus_sharing # OPTIONAL

From

If you urgently need the latest version, a specific branch, or a specific fork, you can use this method.

Add the following lines to your pubspec.yaml file under the 'dependencies_override' section:

dependency_overrides:
    flutter_map_tile_caching:
        git:
            url: https://github.com/JaffaKetchup/flutter_map_tile_caching.git
    fmtc_plus_background_downloading: # OPTIONAL
        git:
            url: https://github.com/JaffaKetchup/fmtc_plus_background_downloading.git
    fmtc_plus_sharing: # OPTIONAL
        git:
            url: https://github.com/JaffaKetchup/fmtc_plus_sharing.git

Import

After installing the package, import it into the necessary files in your project:

import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';
import 'package:fmtc_plus_background_downloading/fmtc_plus_background_downloading.dart'; // OPTIONAL
import 'package:fmtc_plus_sharing/fmtc_plus_sharing.dart'; // OPTIONAL

This project is currently maintained by JaffaKetchup (Luka S). I am currently a maintainer of flutter_map, but this project has no other internal links.

Thanks to all contributors, and 'bugDim88' who originally came up with the idea and created a PR for flutter_map. When that PR was closed (it was decided a plugin would be more suitable), I took over the project. Also thanks to all of the 3rd party dependencies and their maintainers.

Sponsors

Many thanks to all my sponsors, not matter how much or how little they donated (in no particular order):

• @tonyshkurenko

• + 3 anonymous or private donors

3rd party cookies are in use by default, for the purpose of internally tracking visits to this site. We use Google Analytics and GitBook's own built-in analytics to perform this. Data collected is kept confidential to the author of this site, and is only used for improvement/insight purposes.

The Google Analytics property in use is not connected to any Ad tracking/provider any more than by default. No ads are shown on this site.

Please get in touch if you have more questions!

Stores also have the method getTileProvider(). This is the point of integration with flutter_map, providing browse caching through a custom image provider, and can be used as so:

This method (and others) optionally take a FMTCTileProviderSettings. These configure the behaviour of the tile provider. Defaults to the settings specified in the , or the package default (see table below) if that is not specified.

FMTCTileProviderSettings can take the following arguments:

This enumerable contains 3 values, which are used to dictate which logic should be used to store and retrieve tiles from the store.

This package provides the ability to download areas of maps, known as 'regions' throughout this documentation. There are built in region shapes that even large apps, such as Google Maps, don't have!

Downloading is extremely efficient and fast, and uses multiple threads and isolates to achieve write speeds of hundreds of tiles per second (if the network/server speed allows).

After downloading, tiles are stored in the same place as when Browse Caching, meaning that no extra setup is needed to use them in a map (other than the usual ).

v6 and v7 have significantly different underlying storage systems, and therefore different APIs. Pre-v6 uses a multi-directory filesystem-based structure, whereas v7 uses a multi-database structure based on Isar.

This page highlights the biggest changes made that will affect the most users - feature additions are not included. Smaller changes are described by in-code documentation or should be self explanatory.

Changes

Initialisation & Root Directory System

Due to the change in the underlying storage system, initialisation has changed to be asynchronous itself, meaning that the previous method of defining the rootDirectory was now overly complicated. So the RootDirectory system has also been simplified.

FlutterMapTileCaching.initialise(
    await RootDirectory

await FlutterMapTileCaching.initialise(
    rootDirectory:

Store Management

Some methods have been removed from store management due to limitations in Isar. The deprecation documentation in-code suggests replacements.

Changes have been made, which has improved cross-platform stability and performance. Some properties have changed: consult the documentation for more information. Migration should be self explanatory.

Validation options have been removed, as any store name (within UTF8) is now acceptable, because the limitations of the filesystem have been removed.

Some Isar database options have been added to manage the database files themselves. These have sensible defaults, although you should check them to make sure they fit your use-case.

With the introduction of for bulk downloading, there are now two additional statistics. The existing statistics successfulTiles and successfulSize will remain work, but with altered functionality: they now report the number of downloaded, not-necessarily persisted (still in buffer), tiles and size respectivley.

persistedTiles and persistedSize now report the number of tiles and size that has actually been written to the database.

Handling collisions with existing stores during imports has gotten easier, with a built-in callback parameter.

These functionalities have been separated into their own modules, in order to simplify the installation of this package.

To add this functionality again, see and .

If you don't use this functionality in your app, you can undo the instructions related to these modules.

Methods and fields related to statistic caching have been removed, along with the underlying statistic cache system. This is because the new Isar databases are fast enough to calculate statistics, to the point where caching would likely result in reduced performance.

FMTC uses Roots and Stores to structure it's data. Previously, these represented actual directories (hence the reference to directories within the codebase), but now they just represent databases.

There is usually only one root (formed of a directory and some miscellaneous databases) per application, which contains multiple stores (formed of a single database holding a descriptor, multiple tiles, and ).

Once you can access FlutterMapTileCaching.instance after , chaining of methods and accessors is used to access functionality.

1. Base Chains are used as an intermediate step to access functionality on Roots and Stores