Skip to content

magiclane/magiclane-flutter-tutorial-app

BranchesTags

Repository files navigation

Magic Lane Flutter Tutorial app

A hands-on Flutter tutorial app for exploring the Magic Lane Maps SDK for Flutter. Learn how to build interactive maps, search for places, navigate turn-by-turn, calculate routes, download offline maps and route recording. Feel free to draw inspiration from it for your own Magic Lane SDK projects, whether partially or entirely.

Magic Lane Flutter Tutorial app

Key Features

Interactive Map Display

  • High-performance map rendering
  • Responsive pan and zoom with gesture controls
  • Multi-touch gestures support (pinch, rotate, tilt)
  • Touch-based landmark selection and POI interaction

GPS Position Tracking

  • Real-time GPS location tracking
  • Follow position mode with automatic map centering
  • Location permission handling for iOS and Android

POI Search

  • Real-time search by name and address
  • Persistent search history with recent queries
  • Distance display from current map center

Route Calculation

  • Multi-modal routing (car, truck, pedestrian, bike, public transport)
  • Route visualization on map
  • Route metrics display (distance, duration, ETA)

Turn-by-Turn Navigation

  • Real-time navigation with live position tracking
  • Navigation simulation mode for testing
  • Turn instructions with distance to next maneuver
  • Destination reached notifications

Offline Map Downloads

  • Browse and download regional map packages
  • Download progress tracking with pause/resume
  • Manage downloaded maps (view, delete)
  • Offline support for downloaded regions

GPS Route Recording & Track Logging

  • Record GPS tracks with precise coordinates
  • Pause/resume recording during activities
  • Visualize recorded routes on map
  • Track metadata (distance, duration, elevation, speed)
  • Recording history and GPX export capability

Getting Started

Prerequisites

  • Flutter SDK: ^3.35.1 or higher
  • Dart SDK: ^3.9.0 or higher
  • IDE: VS Code, Android Studio, or IntelliJ IDEA
  • Magic Lane API Token
  • Platform-specific tools:
    • For iOS: Xcode
    • For Android: Android Studio

Install

  1. Configure your API token

    An API Key is required to unlock the full functionality of these example applications. Follow our guide to generate your API Key.

    If no API Key is set, you can still test your apps, but a watermark will be displayed, and all the online services including mapping, searching, routing, etc. will slow down after a few minutes.

    You can either set your API Key directly in the main.dart file or pass the token directly when running or building the app with the --dart-define=GEM_TOKEN=your_api_token_here command line option.

  2. Platform-specific setup

    First, prepare the project:

    flutter clean
flutter pub get

    Android

    • Generate an APK using the command: flutter build apk with optional --debug or --release flags
    • Deploy to a connected device using: flutter run --use-application-binary build/app/outputs/flutter-apk/app-[debug|release].apk

    iOS

    • Build the iOS application: flutter build ios
    • Deploy to a connected device: flutter run

    Alternatively, open the Xcode workspace located at <project-path>/ios/Runner.xcworkspace to build, execute and debug directly from Xcode.

App Architecture

This Flutter application features a clear separation of concerns using the Provider pattern for state management:

lib/
├── main.dart                      # App entry point
├── providers/                     # State management (Provider pattern)
│   ├── app_providers.dart         # Provider configuration
│   ├── gem_map_provider.dart      # Map state
│   ├── selected_landmark_provider.dart
│   ├── follow_position_provider.dart
│   ├── routing_state_provider.dart
│   ├── navigation_state_provider.dart
│   └── recording_provider.dart    # Recording state management
├── services/                      # Business logic layer
│   ├── recording_service.dart     # SDK recording operations
│   ├── android_foreground_service.dart
│   └── error_service.dart         # Error handling
├── widgets/                       # Reusable UI components
│   ├── app_map.dart               # Main map widget
│   ├── map_overlay_manager.dart   # UI overlay coordination
│   ├── recordings_button.dart
│   └── clear_recording_button.dart
├── search/                        # Search functionality
│   ├── search_bar_widget.dart
│   ├── search_page.dart
│   └── search_result_item.dart
├── routing/                       # Routing features
│   ├── transport_mode_button.dart
│   ├── routing_engine.dart
│   └── routing_panel.dart
├── navigation/                    # Navigation features
│   └── navigation_panel.dart
├── recording/                     # Recording features
│   └── recordings_history_page.dart
├── map_downloads/                 # Offline maps
│   ├── map_downloads_button.dart
│   ├── map_download_page.dart
│   ├── map_download_item.dart
│   ├── controllers/
│   └── widgets/
├── landmark/                     # Landmark features
│   └── landmark_panel.dart
├── l10n/                         # Internationalization
│   └── app_localizations.dart
├── shared/                       # Shared utilities
│   ├── constants/
│   └── widgets/
└── utils/                        # Helper functions

