Flutter Setup with MapMetrics

This guide will walk you through setting up a Flutter project to use MapMetrics Atlas API with the MapMetrics Flutter package.

Step 1: Create a New Flutter Project

First, create a new Flutter project:

flutter create mapmetrics_demo
cd mapmetrics_demo

Step 2: Add Dependencies

Open your pubspec.yaml file and add the MapMetrics dependency:

dependencies:
  flutter:
    sdk: flutter
  mapmetrics: ^1.0.6
  cupertino_icons: ^1.0.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^2.0.0

Then run:

flutter pub get

Step 3: Platform Configuration

Android Configuration

1. Update Android Manifest (android/app/src/main/AndroidManifest.xml):

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Add internet permission -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    
    <application
        android:label="mapmetrics_demo"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- ... rest of your manifest -->
    </application>
</manifest>

2. Update build.gradle (android/app/build.gradle):

android {
    compileSdkVersion 33
    
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }
}

iOS Configuration

1. Update Info.plist (ios/Runner/Info.plist):

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when open to show your position on the map.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to location when in the background to show your position on the map.</string>

2. Update Podfile (ios/Podfile):

platform :ios, '12.0'

Step 4: Get MapMetrics Credentials

1. Create API Key:

   • Visit MapMetrics Portal
   • Sign up or log in
   • Go to "Keys" section
   • Click "New Key"
   • Configure permissions and allowed domains
   • Copy your API key

2. Create Map Style:

   • Go to "Styles" section in the portal
   • Click "New Style"
   • Choose a template or create custom
   • Customize colors, fonts, and features
   • Save and copy the style ID

Step 5: Create Your First Map

Replace the contents of lib/main.dart:

import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'MapMetrics Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MapScreen(),
    );
  }
}

class MapScreen extends StatefulWidget {
  @override
  _MapScreenState createState() => _MapScreenState();
}

class _MapScreenState extends State<MapScreen> {
  MapController? mapController;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('MapMetrics Atlas Map'),
      ),
      body: MapMetricsView(
        options: MapOptions(
          initStyle:
              'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY',
          initCenter: Position(-74.0060, 40.7128), // lng, lat — New York City
          initZoom: 10.0,
        ),
        onMapCreated: (MapController controller) {
          setState(() {
            mapController = controller;
          });
        },
      ),
    );
  }
}

Step 6: Replace Placeholder Values

Replace the following in your code:

• YOUR_STYLE_ID: Your MapMetrics style ID
• YOUR_API_KEY: Your MapMetrics API key

Step 7: Run the App

flutter run

Step 8: Add Attribution (Required)

Add the required attribution to your app. You can do this in your app's about section or settings:

Widget buildAttribution() {
  return Column(
    children: [
      Text('© MapMetrics'),
      Text('© OSM contributors'),
    ],
  );
}

Alternatively, drop the SDK's built-in SourceAttribution() widget into mapChildren on MapMetricsView and it will render the attribution the loaded style requires automatically.

Troubleshooting

Common Issues

1. Build Errors: Make sure you're using Flutter 3.0.0+ and have the correct SDK versions
2. Map Not Loading: Verify your API key and style ID are correct
3. Permission Errors: Ensure you've added the required permissions in Android/iOS configs
4. Network Issues: Check that your device has internet access

Debug Mode

There's no setDebugMode toggle on MapController. To see what the map is doing, listen to onEvent and log every MapEvent as it arrives:

MapMetricsView(
  options: MapOptions(
    initStyle: 'your_style_url',
  ),
  onMapCreated: (controller) {
    // Handle map creation
  },
  onEvent: (MapEvent event) {
    debugPrint('[MapMetricsView] $event');
  },
)

This surfaces map-created, style-loaded, camera-move, click, and idle events as they happen, which is usually enough to diagnose loading or interaction issues.

Next Steps

Now that you have a basic setup working, try the Basic Map Tutorial to learn more about map interactions and customization.

Configuration Options

You can customize your map with various options:

MapMetricsView(
  options: MapOptions(
    initStyle: 'your_style_url',
    initCenter: Position(lng, lat),
    initZoom: zoom,
    initBearing: bearing,
    initPitch: tilt,
  ),
  onMapCreated: (controller) {
    // Handle map creation
  },
  onEvent: (MapEvent event) {
    if (event case MapEventClick(point: final position)) {
      // Handle map clicks — position is a Position(lng, lat)
    }
  },
  onStyleLoaded: (StyleController style) {
    // Handle style loading
  },
)

---

Remember: Always keep your API keys secure and never commit them to version control. Use environment variables or secure storage for production apps.