Quickstart

FMTC is licensed under GPL-v3.

If you're developing an application that isn't licensed under GPL, this affects you and your application's legal right to distribution. For more information, please see (Proprietary) Licensing.

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

1. Install

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

Console/Terminal

flutter pub add flutter_map_tile_caching

import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Depending on your platform, some additional setup may be neccessary (particularly on macOS).

2. Initialise

Perform the startup procedure to allow usage of FMTC's APIs and allow FMTC to spin-up the underlying connections & systems.

Here, we'll use the built-in, default 'backend' storage, which uses ObjectBox. We'll perform the initialisation just before the app starts, so we can be sure that it will be ready and accessible throughout the app, at any time.

main.dart

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

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    
    await FMTCObjectBoxBackend().initialise(...);
    
    // ...
    
    runApp(MyApp());
}

3. Create a store

Create a container that is capable of storing tiles, and can be used to browse cache and bulk download.

Here, we'll create one called 'mapStore', directly after initialisation. Any number of stores can be created, at any point!

main.dart

    // ...
    
    await FMTCStore('mapStore').manage.create();
    
    // ...

4. Connect to 'flutter_map'

Add FMTC's specialised TileProvider to the TileLayer, to enable browse caching, and retrieval of tiles from the specified store.

Double check that the name of the store specified here is the same as the store created above!

map_view.dart

import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

// Stateful widget class definition

class _...State extends State<...> {
  final _tileProvider = FMTCTileProvider(
    stores: const {'mapStore': BrowseStoreStrategy.readUpdateCreate},
  );
  
  @override
  Widget build(BuildContext context) {
    return FlutterMap(
      options: MapOptions(),
      children: [
        TileLayer(
          urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
          userAgentPackageName: 'com.example.app',
          tileProvider: _tileProvider,
          // Other parameters as normal
        ),
      ],
    );
  }
}

5. Wow! Look at that caching...

You should now have a basic working implementation of FMTC that caches tiles for you as you browse the map!

There's a lot more to discover, from store management to bulk downloading, and from statistics to exporting/importing.

Before using FMTC, especially to bulk download or import/export, ensure you comply with the appropriate restrictions and terms of service set by your tile server. Failure to do so may lead to any punishment, at the tile server's discretion.

This library and/or the creator(s) are not responsible for any violations you make using this package.

For example, OpenStreetMap's tile server forbids bulk downloading: https://operations.osmfoundation.org/policies/tiles. And Mapbox has restrictions on importing/exporting from outside of the user's own device.

For testing purposes, check out the testing tile server included in the FMTC project: Testing Tile Server.