# Task: Hand stops over to the truemetrics standalone navigation app
You are changing this courier/driver app so that it hands a delivery stop to the truemetrics standalone navigation app (Android package `io.truemetrics.navigation`) instead of Google Maps or Waze. The truemetrics app takes the same `google.navigation:` link Google Maps takes, drives the courier to the waypoint on the street and into the parking, shows the walk path to the entrance that truemetrics learned from the couriers' deliveries, and switches back to this app on arrival. The app only needs to: add a few optional fields to the link it already sends, target the truemetrics app, fall back to Google Maps when it is not installed, and make the way back land well.
Work in this order:
1. Analyze the codebase: language and framework, every place where navigation to a stop is started (`google.navigation:`, `geo:`, `https://maps.google.com`, `https://www.google.com/maps/dir`, `waze://`, `https://waze.com/ul` links, map SDK calls), the stop/tour data models (coordinates, street, postcode, city, address IDs, tour order), the truemetrics SDK metadata code (which value is sent as `address_id`), and the launcher activity with its `launchMode` and deep links.
2. For EACH integration point below, propose the exact file, function and line, explain why, and ASK ME TO CONFIRM before writing code. Ask all questions in one batch where possible.
3. Implement only what I confirmed. Keep changes minimal and isolated (ideally one helper, e.g. `TruemetricsHandover`, called from the existing navigation call sites).
4. Use the handover reference at the end of this prompt.
## 0. Platform
- Android only. In cross-platform apps (Flutter, React Native, Expo), keep the current behavior on iOS and guard the new code with a platform check.
- Native Android (Kotlin/Java): build an `Intent` with extras.
- Flutter / React Native / web views without native code: open a URL; every field can be a query parameter of the link (URL-encoded). Use the `truemetrics.navigation://navigate?q=<lat>,<lng>&...` scheme, which opens only the truemetrics app, and fall back to the current Google Maps link if it cannot be opened.
Confirm with me: the detected framework and all call sites found.
## 1. The handover
At each confirmed call site, keep the current link and add:
- The target: `setPackage("io.truemetrics.navigation")` (native), so no chooser and no Google Maps opens.
- `route`: the tour as JSON (see the reference) with the stop to drive to as `next_stop`. Per stop `ID` = the stop's `address_id`, exactly as sent to truemetrics in the SDK metadata, plus `line1` (street and number) and `line2` (a second line, e.g. "Planned Arrival 14:22" if the app has a planned time, else postcode and city; ask me). `ID_sec` only as described under the IDs below.
- The way back: `returnApp` (this app's package name) or `returnUri` (see section 2).
- `q` must be `<lat>,<lng>` in WGS84 degrees. If the current call sends an address string instead of coordinates, tell me: the truemetrics app does not geocode. Propose where the coordinates come from.
IMPORTANT, the IDs: they tell the truemetrics app where to guide the courier and which last meter to show (parking, entrance, walk path). They are typically the app's address identifier or route point identifier, the same value the app sends as `address_id` in the truemetrics SDK metadata. Look them up in the metadata code; do not guess. Without them the courier is navigated to `q` without the last meter.
Examples of what to look for:
- A field such as `addressId`, `deliveryPointId`, `servicePointId`, `locationId` or `routePointId` on the stop model, passed to the SDK as `address_id`.
- The stop in `route` then carries it as `"ID": "<address_id>"`.
- Only if the app uses a second identifier for the stop (e.g. a separate parking or route point next to the address), `"ID_sec"` can carry it. Leave it out by default and ask me before using it.
- Not an ID: a parcel or shipment number, a tour or route number, the stop's position in the tour, a database row ID that changes with every tour.
Fallback: start the intent in a try/catch; on `ActivityNotFoundException` start it again without the package (Google Maps as before, it ignores the extra fields). Do not add a `<queries>` element only for this.
Do not send `simulate` or `simulationStart` (demo only) unless I ask for it.
Confirm with me: the field mapping from this app's stop and tour models, and the call sites to change.
## 2. The way back
The truemetrics app switches back on arrival (after a 10 s countdown on its Back button) and when the courier taps Back or uses the system Back.
- `returnApp` = this app's package: brings the app to the front as a tap on its icon does. Check that the launcher activity's `launchMode` (`singleTask` or `singleTop`) and task setup bring the courier back to the screen they left, not a fresh start. Propose a change if not, and ask me.
- `returnUri` = a deep link of this app (browsable `VIEW` intent filter), e.g. to the stop's delivery screen. Use it if the app has, or should get, such a link. `file:`, `content:`, `intent:` and `android-app:` links are ignored.
- Neither: no Back button, no switch on arrival; the courier comes back on their own, as from Google Maps.
Confirm with me: `returnApp` or `returnUri`, and where the courier should land.
## 3. Optional: offer the choice
If the app has settings for the navigation app (e.g. Google Maps vs Waze), propose adding "truemetrics" there instead of switching all couriers at once. Ask me.
## Handover reference
Links: the same as for Google Maps (`google.navigation:q=<lat>,<lng>&mode=d`, the fields below as intent extras), or the truemetrics scheme with every field a query parameter. A full example:
truemetrics.navigation://navigate?q=55.654436,12.361784&returnApp=com.example.scanner&route=%7B%22stops%22%3A%5B%7B%22ID%22%3A%22%3Caddress_id%3E%22%2C%22line1%22%3A%22Gymnasievej%2039%22%2C%22line2%22%3A%22Planned%20Arrival%2014%3A22%22%7D%2C%7B%22ID%22%3A%22%3Caddress_id%3E%22%2C%22line1%22%3A%22%C3%98sterbyvejen%2033%22%2C%22line2%22%3A%22Planned%20Arrival%2014%3A41%22%7D%5D%2C%22next_stop%22%3A1%7D
`q` is `<lat>,<lng>`, optionally followed by `(label)`. Every field below except `q` can be an intent extra or a URL-encoded query parameter; an extra wins over a parameter of the same name. Extras are strings, except `simulate` (boolean, or the string "true"/"false").
| Field | Meaning |
| --- | --- |
| `route` (required) | JSON: the tour and the stop to drive to, see below |
| `returnUri` | Browsable deep link opened to switch back |
| `returnApp` | Package to switch back to, if there is no `returnUri` |
| `simulate` (boolean), `simulationStart` ("lat,lng") | Demo only: a simulated drive |
`route`, up to 200 stops:
{
"stops": [
{ "ID": "<address_id>", "line1": "Gymnasievej 39", "line2": "Planned Arrival 14:22" },
{ "ID": "<address_id>", "line1": "Østerbyvejen 33", "line2": "Planned Arrival 14:41" }
],
"next_stop": 1
}
| Field | Meaning |
| --- | --- |
| `next_stop` | Index in `stops` of the stop to drive to, counted from 0 |
| `ID` | The stop's `address_id` of the metadata, string or number |
| `ID_sec` | Optional, left out by default: a second identifier of the stop, if the app has one |
| `line1`, `line2` | Optional: the card's two lines, e.g. street and number, and "Planned Arrival 14:22" or postcode and city; `line2` shows only with `line1`, without `line1` the card shows the `(label)` from `q` |
The stop at `next_stop` is the one the courier is navigated to; send the whole tour all the same, the other stops are used as well. A `route` that cannot be read, a `next_stop` outside the list or a stop with none of these fields counts as no `route`.
Native Android example:
val intent = Intent(Intent.ACTION_VIEW, Uri.parse("google.navigation:q=${stop.lat},${stop.lon}&mode=d"))
.setPackage("io.truemetrics.navigation")
.putExtra("route", routeJson(tour, nextStop = index))
.putExtra("returnApp", packageName)
try {
startActivity(intent)
} catch (e: ActivityNotFoundException) {
startActivity(intent.setPackage(null))
}
Behavior to know:
- One handover runs at a time: a new one replaces the one before, also for the same stop.
- Route overview first; its Navigate button presses itself after 10 s.
- Arrival: within 30 m of the parking or entrance and slower than 15 km/h for 20 s.
- The drive goes on with the phone locked or this app in front (foreground service with a notification).
## Done when
- Every confirmed call site hands over to `io.truemetrics.navigation`, with `route` (the IDs from the SDK metadata, `line1`/`line2`) and the way back, and falls back to Google Maps when the app is not installed.
- iOS (in cross-platform apps) unchanged.
- The way back lands on the screen I confirmed.
- Give me a short summary of every file changed and a test plan: on a real Android device with the truemetrics app installed and without it, a stop with known last-meter data and one without, Back during the drive, arrival with the automatic switch back, and the next stop after it. For a quick check from a computer: `adb shell am start -a android.intent.action.VIEW -d "google.navigation:q=<lat>,<lng>&mode=d" -n io.truemetrics.navigation/.ui.navigation.HandoverActivity --es returnApp <this app's package>`.