dynamic_maps_engine 0.0.2

A plug-and-play Flutter map engine powered by Google Maps.

Dynamic Maps Engine

A robust, plug-and-play Flutter package for real-time location tracking, custom routing, and interactive map navigation.

Built specifically to decouple map rendering and logic from application business logic, this package provides a fully integrated UI component (DynamicMapWidget) that can be dropped into any Flutter application (e.g., Courier Apps, Customer Tracking Apps) with minimal configuration.

Features

• Plug-and-Play Map Widget: A ready-to-use GoogleMap widget complete with polylines, driver icons, destination icons, and an ETA overlay.
• Route Calculation: Finds the optimal routes (including alternatives) between an origin and destination using the Google Directions API.
• Marker Motion: Smoothly animates marker movement along polylines or via raw GPS data, eliminating jumping or stuttering.
• Smart Rerouting: Automatically detects if the target deviates more than 15 meters off-route and recalculates the route seamlessly in the background.
• Navigation Voice: Text-to-speech capabilities for turn-by-turn navigation (e.g., "In 200 meters, turn right").
• Secure Architecture: Does not rely on .env files internally. API keys must be passed securely from your main application's environment configuration.

Installation

Add the dependency to your application's pubspec.yaml:

Local Path (For Development)

dependencies:
  dynamic_maps_engine:
    path: ../dynamic_maps_engine 

Git URL (For Production)

dependencies:
  dynamic_maps_engine:
    git:
      url: https://github.com/YOUR_USERNAME/dynamic_maps_engine.git
      ref: main

Basic Usage

The package is designed to be fully generic. You provide the API key, origin, and destination. The widget handles the UI rendering, drawing the route lines, animating the icons, and updating the ETA automatically.

import 'package:flutter/material.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';
import 'package:dynamic_maps_engine/dynamic_maps_engine.dart';

class MyDeliveryScreen extends StatelessWidget {
  final String mapsApiKey; // Retrieve this securely from your application's environment variables

  const MyDeliveryScreen({Key? key, required this.mapsApiKey}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: DynamicMapWidget(
        apiKey: mapsApiKey,
        
        // Starting location (e.g., Driver's current location)
        origin: const LatLng(-6.200000, 106.816666),
        
        // Destination location (e.g., Customer's address)
        destination: const LatLng(-6.210000, 106.820000),
        
        // Optional: Enable simulation mode for testing
        enableSimulation: true,

        // Optional: Custom Icons (defaults to standard red/blue pins if not provided)
        // driverIcon: myCustomCarBitmap,
        // destinationIcon: myCustomHomeBitmap,
        
        // Callback triggered when GPS location updates
        onLocationUpdated: (position) {
          // Integrate with your backend services here
          // Example: FirebaseService.updateLocation(orderId, position);
          debugPrint("Driver is now at: ${position.latitude}, ${position.longitude}");
        },
      ),
    );
  }
}

Security Note on API Keys

This package strictly avoids reading .env files directly to prevent potential security vulnerabilities and tightly coupled dependencies. Always parse your environment variables in your main application and pass the apiKey string explicitly into DynamicMapWidget or the respective core services.

Advanced Usage (Headless Core Services)

If you require custom UI implementations and prefer not to use the built-in DynamicMapWidget, you can directly access the underlying headless core engines:

Route Calculation

final routeService = RouteCalculationService(apiKey: 'YOUR_API_KEY');
final routes = await routeService.calculateRoutes(origin, destination);

Marker Animation

final markerMotion = MarkerMotionService();
markerMotion.moveTo(
  target: newLocation, 
  onUpdate: (position, bearing, index) { 
    // Handle manual marker updates
  }
);

Location Tracking

final trackingService = LocationTrackingService();
trackingService.startTracking(
  onPositionUpdate: (position, {forceUpdate}) {
    // Handle live GPS updates
  }
);