How to Use

Basic Map Display

The app launches with an interactive map centered on a default location. Use standard gestures:

  • Pan: Drag to move the map
  • Zoom: Pinch to zoom in/out or double-tap
  • Rotate: Two-finger rotation gesture

Follow Position

  1. Tap the location button (bottom-right)
  2. Grant location permissions when prompted
  3. Map will center on your current location

Search for Places

  1. Tap the search bar at the top
  2. Type a place name, address, or category
  3. Select from search results
  4. View location on map with landmark panel
  5. View recent searches by tapping the search bar again

Calculate a Route

  1. Select transportation mode (car, pedestrian, bike)
  2. Search and select a destination landmark
  3. Tap the route button in the landmark panel
  4. View route details and alternatives
  5. Tap Start Navigation to begin turn-by-turn guidance

Download Offline Maps

  1. Tap the download button (floating action button)
  2. Browse available map regions
  3. Tap Available Tab for desired regions
  4. Monitor download progress
  5. Switch to Downloaded tab to view and manage downloaded maps

Record a Route

  1. Tap the record button (bottom-right)
  2. Grant necessary permissions (location, notifications)
  3. Start recording your route
  4. Pause/Resume as needed
  5. Stop when finished
  6. View recordings in History (top-right button)
  7. Tap a recording to view on map

Learn about Flutter Maps SDK Integration

This repository includes comprehensive step-by-step tutorials for implementing each Flutter mapping feature from scratch:

  1. Display Map Tutorial - Basic map integration
  2. Follow Position Tutorial - GPS tracking and follow mode
  3. Landmark Selection Tutorial - Interactive landmark selection
  4. Search Functionality Tutorial - Implementing search features
  5. Routing Tutorial - Route calculation and display
  6. Navigation Tutorial - Turn-by-turn guidance
  7. Map Download Tutorial - Offline map management
  8. Recording Tutorial - Route recording implementation

Each tutorial includes a detailed explanation of the concepts, code snippets, and instructions to implement the features step-by-step.

Multi-Language Support

The app supports internationalization using Flutter's localization framework:

  • Supported Languages: English (default), easily extensible
  • Localization Files: lib/l10n/
  • Generated Classes: app_localizations.dart

Adding New Languages

  1. Create ARB files in lib/l10n/
  2. Run code generation: 
    flutter gen-l10n
  3. Add locale to supportedLocales in main.dart

Cross-Platform Support

Platform Supported Notes
Android ✅ Minimum SDK 23 (Android 6.0 Marshmallow)
iOS ✅ Minimum iOS 14.0

Dependencies & Package Requirements | Flutter Pub Packages

Core Dependencies

Package Version Purpose
magiclane_maps_flutter ^3.1.5 Magic Lane Maps SDK
provider ^6.1.5+1 State management
permission_handler ^12.0.1 Runtime permissions
intl ^0.20.2 Internationalization
path ^1.9.1 File path manipulation
path_provider ^2.1.5 App directory access

Recording Dependencies

Package Version Purpose
flutter_local_notifications ^19.5.0 Foreground service notifications
flutter_background_service ^5.1.0 Background recording support

Additional Resources

Magic Lane Documentation

License

Copyright (C) 2025-2026 Magic Lane International B.V.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

A copy of the license is available in the repository's LICENSE file.

Contact Magic Lane at info@magiclane.com for SDK licensing options.

About

Magic Lane Flutter Demo app using Maps SDK for Flutter

Topics

application sdk flutter tutorial-app

Resources

Readme

License

View license

Code of conduct

Code of conduct

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Magic Lane Flutter Tutorial App v1.0.0 Latest
Feb 2, 2026

Packages

 
 
 

Contributors

Languages