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: ^0.1.0
  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 URL

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> {
  MapMetricsController? mapController;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('MapMetrics Atlas Map'),
      ),
      body: MapMetrics(
        styleUrl: 'https://gateway.mapmetrics.org/styles/YOUR_STYLE_ID?token=YOUR_API_KEY',
        onMapCreated: (MapMetricsController controller) {
          setState(() {
            mapController = controller;
          });
        },
        initialCameraPosition: CameraPosition(
          target: LatLng(40.7128, -74.0060), // New York City
          zoom: 10.0,
        ),
      ),
    );
  }
}

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

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 URL 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

Enable debug mode to see detailed logs:

MapMetrics(
  styleUrl: 'your_style_url',
  onMapCreated: (controller) {
    controller.setDebugMode(true);
  },
)

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:

MapMetrics(
  styleUrl: 'your_style_url',
  initialCameraPosition: CameraPosition(
    target: LatLng(lat, lng),
    zoom: zoom,
    bearing: bearing,
    tilt: tilt,
  ),
  onMapCreated: (controller) {
    // Handle map creation
  },
  onMapClick: (point, coordinates) {
    // Handle map clicks
  },
  onStyleLoaded: () {
    // 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.