@mapzone/nav-speed-alert 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/LICENSE +21 -0
- package/README.md +488 -0
- package/android/build.gradle +30 -0
- package/android/src/main/AndroidManifest.xml +2 -0
- package/android/src/main/java/expo/modules/navspeedalert/AlertSignRef.kt +25 -0
- package/android/src/main/java/expo/modules/navspeedalert/ConfigureRecord.kt +17 -0
- package/android/src/main/java/expo/modules/navspeedalert/NavSpeedAlertModule.kt +135 -0
- package/expo-module.config.json +9 -0
- package/ios/AlertSignRef.swift +20 -0
- package/ios/ConfigureRecord.swift +13 -0
- package/ios/EventPayloads.swift +71 -0
- package/ios/NavSpeedAlert.podspec +28 -0
- package/ios/NavSpeedAlertModule.swift +105 -0
- package/package.json +85 -0
- package/src/NavSpeedAlert.types.ts +132 -0
- package/src/NavSpeedAlertModule.ts +26 -0
- package/src/index.ts +114 -0
- package/src/useNavSpeedAlertSigns.ts +79 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0 (2026-09-21)
|
|
4
|
+
|
|
5
|
+
Initial release.
|
|
6
|
+
|
|
7
|
+
- Expo Module wrapping the MapZone Alert View SDK — route-based speed-limit,
|
|
8
|
+
camera, toll and restriction alerts with sign images and voice cues.
|
|
9
|
+
- Requires Expo SDK 57 / React Native 0.86, New Architecture only.
|
|
10
|
+
- Android (Kotlin) and iOS (Swift) modules.
|
|
11
|
+
- Native SDK: Android JitPack `com.github.mapzone-global:mapzone-alert-view-android:1.0.1`,
|
|
12
|
+
iOS CocoaPods `MapZoneAlertView 1.0.1`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vietmap JSC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,488 @@
|
|
|
1
|
+
# Integration Guide — `@mapzone/nav-speed-alert`
|
|
2
|
+
|
|
3
|
+
This guide walks you through adding route-based speed, camera, toll and
|
|
4
|
+
restriction alerts to an Expo / React Native navigation app with
|
|
5
|
+
`@mapzone/nav-speed-alert`. It assumes you already have a navigation engine
|
|
6
|
+
that produces a route polyline and a source of GPS fixes.
|
|
7
|
+
|
|
8
|
+
## 1. Overview
|
|
9
|
+
|
|
10
|
+
The SDK does one job: given the **route** the driver is following and a stream
|
|
11
|
+
of **GPS fixes**, it tells you — once per fix — which signs to show and which
|
|
12
|
+
voice cues to play at that moment. It does not compute routes and it does not
|
|
13
|
+
read GPS itself; your app supplies both.
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
your navigation engine ──► route polyline ──► start(polyline)
|
|
17
|
+
│
|
|
18
|
+
your GPS source ──► onLocation(fix) at ~1 Hz ────────┤
|
|
19
|
+
▼
|
|
20
|
+
native alert engine
|
|
21
|
+
│
|
|
22
|
+
┌──────────────┬───────────────┬───────┴───────┬──────────────┐
|
|
23
|
+
▼ ▼ ▼ ▼ ▼
|
|
24
|
+
onSigns onRestriction onVoice onResult onReroute
|
|
25
|
+
(speed/camera/ (stop/closed/ (WAV clip, (fetch ok / (driver left
|
|
26
|
+
toll images) vehicle/bua/ optional) error code) the route)
|
|
27
|
+
turn images)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Sign images arrive as native references (`AlertSignRef`) that you hand
|
|
31
|
+
straight to `expo-image`. Voice plays through a built-in native player unless
|
|
32
|
+
you choose to receive the clips yourself.
|
|
33
|
+
|
|
34
|
+
## 2. Prerequisites
|
|
35
|
+
|
|
36
|
+
| Requirement | Value |
|
|
37
|
+
|---|---|
|
|
38
|
+
| Expo SDK | ≥ 57 (React Native ≥ 0.86), **New Architecture only** |
|
|
39
|
+
| Build type | Development build or `expo run:*` — **not Expo Go** |
|
|
40
|
+
| iOS | ≥ 16.4, Xcode ≥ 26.4 |
|
|
41
|
+
| Android | minSdk 24 |
|
|
42
|
+
| Peer dependency | `expo-image` (renders the native sign references) |
|
|
43
|
+
| Credentials | `baseUrl`, `apiKeyId`, `apiKey`, `vehicleId` issued by MapZone |
|
|
44
|
+
|
|
45
|
+
**Your application id must be registered with the alert service.** If it does not match what the service has on file,
|
|
46
|
+
every segment fetch fails with a `2xxx` error code (see §8). Register both
|
|
47
|
+
platform ids before testing.
|
|
48
|
+
|
|
49
|
+
The SDK requires location data but does **not** request the permission itself.
|
|
50
|
+
Declare the location permission in your app config and request it at runtime
|
|
51
|
+
as you would for any navigation app (the example in §5 uses `expo-location`).
|
|
52
|
+
|
|
53
|
+
## 3. Installation
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
npx expo install @mapzone/nav-speed-alert expo-image
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Android
|
|
60
|
+
|
|
61
|
+
The native SDK is resolved from JitPack. If your project locks repositories
|
|
62
|
+
with `RepositoriesMode.FAIL_ON_PROJECT_REPOS` in `settings.gradle`, add JitPack
|
|
63
|
+
there:
|
|
64
|
+
|
|
65
|
+
```groovy
|
|
66
|
+
dependencyResolutionManagement {
|
|
67
|
+
repositories {
|
|
68
|
+
maven { url 'https://jitpack.io' }
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The AAR ships its own consumer ProGuard rules and the `INTERNET` permission;
|
|
74
|
+
nothing else to add.
|
|
75
|
+
|
|
76
|
+
### iOS
|
|
77
|
+
|
|
78
|
+
Run `npx pod-install` after installing. The CocoaPods dependency
|
|
79
|
+
`MapZoneAlertView` is declared by the module's podspec. The module is a static
|
|
80
|
+
framework — keep CocoaPods' default linkage, or use
|
|
81
|
+
`use_frameworks! :linkage => :static` if you enable frameworks.
|
|
82
|
+
|
|
83
|
+
### Rebuild
|
|
84
|
+
|
|
85
|
+
Native code changed, so rebuild the app:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
npx expo run:android
|
|
89
|
+
npx expo run:ios
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## 4. Configuration
|
|
93
|
+
|
|
94
|
+
Call `configure()` **once**, before the first `start()`. All fields are
|
|
95
|
+
required.
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import * as NavSpeedAlert from '@mapzone/nav-speed-alert';
|
|
99
|
+
|
|
100
|
+
NavSpeedAlert.configure({
|
|
101
|
+
baseUrl: 'https://<alert-service>',
|
|
102
|
+
apiKeyId: '<your-api-key-id>',
|
|
103
|
+
apiKey: '<your-api-key>',
|
|
104
|
+
vehicleId: '<your-vehicle-id>',
|
|
105
|
+
vehicleType: 1, // 1..9, see table below
|
|
106
|
+
seats: 0, // passenger seats (coaches); 0 = default for the vehicle type
|
|
107
|
+
weights: 0, // gross weight in tonnes (trucks); 0 = default for the vehicle type
|
|
108
|
+
maxSnapMeters: 0, // max distance a GPS fix may be from the route and still count; 0 = server default (~25 m)
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
| `vehicleType` | Vehicle |
|
|
113
|
+
|---|---|
|
|
114
|
+
| 1 | Car |
|
|
115
|
+
| 2 | Motorcycle |
|
|
116
|
+
| 3 | Truck |
|
|
117
|
+
| 4 | Coach |
|
|
118
|
+
| 5 | Bus |
|
|
119
|
+
| 6 | Taxi |
|
|
120
|
+
| 7 | Bicycle |
|
|
121
|
+
| 8 | Pedestrian |
|
|
122
|
+
| 9 | Emergency vehicle |
|
|
123
|
+
|
|
124
|
+
`vehicleType`, `seats` and `weights` decide which restrictions apply to you
|
|
125
|
+
(for example the "vehicle restricted" sign in §6.4 is answered by the service
|
|
126
|
+
for exactly this profile).
|
|
127
|
+
|
|
128
|
+
### Optional request tuning
|
|
129
|
+
|
|
130
|
+
These are rarely needed. Call them after `configure()` and before `start()`;
|
|
131
|
+
they persist across reroutes.
|
|
132
|
+
|
|
133
|
+
| Function | Purpose |
|
|
134
|
+
|---|---|
|
|
135
|
+
| `setSegmentUrl(url)` | Send segment requests to exactly this URL instead of the default endpoint under `baseUrl` — for example to route through your own proxy. `''` restores the default. Authentication always uses `baseUrl`. |
|
|
136
|
+
| `setExtraHeaders(map)` | Add HTTP headers to segment requests. Returns `null` on success or an error message (reserved key such as `Content-Type`, empty key, newline in a value); on error the previous headers are kept. `{}` clears. |
|
|
137
|
+
| `setExtraBodyFields(map)` | Same contract for extra string fields in the request body. Cannot override the SDK's own fields. `{}` clears. |
|
|
138
|
+
|
|
139
|
+
## 5. Session lifecycle
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
// Navigation starts (and again after every reroute):
|
|
143
|
+
NavSpeedAlert.start(routePolyline);
|
|
144
|
+
|
|
145
|
+
// Every GPS fix, ~1 Hz:
|
|
146
|
+
NavSpeedAlert.onLocation({ lat, lng, bearing, speedKmh, accuracy, fixTimeMillis });
|
|
147
|
+
|
|
148
|
+
// Navigation ends:
|
|
149
|
+
NavSpeedAlert.reset();
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### `start(routePolyline)`
|
|
153
|
+
|
|
154
|
+
`routePolyline` is the **full route geometry** from your navigation engine,
|
|
155
|
+
encoded as a Google polyline with **precision 1e6** (not the more common 1e5).
|
|
156
|
+
The engine splits it into segments and fetches speed limits and alerts for each
|
|
157
|
+
on demand as the driver progresses.
|
|
158
|
+
|
|
159
|
+
Call `start()` again with a new polyline whenever the route changes — after a
|
|
160
|
+
reroute, or if the user picks a different destination. This replaces the
|
|
161
|
+
previous route; you do not need to `reset()` first.
|
|
162
|
+
|
|
163
|
+
### `onLocation(fix)`
|
|
164
|
+
|
|
165
|
+
Feed every GPS fix as it arrives, at the usual GPS cadence (~1 Hz). Each field:
|
|
166
|
+
|
|
167
|
+
| Field | Unit / meaning |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `lat`, `lng` | WGS84 degrees |
|
|
170
|
+
| `bearing` | Heading in degrees, 0 = north, 90 = east. Pass `0` if unknown. |
|
|
171
|
+
| `speedKmh` | Current speed in **km/h** (most platform APIs give m/s — multiply by 3.6). |
|
|
172
|
+
| `accuracy` | Horizontal accuracy in metres. Pass a large value (e.g. 100) if unknown, not 0. |
|
|
173
|
+
| `fixTimeMillis` | Fix timestamp, **epoch milliseconds (UTC)**. Pass the fix's own timestamp, not an uptime clock. |
|
|
174
|
+
|
|
175
|
+
If your app already runs map-matched navigation, pass the **snapped** position
|
|
176
|
+
rather than the raw GPS sample — raw fixes can sit 10–20 m off the road centre
|
|
177
|
+
even with good accuracy, and fixes farther than `maxSnapMeters` from the route
|
|
178
|
+
are treated as off-route.
|
|
179
|
+
|
|
180
|
+
A minimal source using `expo-location` (foreground only):
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
import * as Location from 'expo-location';
|
|
184
|
+
import * as NavSpeedAlert from '@mapzone/nav-speed-alert';
|
|
185
|
+
|
|
186
|
+
async function startGps() {
|
|
187
|
+
const { status } = await Location.requestForegroundPermissionsAsync();
|
|
188
|
+
if (status !== 'granted') throw new Error('Location permission denied');
|
|
189
|
+
|
|
190
|
+
return Location.watchPositionAsync(
|
|
191
|
+
{ accuracy: Location.Accuracy.High, timeInterval: 1000, distanceInterval: 0 },
|
|
192
|
+
(loc) => {
|
|
193
|
+
const { heading, speed, accuracy } = loc.coords;
|
|
194
|
+
NavSpeedAlert.onLocation({
|
|
195
|
+
lat: loc.coords.latitude,
|
|
196
|
+
lng: loc.coords.longitude,
|
|
197
|
+
bearing: heading != null && heading >= 0 ? heading : 0, // iOS reports -1 when unknown
|
|
198
|
+
speedKmh: Math.max(0, (speed ?? 0) * 3.6),
|
|
199
|
+
accuracy: accuracy ?? 100,
|
|
200
|
+
fixTimeMillis: loc.timestamp,
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
// Later: (await startGps()).remove();
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### `reset()`
|
|
209
|
+
|
|
210
|
+
Stops alerting, drops the route and clears voice state. Safe to call
|
|
211
|
+
repeatedly. Call it when navigation finishes; also call it on component
|
|
212
|
+
unmount so a hot reload does not leave a stale session running.
|
|
213
|
+
|
|
214
|
+
## 6. Receiving signs
|
|
215
|
+
|
|
216
|
+
This is the part most apps spend their time on, so it is covered in detail.
|
|
217
|
+
|
|
218
|
+
### 6.1 `AlertSignRef` — the image handle
|
|
219
|
+
|
|
220
|
+
Every sign slot is an `AlertSignRef | null`. `null` means "nothing to show in
|
|
221
|
+
this slot — hide it". A non-null ref is a native image (Bitmap on Android,
|
|
222
|
+
UIImage on iOS) that:
|
|
223
|
+
|
|
224
|
+
- renders directly with `expo-image`: `<Image source={ref} />`;
|
|
225
|
+
- can be converted with `ref.toBase64()` (PNG bytes as base64) if you render
|
|
226
|
+
with something other than `expo-image`;
|
|
227
|
+
- **must be released** with `ref.release()` once you no longer display it.
|
|
228
|
+
Skipping this leaks a native image per slot per tick.
|
|
229
|
+
|
|
230
|
+
### 6.2 Three ways to subscribe
|
|
231
|
+
|
|
232
|
+
**A. `useNavSpeedAlertSigns()` — recommended.** The hook keeps the latest
|
|
233
|
+
`onSigns` and `onRestriction` events in React state and releases the previous
|
|
234
|
+
tick's refs for you, including events that were batched between renders. It
|
|
235
|
+
also subscribes to `onRestriction`, which is what makes the engine start
|
|
236
|
+
producing restriction signs.
|
|
237
|
+
|
|
238
|
+
```tsx
|
|
239
|
+
import { useNavSpeedAlertSigns } from '@mapzone/nav-speed-alert';
|
|
240
|
+
import { Image } from 'expo-image';
|
|
241
|
+
|
|
242
|
+
function SpeedOverlay() {
|
|
243
|
+
const { signs, restriction } = useNavSpeedAlertSigns();
|
|
244
|
+
return (
|
|
245
|
+
<>
|
|
246
|
+
{signs?.current && <Image source={signs.current} style={S.sign} />}
|
|
247
|
+
{signs?.camera && (
|
|
248
|
+
<>
|
|
249
|
+
<Image source={signs.camera} style={S.sign} />
|
|
250
|
+
<Text>{signs.cameraDistMeters} m</Text>
|
|
251
|
+
</>
|
|
252
|
+
)}
|
|
253
|
+
{restriction?.stop && <Image source={restriction.stop} style={S.sign} />}
|
|
254
|
+
</>
|
|
255
|
+
);
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Mount one instance of the component that calls the hook for the whole
|
|
260
|
+
navigation screen. Unmounting it removes the listeners and releases the last
|
|
261
|
+
refs.
|
|
262
|
+
|
|
263
|
+
**B. `addSignsListener` / `addRestrictionListener` — manual.** Use these when
|
|
264
|
+
you keep your own state (e.g. outside React, or in a store). You own the
|
|
265
|
+
release protocol: release every ref in an event once you have replaced it with
|
|
266
|
+
a newer one, and release the last event's refs when you stop.
|
|
267
|
+
|
|
268
|
+
```ts
|
|
269
|
+
let last: SignsEvent | null = null;
|
|
270
|
+
const sub = NavSpeedAlert.addSignsListener((e) => {
|
|
271
|
+
render(e);
|
|
272
|
+
if (last) for (const k of ['current', 'next', 'camera', 'toll'] as const) last[k]?.release();
|
|
273
|
+
last = e;
|
|
274
|
+
});
|
|
275
|
+
// On stop:
|
|
276
|
+
sub.remove();
|
|
277
|
+
if (last) for (const k of ['current', 'next', 'camera', 'toll'] as const) last[k]?.release();
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
**C. `toBase64()` — non-`expo-image` hosts.** Subscribe as in B, call
|
|
281
|
+
`ref.toBase64()` on the refs you need, release the ref immediately, and render
|
|
282
|
+
`data:image/png;base64,…` with your image component.
|
|
283
|
+
|
|
284
|
+
### 6.3 The nine sign slots
|
|
285
|
+
|
|
286
|
+
`onSigns` carries four slots plus `speedStatus`; `onRestriction` carries five.
|
|
287
|
+
Slots are independent — several can be non-null at once. Every `*DistMeters`
|
|
288
|
+
is metres along the route from the current position; `0` means "on it now".
|
|
289
|
+
|
|
290
|
+
#### `SignsEvent`
|
|
291
|
+
|
|
292
|
+
| Field | Sign | Shown | Distance |
|
|
293
|
+
|---|---|---|---|
|
|
294
|
+
| `current` | Current speed limit | Always while on the route | — |
|
|
295
|
+
| `speedStatus` | `0` within limit · `1` close to limit · `2` over limit | Always | — |
|
|
296
|
+
| `next` | Next speed limit (differs from `current`) | When a new limit is near ahead | `nextDistMeters` |
|
|
297
|
+
| `camera` | Nearest camera ahead (speed / enforcement / red-light / AI) | When a camera is ahead; gone once passed | `cameraDistMeters` |
|
|
298
|
+
| `toll` | Toll plaza ahead | When a toll plaza is ahead; gone once passed | `tollDistMeters` |
|
|
299
|
+
|
|
300
|
+
#### `RestrictionEvent`
|
|
301
|
+
|
|
302
|
+
| Field | Sign | Shown | Distance |
|
|
303
|
+
|---|---|---|---|
|
|
304
|
+
| `stop` | No-parking / no-stopping | **Only while driving slowly** and on or near a restricted stretch | `stopDistMeters` |
|
|
305
|
+
| `closed` | Road closed | On or near a closed stretch | `closedDistMeters` |
|
|
306
|
+
| `vehicle` | Your vehicle type not allowed | On or near a stretch restricted for your `vehicleType` | `vehicleDistMeters` |
|
|
307
|
+
| `bua` | Built-up (urban) area — entry plate, or end plate | While inside an area, when approaching one, and briefly after leaving | `buaDistMeters` (`0` while inside) |
|
|
308
|
+
| `inBua` | — | `true` while inside a built-up area | — |
|
|
309
|
+
| `turn` | Turn restriction (no left / right / U-turn / straight, or "only …") | When a restricted junction is ahead | `turnDistMeters` |
|
|
310
|
+
|
|
311
|
+
`stop`, `closed` and `vehicle` describe a stretch of road: the sign stays up
|
|
312
|
+
while you are on it, then disappears. `bua` has no voice; the other restriction
|
|
313
|
+
slots do (§7).
|
|
314
|
+
|
|
315
|
+
### 6.4 Rendering tips
|
|
316
|
+
|
|
317
|
+
- Sign images are square; 72×72 dp works well for a primary sign, 48×48 dp for
|
|
318
|
+
a preview row. Set explicit `width`/`height` on the `Image`.
|
|
319
|
+
- Show the distance next to `next`, `camera`, `toll` and the restriction slots;
|
|
320
|
+
omit it for `current` (it has none).
|
|
321
|
+
- Because a new ref arrives every second, avoid keying a list item on the ref
|
|
322
|
+
identity; key on the slot name.
|
|
323
|
+
|
|
324
|
+
## 7. Voice
|
|
325
|
+
|
|
326
|
+
### Built-in player (default)
|
|
327
|
+
|
|
328
|
+
With no `onVoice` listener the native engine plays voice cues itself through a
|
|
329
|
+
priority-aware queue: speed-limit changes, "approaching" warnings, speeding
|
|
330
|
+
warnings, camera / toll / restriction announcements. Nothing to do.
|
|
331
|
+
|
|
332
|
+
### Receiving clips yourself
|
|
333
|
+
|
|
334
|
+
Subscribe to `onVoice` if you want to mix the audio into your own player, duck
|
|
335
|
+
music, or route it to a specific audio session. **While at least one listener
|
|
336
|
+
exists the built-in player is silent** and your app is responsible for playing
|
|
337
|
+
every clip; removing the last listener hands playback back to the built-in
|
|
338
|
+
player.
|
|
339
|
+
|
|
340
|
+
```ts
|
|
341
|
+
const sub = NavSpeedAlert.addVoiceListener((e) => {
|
|
342
|
+
// e.wavBase64: WAV, PCM 16-bit LE, mono, 22 050 Hz
|
|
343
|
+
// e.priority: 0 = "current" (drop first if you fall behind), 1 = normal, 2 = speeding (never drop)
|
|
344
|
+
// e.trigger: native VoiceTrigger id — useful for logging / analytics
|
|
345
|
+
playWav(e.wavBase64, e.priority);
|
|
346
|
+
});
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
`wavBase64` is a complete WAV file; write it to a temporary file and play it
|
|
350
|
+
with your audio library, or decode it and feed an audio track directly. If
|
|
351
|
+
clips can queue up, honour `priority`: shed priority 0 first, then 1, never 2.
|
|
352
|
+
|
|
353
|
+
### Muting categories
|
|
354
|
+
|
|
355
|
+
```ts
|
|
356
|
+
import { VoiceAlertType } from '@mapzone/nav-speed-alert';
|
|
357
|
+
|
|
358
|
+
NavSpeedAlert.setMutedAlertTypes([VoiceAlertType.SPEED_CAMERA, VoiceAlertType.TOLL]);
|
|
359
|
+
NavSpeedAlert.setMutedAlertTypes([]); // unmute everything
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
- Speed-limit and speeding voices are core safety cues and **cannot** be muted.
|
|
363
|
+
- Muting a **camera or toll** category hides its sign as well (there is one
|
|
364
|
+
slot each; a category you do not want should not occupy it).
|
|
365
|
+
- Muting a **restriction** category (`NO_PARKING`, `NO_STOPPING`,
|
|
366
|
+
`ROAD_CLOSED`, `VEHICLE_RESTRICTED`, `BUILDUP_AREA_START/END`) silences the
|
|
367
|
+
voice only; the sign is still delivered.
|
|
368
|
+
- The turn categories (`NO_LEFT_TURN`, `NO_RIGHT_TURN`, `NO_UTURN`,
|
|
369
|
+
`NO_STRAIGHT`) are accepted but currently have no voice — turn signs are
|
|
370
|
+
shown silently.
|
|
371
|
+
|
|
372
|
+
The mute set persists across `start()` / reroutes. See `VoiceAlertType` in
|
|
373
|
+
[`src/NavSpeedAlert.types.ts`](../src/NavSpeedAlert.types.ts) for the full list.
|
|
374
|
+
|
|
375
|
+
## 8. Results
|
|
376
|
+
|
|
377
|
+
### `onResult` — segment fetch outcome
|
|
378
|
+
|
|
379
|
+
Fired once per route segment fetch. Subscribe at least in development so
|
|
380
|
+
authentication and coverage problems are visible.
|
|
381
|
+
|
|
382
|
+
```ts
|
|
383
|
+
NavSpeedAlert.addResultListener((e) => {
|
|
384
|
+
if (!e.success) console.warn(`alert fetch failed ${e.errorCode}: ${e.errorMessage}`);
|
|
385
|
+
});
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
| `errorCode` | Meaning |
|
|
389
|
+
|---|---|
|
|
390
|
+
| `0` | Success — segment loaded |
|
|
391
|
+
| `1001` | A route point is outside the supported area (Vietnam) |
|
|
392
|
+
| `1002` | Missing points / invalid request |
|
|
393
|
+
| `1003` | Route polyline could not be decoded (check the 1e6 precision) |
|
|
394
|
+
| `2001` | Device clock is more than 10 s out of sync with the server |
|
|
395
|
+
| `2002` | Unauthorized — `apiKeyId` / `apiKey` / application id mismatch |
|
|
396
|
+
| other `2xxx` | Session could not be established (surfaced as "session expired") |
|
|
397
|
+
| `3003` | `vehicleType` outside 1..9 |
|
|
398
|
+
| `3004` | Route did not match any road |
|
|
399
|
+
| `5xxx` | Server temporarily unavailable — retry later |
|
|
400
|
+
| negative | Local failure: no connectivity, or the response could not be read (for example a proxy or wrong `setSegmentUrl` returning something other than the service response) |
|
|
401
|
+
|
|
402
|
+
`errorMessage` is short and display-ready.
|
|
403
|
+
## 9. Putting it together
|
|
404
|
+
|
|
405
|
+
A complete minimal integration: configure once, wire listeners, drive a
|
|
406
|
+
session from your navigation state, render the signs.
|
|
407
|
+
|
|
408
|
+
```tsx
|
|
409
|
+
import * as NavSpeedAlert from '@mapzone/nav-speed-alert';
|
|
410
|
+
import { useNavSpeedAlertSigns } from '@mapzone/nav-speed-alert';
|
|
411
|
+
import { Image } from 'expo-image';
|
|
412
|
+
import { useEffect } from 'react';
|
|
413
|
+
import { StyleSheet, Text, View } from 'react-native';
|
|
414
|
+
|
|
415
|
+
// 1. Once at app start (credentials from your config layer).
|
|
416
|
+
NavSpeedAlert.configure({
|
|
417
|
+
baseUrl: config.alertBaseUrl,
|
|
418
|
+
apiKeyId: config.alertApiKeyId,
|
|
419
|
+
apiKey: config.alertApiKey,
|
|
420
|
+
vehicleId: config.alertVehicleId,
|
|
421
|
+
vehicleType: 1,
|
|
422
|
+
seats: 0,
|
|
423
|
+
weights: 0,
|
|
424
|
+
maxSnapMeters: 0,
|
|
425
|
+
});
|
|
426
|
+
|
|
427
|
+
// 2. Session driver: follows your navigation state.
|
|
428
|
+
export function useSpeedAlertSession(route: { polyline1e6: string } | null, gps: GpsSource) {
|
|
429
|
+
useEffect(() => {
|
|
430
|
+
if (!route) return;
|
|
431
|
+
NavSpeedAlert.start(route.polyline1e6);
|
|
432
|
+
const stopGps = gps.subscribe((fix) => NavSpeedAlert.onLocation(fix));
|
|
433
|
+
const subs = [
|
|
434
|
+
NavSpeedAlert.addResultListener((e) => {
|
|
435
|
+
if (!e.success) console.warn('alert fetch', e.errorCode, e.errorMessage);
|
|
436
|
+
}),
|
|
437
|
+
NavSpeedAlert.addRerouteListener(({ lat, lng }) => navigation.rerouteFrom(lat, lng)),
|
|
438
|
+
];
|
|
439
|
+
return () => {
|
|
440
|
+
subs.forEach((s) => s.remove());
|
|
441
|
+
stopGps();
|
|
442
|
+
NavSpeedAlert.reset();
|
|
443
|
+
};
|
|
444
|
+
}, [route, gps]);
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
// 3. Overlay: mount once on the navigation screen.
|
|
448
|
+
export function SpeedAlertOverlay() {
|
|
449
|
+
const { signs, restriction } = useNavSpeedAlertSigns();
|
|
450
|
+
if (!signs) return null;
|
|
451
|
+
return (
|
|
452
|
+
<View style={S.row}>
|
|
453
|
+
<Slot sign={signs.current} tint={signs.speedStatus} />
|
|
454
|
+
<Slot sign={signs.next} dist={signs.nextDistMeters} />
|
|
455
|
+
<Slot sign={signs.camera} dist={signs.cameraDistMeters} />
|
|
456
|
+
<Slot sign={signs.toll} dist={signs.tollDistMeters} />
|
|
457
|
+
<Slot sign={restriction?.stop} dist={restriction?.stopDistMeters} />
|
|
458
|
+
<Slot sign={restriction?.closed} dist={restriction?.closedDistMeters} />
|
|
459
|
+
<Slot sign={restriction?.vehicle} dist={restriction?.vehicleDistMeters} />
|
|
460
|
+
<Slot sign={restriction?.bua} dist={restriction?.buaDistMeters} />
|
|
461
|
+
<Slot sign={restriction?.turn} dist={restriction?.turnDistMeters} />
|
|
462
|
+
</View>
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
function Slot({ sign, dist, tint }: { sign?: NavSpeedAlert.AlertSignRef | null; dist?: number; tint?: number }) {
|
|
467
|
+
if (!sign) return null;
|
|
468
|
+
const border = tint === 2 ? '#F44336' : tint === 1 ? '#FF9800' : 'transparent';
|
|
469
|
+
return (
|
|
470
|
+
<View style={S.slot}>
|
|
471
|
+
<Image source={sign} style={[S.sign, { borderColor: border }]} />
|
|
472
|
+
{dist !== undefined && dist > 0 ? <Text style={S.dist}>{dist} m</Text> : null}
|
|
473
|
+
</View>
|
|
474
|
+
);
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
const S = StyleSheet.create({
|
|
478
|
+
row: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
|
|
479
|
+
slot: { alignItems: 'center' },
|
|
480
|
+
sign: { width: 72, height: 72, borderWidth: 3, borderRadius: 36 },
|
|
481
|
+
dist: { fontSize: 12 },
|
|
482
|
+
});
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
## Contact
|
|
486
|
+
|
|
487
|
+
This SDK is available to [Vietmap MAPs API](https://maps.vietmap.vn/docs/vi/) enterprise customers. For credentials,
|
|
488
|
+
application-id registration or integration support, contact on [Zalo OA](https://zalo.me/3189066936017422854).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
plugins {
|
|
2
|
+
id 'com.android.library'
|
|
3
|
+
id 'expo-module-gradle-plugin'
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
group = 'expo.modules.navspeedalert'
|
|
7
|
+
version = '1.0.0'
|
|
8
|
+
|
|
9
|
+
// Native Alert View SDK binary is consumed from JitPack. Hosts that lock
|
|
10
|
+
// repositories with RepositoriesMode.FAIL_ON_PROJECT_REPOS must add jitpack
|
|
11
|
+
// to their own settings.gradle (see README).
|
|
12
|
+
repositories {
|
|
13
|
+
maven { url 'https://jitpack.io' }
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
android {
|
|
17
|
+
namespace "expo.modules.navspeedalert"
|
|
18
|
+
defaultConfig {
|
|
19
|
+
versionCode 1
|
|
20
|
+
versionName "1.0.0"
|
|
21
|
+
}
|
|
22
|
+
lintOptions {
|
|
23
|
+
abortOnError false
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
dependencies {
|
|
28
|
+
// Pinned to the native SDK release this wrapper was verified against.
|
|
29
|
+
implementation 'com.github.mapzone-global:mapzone-alert-view-android:1.0.1'
|
|
30
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
package expo.modules.navspeedalert
|
|
2
|
+
|
|
3
|
+
import android.graphics.Bitmap
|
|
4
|
+
import android.util.Base64
|
|
5
|
+
import expo.modules.kotlin.runtime.Runtime
|
|
6
|
+
import expo.modules.kotlin.sharedobjects.SharedRef
|
|
7
|
+
import java.io.ByteArrayOutputStream
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Hands a sign Bitmap to JS without copying pixels. `nativeRefType = "image"`
|
|
11
|
+
* is what lets `expo-image` accept the ref directly as `source`.
|
|
12
|
+
*
|
|
13
|
+
* The Bitmap is deliberately NOT recycled on release: expo-image may still be
|
|
14
|
+
* drawing it. Dropping the reference is enough for the Java GC to reclaim it.
|
|
15
|
+
*/
|
|
16
|
+
class AlertSignRef(bitmap: Bitmap, runtime: Runtime) : SharedRef<Bitmap>(bitmap, runtime) {
|
|
17
|
+
override val nativeRefType: String = "image"
|
|
18
|
+
|
|
19
|
+
/** PNG bytes as base64 for hosts that do not use `expo-image`. */
|
|
20
|
+
fun toPngBase64(): String {
|
|
21
|
+
val out = ByteArrayOutputStream()
|
|
22
|
+
ref.compress(Bitmap.CompressFormat.PNG, 100, out)
|
|
23
|
+
return Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP)
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
package expo.modules.navspeedalert
|
|
2
|
+
|
|
3
|
+
import expo.modules.kotlin.records.Field
|
|
4
|
+
import expo.modules.kotlin.records.Record
|
|
5
|
+
import expo.modules.kotlin.records.Required
|
|
6
|
+
|
|
7
|
+
/** Mirrors `ConfigureOptions` in `src/NavSpeedAlert.types.ts`. */
|
|
8
|
+
class ConfigureRecord : Record {
|
|
9
|
+
@Field @Required val baseUrl: String = ""
|
|
10
|
+
@Field @Required val apiKeyId: String = ""
|
|
11
|
+
@Field @Required val apiKey: String = ""
|
|
12
|
+
@Field @Required val vehicleId: String = ""
|
|
13
|
+
@Field @Required val vehicleType: Int = 0
|
|
14
|
+
@Field @Required val seats: Int = 0
|
|
15
|
+
@Field @Required val weights: Double = 0.0
|
|
16
|
+
@Field @Required val maxSnapMeters: Double = 0.0
|
|
17
|
+
}
|