Coffee Mapbox — Flutter Plugin Integration Guide #

This guide explains how to integrate the Coffee Mapbox Flutter plugin, including Mapbox access token setup, location permissions, and initial configuration for both Android and iOS platforms.

Table of Contents #

Table of Contents #

1. Installation

2. Android Setup

3. iOS Setup

4. Build & Run

5. Flutter Map Integration

   • 5.1 CoffeeMapboxView
   • 5.2 CoffeeMapboxController

6. Offline Tile Management

   • 6.1 Creating the Manager
   • 6.2 Listening for Download Status
   • 6.3 Downloading a Tile Region
   • 6.4 Cancelling a Download
   • 6.5 Deleting a Downloaded Region
   • 6.6 Listing All Downloaded Regions

1) Installation #

Add coffee_mapbox to your pubspec.yaml dependencies:

dependencies:
  coffee_mapbox: ^1.0.0

Then run:

flutter pub get

2) Android Setup #

2.1) Add Mapbox Access Token #

1. Open android/app/src/main/res/values/strings.xml.
2. Add your Mapbox token:

<resources>
    <string name="mapbox_access_token">YOUR_MAPBOX_ACCESS_TOKEN_HERE</string>
</resources>

⚠️ Replace YOUR_MAPBOX_ACCESS_TOKEN_HERE with your actual Mapbox token.

2.2) Configure gradle.properties #

Add your token to gradle.properties for Gradle/Maven access:

MAPBOX_DOWNLOADS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN_HERE

This ensures Gradle can download Mapbox SDK artifacts securely during the build.

2.3) Configure Project-level Gradle (android/build.gradle) #

Inside the allprojects { repositories { ... } } section, add the Mapbox Maven repository:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://storage.flutter-io.cn/download.flutter.io' }

        // Mapbox SDK repository
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
            credentials {
                username = "mapbox"
                password = project.findProperty("MAPBOX_DOWNLOADS_TOKEN") ?: ""
            }
            authentication {
                basic(BasicAuthentication)
            }
        }
    }
}

3) iOS Setup #

3.1) Platform Version #

In your ios/Podfile, ensure the platform is at least 13.0:

platform :ios, '13.0'

3.2) Add Mapbox Access Token #

Add your Mapbox token to Info.plist:

<key>MBXAccessToken</key>
<string>YOUR_MAPBOX_ACCESS_TOKEN_HERE</string>

⚠️ Replace the string value with your own Mapbox token.

After updating Info.plist, run:

cd ios
pod install

3.3) Add Location Permissions #

Update Info.plist with these keys:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to show it on the map</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location for navigation and tracking even in the background</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>We need your location for background updates</string>

These keys are required for iOS to prompt the user for location permissions.

4) Build & Run #

From the root of your Flutter project:

flutter clean
flutter pub get
cd ios
pod install
cd ..
flutter run -v

5) Flutter Map Integration & Controller Methods #

5.1) Using CoffeeMapboxView #

Add a map widget to your Flutter widget tree:

final controller = CoffeeMapboxController(
  onMapReady: () => print('Map is ready'),
  onMarkerTap: (id) => print('Marker tapped: $id'),
);

CoffeeMapboxView(
  controller: controller,
  options: CoffeeMapboxMapOptions(
    initialCenter: [37.7749, -122.4194],
    initialZoom: 12,
  ),
);

⚠️ The controller must be attached automatically to the platform view. On iOS and Android, the viewId is set internally and wired to the MethodChannel for communication.

5.2) Controller Methods Overview #

After creating the CoffeeMapboxController, you can manipulate the map:

• Attach to Platform View

controller.attachToView(viewId); // Usually handled automatically

• Map Style

await controller.setStyle('mapbox://styles/mapbox/satellite-v9');

• Markers

await controller.setMarkers([marker1, marker2]);
await controller.removeMarkers(['marker1']);

• Polylines

await controller.setPolylines([polyline1, polyline2]);
await controller.removePolylines(['polyline1']);

• Polygons

await controller.setPolygons([polygon1, polygon2]);
await controller.removePolygons(['polygon1']);

• Camera Control

await controller.setCameraToBounds([point1, point2], padding: 80.0);
await controller.centerOnUserPuck(zoom: 14);

• Dispose Map View

await controller.disposeView();

5.3) Notes #

• Each platform view has a unique viewId that is automatically assigned and used internally for communication between Flutter and native.
• All native map interactions go through the MethodChannel attached to the viewId.
• This setup allows multiple map instances in a single Flutter app (iOS & Android).

6) Offline Tile Management #

6.1 Creating the Manager

final tileManager = CoffeeMapboxTileRegionManager();

6.2 Listening for Download Status

tileManager.addListener((response) {
  print('Region ${response.id} status: ${response.status}');
});

6.3 Downloading a Tile Region

await tileManager.downloadTileRegion(points, padding: 0.001, id: 'myRegionId');

6.4 Cancelling a Download

await tileManager.cancelCurrentDownload();

6.5 Deleting a Downloaded Region

await tileManager.deleteTileRegion('myRegionId');

6.6 Listing All Downloaded Regions

final regions = await tileManager.getDownloadedTileRegions();
for (var region in regions) {
  print('Downloaded region: ${region.id}');
}