mapzone_nav_speed_alert 1.0.0
mapzone_nav_speed_alert: ^1.0.0 copied to clipboard
Speed-limit, camera, toll and road-restriction alerts with voice along a given route, for Flutter navigation apps on Android and iOS.
mapzone_nav_speed_alert #
Speed-limit, camera, toll and road-restriction alerts with voice along a route, for Flutter navigation apps on Android and iOS.
Your app supplies the route polyline and feeds GPS fixes; the plugin returns ready-to-draw sign images on every tick and plays voice alerts.
your navigation app mapzone_nav_speed_alert
─────────────────── ──────────────────────
route built ──── polyline (precision 1e6) ──► start()
GPS fix ~1 Hz ── lat/lng/bearing/speed ─────► onLocation()
│
UI ◄── onSigns speed limit · next · camera · toll (PNG)
UI ◄── onRestriction no stopping · closed · vehicle ban · built-up area · turn
◄── voice built-in player, or onVoice for your own player
◄── onReroute route lost → build a new one, call start() again
Requirements #
| Minimum | |
|---|---|
| Flutter | 3.32 |
| Dart | 3.8 |
| Android | minSdk 24, compiled against SDK 36 |
| iOS | 13.0 |
| Network | Internet access to the alert service |
The plugin does not read GPS, request permissions or draw a map — your app does that and passes positions in.
Getting an integration key #
Contact MapZone on MapZone — and provide:
- the application id of every build that will call the service
(Android package name / iOS bundle id), including debug or flavour ids such
as
com.example.app.debugif you run them; - the kind of vehicles you will configure (see
vehicleType).
You will receive the apiKeyId and apiKey used in
AlertViewConfig.
Application id #
The service authenticates your app by its exact application id, resolved
natively — you do not pass it in Dart. A build whose id is not registered for
the key (for example an Android applicationIdSuffix ".debug" variant) is
rejected and no signs are delivered. Either register that id as well, or run
the build whose id is registered.
Keep apiKey out of source control (e.g. a git-ignored Dart file,
--dart-define, or your secrets pipeline).
Installation #
dependencies:
mapzone_nav_speed_alert: ^1.0.0
Android #
The native SDK is hosted on JitPack, and Gradle resolves it with your app's repositories, so JitPack must be declared in the app project.
If your project declares repositories in android/build.gradle.kts:
allprojects {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
If it uses dependencyResolutionManagement in android/settings.gradle.kts:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
Ensure minSdk is at least 24 and declare the permissions your app uses in
android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
iOS #
Set the platform to iOS 13.0 or later in ios/Podfile, then:
cd ios && pod install
The MapZoneAlertView pod is resolved automatically. Add the location usage
descriptions your app needs to ios/Runner/Info.plist, for example:
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to show speed limits and road alerts.</string>
Add NSLocationAlwaysAndWhenInUseUsageDescription and the location /
audio background modes if you keep navigating with the screen off.
Integration guide #
1. Configure once #
import 'package:mapzone_nav_speed_alert/mapzone_nav_speed_alert.dart';
final alert = NavSpeedAlert.instance;
await alert.configure(const AlertViewConfig(
baseUrl: 'https://…', // from MapZone
apiKeyId: 'your-api-key-id', // from MapZone
apiKey: 'your-api-key', // from MapZone
vehicleId: 'your-vehicle-id', // your own identifier for this vehicle
vehicleType: 1, // 1 = car, see "Vehicle types"
));
configure throws ArgumentError when vehicleType is outside 1..9 and a
PlatformException when the native SDK cannot initialise. Call it again to
change the vehicle profile.
2. Listen to the streams #
Subscribe before start so the first tick is not missed.
final subs = <StreamSubscription<Object>>[
alert.onSigns.listen((e) => setState(() => _signs = e)),
alert.onRestriction.listen((e) => setState(() => _restriction = e)),
alert.onResult.listen((r) {
if (!r.success) debugPrint('alert ${r.errorCode}: ${r.errorMessage}');
}),
alert.onReroute.listen((_) => _rebuildRoute()),
];
Listen to onRestriction and onVoice only if you need them — see
Streams.
3. Start along a route #
await alert.start(routePolyline); // encoded polyline, precision 1e6
The polyline must use precision 1e6 (polyline6), not the common 1e5.
4. Feed GPS fixes #
Call onLocation for every fix, about once per second:
await alert.onLocation(LocationFix(
lat: pos.latitude,
lng: pos.longitude,
bearing: pos.heading,
speedKmh: pos.speed < 0 ? 0 : pos.speed * 3.6, // m/s → km/h; iOS reports -1 when unknown
accuracy: pos.accuracy,
));
Fixes faster than ~1 Hz are dropped by the engine. A position snapped to the route by your navigation SDK works as well as a raw GPS fix.
5. Handle reroutes #
When the vehicle leaves the route, onReroute fires. Build a new route with
your navigation SDK and call start(newPolyline) again — no reset needed.
6. Stop #
await alert.reset(); // releases route and voice state
for (final s in subs) { await s.cancel(); }
Drawing signs #
Every image is PNG bytes; null means the slot is empty. Images are re-rendered
every tick, so use gaplessPlayback to avoid flicker:
Widget sign(Uint8List? png, {double size = 64}) => png == null
? const SizedBox.shrink()
: Image.memory(png, width: size, height: size, gaplessPlayback: true);
Row(children: [
sign(_signs?.current, size: 80),
sign(_signs?.next),
if ((_signs?.nextDistMeters ?? 0) > 0) Text('${_signs!.nextDistMeters} m'),
sign(_signs?.camera),
sign(_signs?.toll),
]);
Use speedStatus to colour your own speedometer — safe, approaching
(within 5 km/h of the limit) or speeding.
Configuration reference #
AlertViewConfig #
| Field | Type | Required | Description |
|---|---|---|---|
baseUrl |
String |
yes | Service base URL, from MapZone. |
apiKeyId |
String |
yes | API key id issued for your application id. |
apiKey |
String |
yes | API key secret. |
vehicleId |
String |
yes | Your identifier for the vehicle. |
vehicleType |
int |
yes | Vehicle class 1..9, see below. |
seats |
int |
no | Number of seats (coaches); 0 = default for the type. |
weights |
double |
no | Gross weight in tonnes (trucks); 0 = default for the type. |
maxSnapMeters |
double |
no | Max distance (m) a fix may be from the route and still snap to it; <= 0 = service default (~25 m). |
Vehicle types #
vehicleType |
Vehicle |
|---|---|
| 1 | Car |
| 2 | Motorcycle |
| 3 | Truck |
| 4 | Coach |
| 5 | Bus |
| 6 | Taxi |
| 7 | Bicycle |
| 8 | Pedestrian |
| 9 | Emergency / priority vehicle |
The type, seats and weight decide which speed limits and vehicle bans apply.
LocationFix #
| Field | Unit | Notes |
|---|---|---|
lat, lng |
degrees (WGS84) | |
bearing |
degrees | 0 = north, 90 = east. |
speedKmh |
km/h | Never negative. |
accuracy |
m | Horizontal accuracy; default 0. |
fixTimeMillis |
ms since epoch (UTC) | Defaults to now. |
API reference #
All members are on NavSpeedAlert.instance.
Methods #
| Method | Description |
|---|---|
configure(AlertViewConfig) |
Credentials + vehicle profile. Call before start. |
start(String polyline) |
Start alerting along a route (precision 1e6). Call again after a reroute. |
onLocation(LocationFix) |
Feed one GPS fix (~1 Hz). |
reset() |
Release route and voice state, e.g. when navigation ends. |
setMutedAlertTypes(Set<VoiceAlertType>) |
Mute voice categories; empty set = announce everything. |
setVoiceMode(VoiceMode) |
full sentences or ding chimes. |
setVoiceSpeed(double) |
Built-in player speed, 1.0 = recorded, clamped to 0.5..2.0, pitch kept. No effect while onVoice has a listener. |
setSegmentUrl(String) |
Override the route-data (segment) endpoint only; '' restores the default derived from baseUrl. |
setExtraHeaders(Map<String, String>) |
Add HTTP headers to segment requests. |
setExtraBodyFields(Map<String, String>) |
Add string fields to segment request bodies. |
setExtraHeaders and setExtraBodyFields should be called after configure
and before start. They return null on success, or an error message — for a
reserved, empty or multi-line key/value — in which case the previous values are
kept. SDK-owned keys cannot be overridden. Pass {} to clear.
Settings made with setMutedAlertTypes, setVoiceMode, setVoiceSpeed,
setSegmentUrl and the extras persist across routes and reset().
Streams #
| Stream | Payload | When |
|---|---|---|
onSigns |
SignsEvent |
Every tick after start. |
onRestriction |
RestrictionEvent |
Every tick, only while listened to — on Android the images are not rendered at all otherwise. |
onVoice |
VoiceEvent |
Per clip, only while listened to — the built-in player is silent for that time. |
onResult |
ResultEvent |
After each route-segment fetch. |
onReroute |
RerouteEvent |
The vehicle has left the route. |
Distances are in metres. A distance of 0 means "currently on it".
SignsEvent
| Field | Type | Description |
|---|---|---|
current |
Uint8List? |
Current speed-limit sign; null when no road is matched. |
speedStatus |
SpeedStatus |
safe, approaching (within 5 km/h) or speeding. |
next / nextDistMeters |
Uint8List? / int |
Next speed-limit sign ahead and its distance. |
camera / cameraDistMeters |
Uint8List? / int |
Nearest camera ahead; the artwork shows the camera kind. |
toll / tollDistMeters |
Uint8List? / int |
Nearest toll booth ahead. |
RestrictionEvent
The slots are independent: one stretch of road can be in a built-up area, closed to your vehicle and no-stopping at once.
| Field | Type | Description |
|---|---|---|
stop / stopDistMeters |
Uint8List? / int |
No-parking / no-stopping sign. |
closed / closedDistMeters |
Uint8List? / int |
Road-closed sign. |
vehicle / vehicleDistMeters |
Uint8List? / int |
Road closed to the configured vehicle type. |
bua / buaDistMeters |
Uint8List? / int |
Built-up-area sign: shown while inside the area, then an end-of-area sign for a few seconds after leaving. |
inBua |
bool |
Whether the vehicle is inside a built-up area. |
turn / turnDistMeters |
Uint8List? / int |
Turn restriction (banned or mandatory manoeuvre). |
VoiceEvent
| Field | Type | Description |
|---|---|---|
wav |
Uint8List |
WAV clip, PCM 16-bit mono 22050 Hz. |
trigger |
int |
Native trigger code of the announcement (see VoiceAlertType.triggerValue). |
priority |
int |
0 current speed (lowest), 1 normal, 2 speeding. |
ResultEvent and RerouteEvent
ResultEvent: success, errorCode, errorMessage (empty on success) — see
Error codes. RerouteEvent: lat, lng of the position where
the route was lost.
Voice alerts #
Built-in player or your own #
By default the native SDK plays alerts through a built-in priority queue —
nothing to do. To play clips yourself (mixing with other audio, custom
ducking…), listen to onVoice:
final voiceSub = alert.onVoice.listen((v) => myPlayer.play(v.wav, v.priority));
// Later: cancel every onVoice subscription to hand playback back to the SDK.
await voiceSub.cancel();
Use priority to decide whether a new clip interrupts the current one.
Voice mode #
await alert.setVoiceMode(VoiceMode.ding);
VoiceMode.full(default): full spoken sentences.VoiceMode.ding: a chime for cameras and no-parking / no-stopping signs, a distinct chime for speeding, silence for everything else.
On-screen signs are identical in both modes.
Muting categories #
await alert.setMutedAlertTypes({VoiceAlertType.toll, VoiceAlertType.noParking});
- Speed-limit and speeding announcements cannot be muted.
- Muting a camera or toll category also hides its sign — there is a single slot for each.
- Muting a restriction category silences the voice only; the sign still shows.
VoiceAlertType |
Code | Muting also hides the sign |
|---|---|---|
speedCamera |
3 | yes |
toll |
4 | yes |
trafficEnforcementCamera |
6 | yes |
redLightCamera |
7 | yes |
aiCamera |
8 | yes |
noLeftTurn, noRightTurn, noUturn, noStraight |
9, 10, 11, 15 | no (no voice is produced for turn signs yet) |
noOvertaking, noOvertakingEnd |
12, 13 | no |
noParking, noStopping |
14, 19 | no |
buildupAreaStart, buildupAreaEnd |
16, 17 | no |
restStation |
18 | no |
roadClosed |
20 | no |
vehicleRestricted |
21 | no |
Error codes #
Reported in ResultEvent.errorCode after a route-segment fetch.
| Code | Meaning | What to check |
|---|---|---|
1001 |
Point outside Vietnam | The route or position is outside coverage. |
1002 |
Missing points | The polyline is empty or too short. |
1003 |
Malformed polyline | Encode with precision 1e6. |
2001 |
Device clock off by more than 10 s | Enable automatic date & time on the device. |
3003 |
Vehicle type outside 1..9 |
AlertViewConfig.vehicleType. |
3004 |
No road matched | The route does not follow mapped roads. |
5000 |
Server error | Retry later; contact MapZone if it persists. |
Example app #
example/ is a complete navigation app (map, search, simulated or
real driving) built on vietmap_flutter_navigation. See
example/README.md for setup.
Support #
- Integration key and commercial questions: MapZone
- Bugs and feature requests: GitHub issues
License #
MIT — see LICENSE.