mapzone_flutter_alert_plugin #

Flutter plugin for the MapZone Speed Alert SDK. It delivers real-time speed-limit signs, over-speed status, upcoming signs, speed-camera and toll-gate alerts, and voice warnings — for Android and iOS — behind a single Dart API.

The plugin wraps the native Speed Alert engine, pulled automatically from the published native packages:

• Android: com.github.mapzone-global:mapzone_speed_alert_android:2.0.1 (JitPack)
• iOS: MapZoneSpeedAlertSDK 2.0.1 (CocoaPods)

Table of Contents #

• Features
• Requirements
• Installation
• Android Setup
• iOS Setup
• Quick Start
• GPS modes
• Muting voice categories
• Vehicle types
• Error codes
• API Reference
• Example
• License

Features #

• 🚦 Current speed-limit sign + compliance status (compliant / approaching / exceeding)
• ⏭️ Next sign, speed camera and toll gate with distance-to-go
• 🔊 Voice-alert WAV clips forwarded to Flutter with trigger + priority
• 🔇 Per-category voice muting (setMutedAlertTypes); muting a camera / toll category also hides its on-screen sign
• 📍 Two GPS modes:
  • Standalone: the plugin captures native GPS and drives the engine
  • Injected: feed navigation-snapped GPS via processExternalLocation()
• 🖼️ Sign images delivered as PNG bytes with native change-detection caching (no re-encoding every frame)

Requirements #

Installation #

Add the plugin to your app:

flutter pub add mapzone_flutter_alert_plugin

The native Speed Alert SDK (2.0.1) is declared by the plugin and resolved automatically — you do not build it yourself. You only need to make the two package hosts reachable from your app (below).

Android Setup #

The Android SDK is hosted on JitPack, so your app must declare that repository. In modern Gradle the repository has to be added by the app, not the plugin — add it to your android/settings.gradle (or android/build.gradle):

// android/settings.gradle(.kts) — inside dependencyResolutionManagement { repositories { … } }
maven { url = uri("https://jitpack.io") }

Permissions are already declared by the plugin (listed here for reference): ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION, INTERNET, FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION.

iOS Setup #

The iOS SDK is a published CocoaPods pod, so a plain pod install resolves it — no extra source needed.

Add the location usage descriptions to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to provide real-time speed alerts.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Keeps speed alerts running while you drive.</string>
<key>UIBackgroundModes</key>
<array><string>location</string></array>

Set the app deployment target to 14.0 in ios/Podfile:

platform :ios, '14.0'

Quick Start #

import 'package:mapzone_flutter_alert_plugin/mapzone_flutter_alert_plugin.dart';

final alert = VietmapAlertController.instance;

// 1. Configure the engine. bundleId is read natively from the app itself and
//    must match the bundle id registered for the API key.
await alert.initialize(const AlertConfig(
  baseUrl: 'https://driving.map.zone',
  apiKeyId: 'YOUR_API_KEY_ID',
  apiKey: 'YOUR_API_KEY',
  vehicleId: 'YOUR_VEHICLE_ID',
  vehicleType: VehicleType.car, // car=1, motorcycle=2, truck=3, … emergency=9
  seats: 4,
  weight: 1500, // kg (int)
));

// 2. Listen to the alert streams.
alert.onReady.listen((r) => print('ready: ${r.linkCount} links'));
alert.onAlert.listen((e) {
  // e.currentSpeedLimitSign is Uint8List? PNG -> Image.memory(...)
  // e.speedStatus, e.nextDistanceMeters, e.cameraDistanceMeters, e.tollDistanceMeters
});
alert.onVoice.listen((v) => playWav(v.wav, v.priority)); // your audio player
alert.onResult.listen((r) { if (!r.success) print('error ${r.errorCode}'); });
alert.onLocation.listen((l) => print('${l.speedKmh} km/h'));

// 3. Standalone mode — native GPS capture.
if (await alert.requestLocationPermissions()) {
  await alert.start();
}

// 4. Tear down.
await alert.stop();
await alert.reset();

Register alert.registerLifecycleObserver() once to forward background/foreground transitions to the engine.

GPS modes #

The engine needs a stream of GPS positions. There are two ways to provide them:

• Standalone — call start() and the plugin captures native GPS itself. Best when the alert engine is the only thing that needs location.

• Injected — feed positions yourself with processExternalLocation(). Use this to reuse the snapped location from a navigation SDK so the alert and the map agree:

  await alert.processExternalLocation(
    lat: 21.02, lng: 105.83, bearing: 90, speedKmh: 45,
  );
  

Muting voice categories #

setMutedAlertTypes silences specific VoiceAlertType categories (speed camera, toll, red-light camera, no-overtaking, rest station, …). Muting a camera or toll category also hides its on-screen sign; the other categories are voice-only (they have no icon). Core speed-limit and speeding cues can never be muted — they are safety cues and are always announced.

await alert.setMutedAlertTypes([VoiceAlertType.speedCamera, VoiceAlertType.toll]);
await alert.setMutedAlertTypes([]); // re-enable all

Vehicle types #

VehicleType codes match the native SDK enum:

car=1, motorcycle=2, truck=3, coach=4, bus=5, taxi=6, bicycle=7, pedestrian=8, emergency=9.

Only some types support speed alerts; an unsupported type is reported through onResult with error code 3003.

Error codes #

AlertResult.errorCode:

0 success · 1001 invalid parameter (e.g. coordinates out of bounds) · 2003 unauthorized / expired API key · 3003 unsupported vehicle type · < 0 network / parsing error.

API Reference #

Event streams

Example #

See example/ for a single-screen demo app: a map screen with a destination search box (autocomplete / place v4). Pick a destination → the route is built and drawn → start simulated navigation; the snapped GPS is fed into the engine via processExternalLocation, the speed-limit / camera / toll signs render as a HUD, a speed chip shows the over-speed status, and a floating button configures voice muting per VoiceAlertType. Vehicle profile and route simulation are set from a settings dialog.

The route / map is drawn by the example's own navigation SDK — this alert plugin does not render maps; it only consumes GPS and emits sign / voice events.

Fill your Speed Alert credentials (and the map API key) in example/lib/env.dart before running.

License #

MIT — see LICENSE.