google_maps_native_sdk 0.4.0

Native Google Maps plugin for Flutter/FlutterFlow with markers, polylines, caching, events — ideal for mobility apps (e.g., taxi).

Google Maps Native SDK (Flutter/FlutterFlow)

• Native Google Maps plugin (Android Java / iOS Swift) for Flutter, built for mobility apps (e.g., taxi): markers, polylines, events, snapshot and icon caching. Bilingual docs (English/Português) below.

Features

• Native PlatformView (AndroidView / UiKitView).
• Markers with icon by URL (memory + disk cache), anchor, rotation and z-index.
• Polylines (points list or encoded polyline via addPolylineFromEncoded).
• Camera: move/animate, fit bounds with padding.
• Map styling: JSON style or single-color tint via setMapColor(Color, {dark: false}).
• Extras: traffic, buildings, map padding, snapshot.
• Events: marker tap (onMarkerTap stream).

New in 0.3.0 (highlights)

• Map reveal only after map is fully loaded (Android/iOS), with controller.onMapLoaded future.
• Update polyline points in place: controller.updatePolylinePoints(id, points) (no flicker).
• URL icons: decode/resize off-main-thread; default anchor now (0.5, 0.62).
• Static map helper: StaticMapView for lightweight previews and Windows/desktop fallback.

Navigation (Directions + Voice + Follow)

• New: lightweight turn-by-turn helper in Dart. Fetches a Google Directions route, draws the polyline, follows the user's location with camera, and speaks upcoming step instructions.
• API:
  • MapNavigator.start(controller: ..., options: NavigationOptions(...)) → returns a NavigationSession (call stop() to end).
  • NavigationOptions requires a Google Directions API key, origin, destination; supports mode, language (default pt-BR), voiceGuidance, cameraZoom, cameraTilt, followBearing, voiceAheadDistanceMeters, and simple off-route re-route.
• Camera: added animateCamera(target, {zoom, tilt, bearing, durationMs}) to smoothly follow the user.
• Dependencies: http, geolocator, flutter_tts (already included in this package). Your app must handle location permissions.

Usage (simplified):

final session = await MapNavigator.start(
  controller: controller,
  options: NavigationOptions(
    apiKey: 'YOUR_DIRECTIONS_API_KEY',
    origin: LatLng(-23.561, -46.656),
    destination: LatLng(-23.570, -46.650),
    language: 'pt-BR',
    voiceGuidance: true,
  ),
);
// Later: await session.stop();

Routes API (v2)

• RoutesApi.computeRoutes: alternatives, route modifiers (avoid tolls/highways/ferries), advanced waypoints (sideOfRoad, via/stopover), toll info with estimated price, polyline quality, units/language, configurable FieldMask.
• RoutesApi.computeRouteMatrix: compute ETAs for multiple origins/destinations.

Example — compute routes with alternatives and toll info:

final res = await RoutesApi.computeRoutes(
  apiKey: 'YOUR_ROUTES_API_KEY',
  origin: Waypoint(location: LatLng(-23.561, -46.656)),
  destination: Waypoint(location: LatLng(-23.570, -46.650)),
  intermediates: [Waypoint(location: LatLng(-23.566, -46.653), via: true, sideOfRoad: true)],
  modifiers: const RouteModifiers(avoidTolls: false, avoidHighways: true),
  alternatives: true,
  languageCode: 'pt-BR',
  units: Units.metric,
);
for (final r in res.routes) {
  await controller.addPolyline(PolylineOptions(id: 'r${r.index}', points: r.points, color: const Color(0xFF1976D2)));
}

Example — route matrix (batch ETAs):

final matrix = await RoutesApi.computeRouteMatrix(
  apiKey: 'YOUR_ROUTES_API_KEY',
  origins: [Waypoint(location: LatLng(-23.56, -46.65))],
  destinations: [Waypoint(location: LatLng(-23.57, -46.66)), Waypoint(location: LatLng(-23.59, -46.67))],
);

Navigation events (feed ETA, distance, instruction):

session.onProgress.listen((p){ /* p.distanceRemainingMeters, p.etaSeconds */ });
session.onInstruction.listen((i){ /* i.text, i.maneuver, i.distanceMeters */ });
session.onState.listen((s){ /* navigating/offRoute/rerouting */ });
session.onSpeedAlert.listen((a){ /* a.overLimit */ });

Install

• Add dependency in your app pubspec.yaml (path/git or Pub when published).
• Android: add your Google Maps API Key in the app AndroidManifest.xml:
  • <meta-data android:name="com.google.android.geo.API_KEY" android:value="YOUR_API_KEY"/>
• iOS: provide the API key in AppDelegate or Info.plist:
  • GMSServices.provideAPIKey("YOUR_API_KEY") or GMSApiKey in Info.plist.

Quick Start (see example/lib/main.dart)

