io.truemetrics:navigation) is the screen of the
truemetrics standalone navigation app as an Android library: the map, the last
meter, the routing and the best practices, inside your own app. One stop at a time.
Point-to-point navigation can be off or on, with one switch, routing:
Without last-meter data for a stop, the map falls back to the destination and highlights the
building at it.
Requirements
- Android app in Kotlin or Java,
minSdk23 or higher,compileSdk37, Kotlin 2.3 or newer (the library bringskotlin-stdlib2.4). - The screen that shows the module is a
FragmentActivity(anAppCompatActivityis one). - An API key from truemetrics, enabled for the module.
- Last-meter data: the truemetrics SDK recording in your courier app with
address_idin the metadata (see Integrate with an AI agent).
Flutter or React Native apps: show the module from a small native Android part
(
NavigationContract, see step 4), or use the standalone app,
which needs no native code at all.Integration
1
1. Add the dependency
The repository URL and the current version come from your truemetrics contact.The library’s manifest merges into your app:
settings.gradle.kts
app/build.gradle.kts
INTERNET, ACCESS_NETWORK_STATE,
ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION, FOREGROUND_SERVICE,
FOREGROUND_SERVICE_LOCATION, POST_NOTIFICATIONS, its activity and its foreground service.
Remove none of them.2
2. Initialise once
In
Application.onCreate, on the main thread. After Android killed the process it brings an open
navigation back directly, and only Application.onCreate runs before it.MyApp.kt
3
3. Describe the stop
One
NavigationRequest per stop. Only destination is required; the IDs bring the last meter.4
4. Show it
Pick one of three ways.
- Inside your layout
- Compose
- A screen of its own
The fragment in a container of your own screen, between your own bar and buttons.
R.id.navigation_container is a FrameLayout or FragmentContainerView of at least about
400 dp height. The full example below shows the rest.5
5. Hear the end
The navigation ends on arrival (
NavigationResult.Arrived), or with Back, ✕ or the system Back
(NavigationResult.Ended). Take the fragment away then.Either implement TruemetricsNavigationFragment.Host on the activity (or the parent fragment):
it hears the end at once, also while your screen is out of sight, for example with the phone
locked. Or listen for the fragment result, delivered when your screen is started:6
6. Declare the screen
The activity that holds the module keeps the map through dark-mode switches and rotation:
AndroidManifest.xml
Full example
A stop screen of a courier app: its own bar and “Delivered” button, the module in between. This is how truemetrics’ own test app embeds it.StopActivity.kt
Parameters
TruemetricsNavigation.init
The truemetrics API key: last meter, routing, configuration. Keep it in your build config or
secrets, never in source. Call
init again to switch the key; screens opened afterwards use the
new one.NavigationRequest
The stop in WGS84 degrees, latitude first: the coordinate you hand to Google Maps today. Used for
routing and the map when there is no last meter for the stop. An invalid position throws.
The stop’s
address_id, as sent in the metadata: typically your address identifier or route point
identifier. It tells the module where to guide the courier and which last meter to show. Without
it the map shows the destination only.Optional, usually left out. Only if your system uses a second identifier for the stop (for
example a separate parking or route point next to the address), and only if truemetrics asked
for it.
Point-to-point navigation.
false: the last meter and the courier’s position, no route. true: route to the
waypoint (else the parking, else the destination), turn-by-turn guidance, rerouting, arrival.The card’s first line: street and number, or a place name. One line, a longer one is cut with ”…”.
The card’s second line, shown only with
address: a line of your choice, for example
“Planned Arrival 14:22”, or postcode and city. One line, a longer one is cut with ”…”.The card at the bottom (address, time left, arrival time, one button) and the ✕. Set
false when
your own screen shows the stop and the way out around the map; with routing the drive then starts
by itself after the route overview.The text of the card’s Back button.
null for none; an ✕ ends the navigation then.Whether the navigation ends by itself a few seconds after arrival (
NavigationResult.Arrived), or
stays on the map until the courier leaves. Left out: it ends when there is a Back button and the
configuration for your key allows it. Without the card, pass true.Results
Good to know
- One module per activity. For the next stop, remove the old fragment with
commitNow()first, then add the new one. Areplacebuilds the new map while the old one still lives. - Permissions. The module asks for location itself, and for notifications at the first drive (Android 13+). Without location it says so on the map and offers the fix.
- Back. The system Back ends the navigation (you hear it as the result); after that, Back is yours again.
- Theme. The map puts its own theme on the activity while it is created; the module puts your manifest theme back right away. If you set your theme in code, set it again after adding the fragment.
- Approximate location. With approximate location only, the courier’s dot is not shown and an arrival cannot be noticed; the module says so.
- Configuration from truemetrics. Reroute limits, arrival behaviour and similar settings come per API key from truemetrics. A drive keeps the configuration it started with.
- Battery. The map draws only when something changes, the screen stays on only while navigating, and the foreground service runs only during a drive on the device’s position.
- Your own MapLibre. If your app uses MapLibre itself, tell your truemetrics contact: the
module sets MapLibre’s process-wide settings at the first
init.
Let an AI agent do it
Integrate the module with an AI agent: a copy-paste prompt that analyses your app, asks you to confirm each step, and implements the integration above.For testing and demos
Leave these out in production. With them a drive runs by itself, so a stop can be shown at a desk or in a customer meeting without driving there.NavigationRequest, with routing = true: drive along the route by itself instead of following
the device location, with arrival as in a real drive. No rerouting.NavigationRequest: where the simulated drive starts. Left out, at the device location. A few
hundred metres before the stop, on the road leading in, shows the approach and the last meter in
a minute.TruemetricsNavigation.init: whether a drive from the module’s own address search is simulated
until the courier flips the switch. Not used for requests from your app.