Skip to main content
The truemetrics last meter module (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, minSdk 23 or higher, compileSdk 37, Kotlin 2.3 or newer (the library brings kotlin-stdlib 2.4).
  • The screen that shows the module is a FragmentActivity (an AppCompatActivity is one).
  • An API key from truemetrics, enabled for the module.
  • Last-meter data: the truemetrics SDK recording in your courier app with address_id in 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.
settings.gradle.kts
app/build.gradle.kts
The library’s manifest merges into your app: 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.
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

Context
required
Your application context.
String
required
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.
LatLon
required
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.
String
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.
String
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.
Boolean
default:"false"
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.
String
The card’s first line: street and number, or a place name. One line, a longer one is cut with ”…”.
String
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 ”…”.
Boolean
default:"true"
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.
String
default:"\"Back\""
The text of the card’s Back button. null for none; an ✕ ends the navigation then.
Boolean
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. A replace builds 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.
Boolean
default:"false"
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.
LatLon
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.
Boolean
default:"false"
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.