• Widget: GoogleMapView(initialCameraPosition: CameraPosition(target: LatLng(-23.56,-46.65), zoom: 13), onMapCreated: ...).
• Controller: addMarker(...), addPolyline(...), moveCamera(...), animateToBounds(...), setMapStyle(...), setMapColor(...), takeSnapshot().

Wait for map ready before heavy overlay work:

GoogleMapController? controller;
GoogleMapView(
  initialCameraPosition: CameraPosition(target: LatLng(-23.56, -46.65), zoom: 13),
  onMapCreated: (c) async {
    controller = c;
    await c.onMapLoaded; // tiles & style ready
    await c.addMarker(MarkerOptions(id: 'a', position: LatLng(-23.56,-46.65)));
  },
);

Update an existing polyline without recreate:

await controller!.updatePolylinePoints('route', latestPoints);

Windows/desktop static map (Google Static Maps):

StaticMapView(
  apiKey: 'YOUR_API_KEY',
  width: 600,
  height: 360,
  center: LatLng(-23.56, -46.65),
  zoom: 13,
  polyline: [LatLng(-23.56,-46.65), LatLng(-23.57,-46.66)],
)

FlutterFlow

• Import as Custom Package and use GoogleMapView. Use onMapCreated to wire controller calls via custom actions.

Best practices (mobility/taxi)

• Enable trafficEnabled when useful to reduce visual noise.
• Use setPadding to accommodate panels (e.g., bottom sheet).
• Update driver position with updateMarker (optionally smooth in Dart first).
• Use URL marker icons; built-in memory+disk cache reduces flicker and network.
• For "snake" live traces: decimate incoming points and throttle updates to ~16–32 ms using updatePolylinePoints; avoid removing/adding polylines each frame.

Notes / Limitations

• Location permissions are app responsibility (e.g., permission_handler).
• Clustering is not exposed yet (native Utils libs are included for future work).
• Full offline tiles are not supported; use SDK cache + custom tiles if needed.

—

Google Maps Native SDK (Flutter/FlutterFlow) — Português

• Plugin Flutter com views nativas (Android Java / iOS Swift) do Google Maps, focado em apps de mobilidade (ex.: táxi): markers, polylines, eventos, snapshot e cache de ícones (memória + disco). Documentação bilíngue.

Recursos

• PlatformView nativo (AndroidView / UiKitView).
• Markers com ícone por URL (cache memória + disco), âncora, rotação e z-index.
• Polylines (lista de pontos ou polyline codificado via addPolylineFromEncoded).
• Câmera: mover/animar, bounds com padding.
• Estilização: JSON ou cor única com setMapColor(Color, {dark: false}).
• Extras: tráfego, prédios, padding do mapa, snapshot.
• Eventos: toque em marker (onMarkerTap).

Navegação (Rotas + Voz + Follow)

• Novo: helper leve de navegação em Dart. Busca a rota no Google Directions, desenha a polyline, segue a localização do usuário com a câmera e fala a próxima instrução.
• API:
  • MapNavigator.start(controller: ..., options: NavigationOptions(...)) → retorna NavigationSession (use stop() para encerrar).
  • NavigationOptions exige a Directions API Key, origin, destination; suporta mode, language (padrão pt-BR), voiceGuidance, cameraZoom, cameraTilt, followBearing, voiceAheadDistanceMeters e re-roteamento simples quando sai da rota.
• Câmera: adicionamos animateCamera(target, {zoom, tilt, bearing, durationMs}) para seguir o usuário suavemente.
• Dependências: http, geolocator, flutter_tts (já incluídas). Seu app deve pedir permissões de localização.

Exemplo:

final session = await MapNavigator.start(
  controller: controller,
  options: NavigationOptions(
    apiKey: 'SUA_DIRECTIONS_API_KEY',
    origin: LatLng(-23.561, -46.656),
    destination: LatLng(-23.570, -46.650),
    language: 'pt-BR',
    voiceGuidance: true,
  ),
);
// Depois: await session.stop();

Instalação

• Adicione no pubspec.yaml do app (path/git ou Pub quando publicado).
• Android: adicione a API Key no AndroidManifest.xml do app.
• iOS: forneça a API Key no AppDelegate ou Info.plist.

Uso Rápido

• Widget e controller conforme exemplo em example/lib/main.dart.
• Chaves principais: addMarker, addPolyline, moveCamera, animateToBounds, setMapStyle, setMapColor, takeSnapshot.

FlutterFlow

• Importe como Custom Package e use GoogleMapView com onMapCreated para acionar o controller por ações custom.

Boas práticas

• Habilite trafficEnabled quando útil.
• Use setPadding para acomodar overlays.
• Atualize posição do motorista com updateMarker.
• Ícones por URL com cache (memória + disco) integrado.

Limitações

• Permissões de localização são do app.
• Clustering: previsto para próxima versão.