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}');
}

---