dynamic_maps_engine 0.0.3

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/rayhanrwa1/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
  }
);

Cost Optimization (Zero API Cost Mode)

This package automatically implements cost-saving logic for Maps usage:

1. Primary Routing (100% Free): It automatically tries to calculate routes using the Open Source Routing Machine (OSRM) first. This completely avoids Google Maps Directions API usage for most trips!
2. Turn-by-Turn Navigation: It natively requests and parses the steps=true parameter from OSRM to provide the same turn-by-turn instruction data you'd expect from Google.
3. Smart Fallback: If OSRM fails or the route is too complex, it automatically falls back to Google Maps to ensure reliability.

IconService

The IconService is now bundled directly into this package! You can now load driver and destination markers easily:

import 'package:dynamic_maps_engine/dynamic_maps_engine.dart';

await IconService.preloadDriverIcon(color: Colors.red); // Supports custom colors!

Cost Comparison Table

Service	Google Maps API Cost	OSRM (This Package) Cost	Savings
Routing / Directions	~$5.00 per 1000 requests	$0.00 (Free)	100%
Turn-by-turn Steps	Included in Directions API	$0.00 (Free)	100%
Map Rendering (Tiles)	~$7.00 per 1000 loads	Normal GMap Cost	-
Geocoding	~$5.00 per 1000 requests	N/A (Can use OSM Geocoding)	-

Note: Google Maps API charges highly for Directions (Routing). By intercepting these requests and redirecting them to OSRM, you save nearly all dynamic routing costs.

API Calls Flow Table

Action	Primary Engine	Fallback Engine	Fallback Condition
Calculate Route	OSRM route/v1/driving	Google Maps directions/json	OSRM Server down, Route not found
Draw Polyline	OSRM Geometry Decode	Google Maps overview_polyline	OSRM Server down, Route not found
Navigation Steps	OSRM steps=true	Google Maps html_instructions	OSRM Server down, Route not found
Alternative Routes	OSRM	Google Maps alternatives=true	Handled automatically