Headless navigation
Contents
This guide describes how to integrate the Trimble Maps Navigation SDK on iOS in headless mode: full navigation engine capabilities without presenting NavigationViewController or embedding NavigationMapView. You import the published Swift modules (XCFrameworks), wire TrimbleMapsNavigationService, and build your own UI.
SDK modules (where types live)
| Module | Typical responsibilities in headless flows |
|---|---|
| TrimbleMapsCoreNavigation | NavigationService, TrimbleMapsNavigationService, TrimbleMapsTrip, TripStop, NavigationServiceDelegate, NavigationSettings, RouteProgress, SimulationMode, route session lifecycle
|
| TrimbleMapsWebservicesClient | Route, RouteOptions, RouteResponse, SpokenInstruction, VisualInstructionBanner, VisualInstruction, Waypoint, directions types
|
| TrimbleMapsNavigation | NavigationViewController, NavigationMapView, RouteVoiceController (standard UI path); optional helpers that also apply when mixing UI and services
|
| TrimbleMapsAccounts | AccountManager and account / licensing initialization
|
| TrimbleMapsNavigationNative | NavigationNative (native bridge; optional tuning such as GPS timer APIs)
|
| TrimbleMaps | Maps / GL stack when your product links the full mobile SDK (often present alongside navigation binaries) |
| CoreLocation (Apple) | CLLocation, CLLocationCoordinate2D for origins and fixes
|
| AVFAudio (Apple) | AVSpeechSynthesizer or other system TTS for spoken guidance
|
Link the binaries your distribution provides (for example Carthage-built .xcframework artifacts), then import the modules above as needed.
Contents
- What is headless navigation?
- Key difference from standard navigation
- When to use headless navigation
- Requirements
- SDK dependencies and permissions
- Core components
- Setup and initialization
- NavigationServiceDelegate callbacks
- Simulated navigation
- API reference (summary)
- Limitations
- Best practices
- Troubleshooting
- Related links
What is headless navigation?
Headless navigation means driving NavigationService (concrete type TrimbleMapsNavigationService, TrimbleMapsCoreNavigation) directly while you own all UI (SwiftUI, UIKit, widgets, CarPlay-only flows, or no UI). The SDK still provides:
- Route calculation and active guidance
- Turn-by-turn timing for visual and spoken instructions
- Voice guidance triggers (you supply TTS playback)
- Road-snapped vs raw location updates
- Off-route detection and reroute flows
- Arrival at waypoints and destination
Key difference from standard navigation
| Feature | Standard navigation | Headless navigation |
|---|---|---|
| UI components | Pre-built NavigationViewController (TrimbleMapsNavigation)
| Custom (SwiftUI, UIKit, etc.) |
| Map display | Integrated via NavigationMapView (TrimbleMapsNavigation)
| Optional / your own map or none |
| Voice playback | Often RouteVoiceController (TrimbleMapsNavigation) with full UI
| AVFAudio / custom TTS using SpokenInstruction (TrimbleMapsWebservicesClient)
|
| Turn cards / banners | Built-in views | Build UI from VisualInstructionBanner (TrimbleMapsWebservicesClient) in delegate callbacks
|
| Flexibility | Faster path for standard turn-by-turn | Full control over layout and behavior |
When to use headless navigation
Use headless navigation when
- You need a fully custom navigation UI that does not match the stock navigation chrome.
- You target embedded or fleet devices with bespoke displays.
- Voice-first or minimal UI: instructions surfaced outside a full-screen map.
- You run navigation alongside another primary experience (AR, gaming metaphor, minimal HUD).
- You integrate into an existing app with established navigation UX patterns.
Prefer standard NavigationViewController when
- Time-to-market matters more than pixel-level customization.
- Default turn-by-turn UI, route preview, and map camera behavior are acceptable.
- You want bundled voice and banner behavior with minimal glue code.
Requirements
- iOS: Use the minimum deployment target specified for your Navigation SDK release.
- Xcode: A version compatible with your SDK binaries.
- Auth / license: Initialize
AccountManager(TrimbleMapsAccounts) and satisfy navigation licensing before routing. - Frameworks: At minimum TrimbleMapsCoreNavigation, TrimbleMapsWebservicesClient, and TrimbleMapsNavigationNative; TrimbleMapsNavigation is required when linking the standard navigation umbrella; add TrimbleMaps, TrimbleMapsMobileEvents, and third-party dependencies per your distribution’s integration list.
SDK dependencies and permissions
Carthage Cartfile
Use binary JSON artifacts from your Trimble Maps SDK distribution (URLs and version pins come from release documentation—do not invent endpoints). A typical navigation stack—including headless use—declares the core binaries plus shared dependencies:
# Replace each `binary "…"` URL and version with the values from your SDK release / Carthage manifest.
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsAccounts.json" == <ACCOUNTS_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsMobileEvents.json" == <EVENTS_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMaps.json" == <MAPS_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsWebservicesClient.json" == <WEBSERVICES_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/Turf.json" == <TURF_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsCoreNavigation.json" == <CORE_NAV_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsNavigation.json" == <NAV_UI_VERSION>
binary "https://<TRIMBLE_CARTHAGE_BASE>/TrimbleMapsNavigationNative.json" == <NAV_NATIVE_VERSION>
github "ceeK/Solar" ~> 3.0
github "raphaelmor/Polyline" ~> 5.1
Headless-focused notes:
TrimbleMapsCoreNavigationandTrimbleMapsWebservicesClientcarryTrimbleMapsNavigationService,TrimbleMapsTrip, and directions types.TrimbleMapsNavigationNativeis required for the native navigation engine backingTrimbleMapsNavigationService.TrimbleMapsNavigationremains the module that shipsNavigationViewController/NavigationMapView; link it when your app or transitive SDK layers expect that framework, even if you never present those view controllers.TrimbleMaps,TrimbleMapsAccounts,TrimbleMapsMobileEvents, Turf, Solar, and Polyline are part of the usual binary set from Trimble’s Carthage feed—trim only if your distribution explicitly documents a smaller footprint.
Optional binaries (search, route rendering UI plugins, routing profile UI, multiplatform UI) are not required for headless turn-by-turn; add them only when you use those features.
After editing the Cartfile, run carthage bootstrap (or carthage update) with the flags your team standardizes on for XCFrameworks, then embed the built .xcframework products in the app target and set Frameworks, Libraries, and Embedded Content accordingly.
Xcode target integration
Import the modules from the SDK modules table, link the XCFrameworks from Carthage/Build (or your package manager output), and construct a TrimbleMapsNavigationService for each navigation session. There is no shared singleton navigation instance—create and retain a service when you start a session.
Required Info.plist usage descriptions
Declare location usage keys appropriate to your app:
NSLocationWhenInUseUsageDescriptionNSLocationTemporaryUsageDescriptionDictionarywhen prompting for temporary precise location; includeTMGLAccuracyAuthorizationDescriptionwhen using APIs that reference that key (TrimbleMaps)
For background navigation, add NSLocationAlwaysAndWhenInUseUsageDescription and enable Background Modes as required. Follow Apple’s location privacy guidelines.
Core components
TrimbleMapsNavigationService (TrimbleMapsCoreNavigation)
Concrete implementation of NavigationService. Create it after you have a Route and RouteOptions (TrimbleMapsWebservicesClient) and a route index from directions.
import TrimbleMapsCoreNavigation
let service = TrimbleMapsNavigationService(
route: route,
routeIndex: 0,
routeOptions: routeOptions,
simulating: .never // or .always / .onPoorGPS — see Simulated navigation
)
Retain the service for the lifetime of the session. Call start() when you are ready to navigate; call stop() or endNavigation(feedback:) when finished. Create a new instance for each new session.
TrimbleMapsTrip (TrimbleMapsCoreNavigation)
Holds origin, stops, routing options, and optional attachment to the active NavigationService. Use it to request routes and to participate in delegate chaining.
import TrimbleMapsCoreNavigation
let trip = TrimbleMapsTrip()
trip.origin = CLLocation(latitude: lat, longitude: lon)
trip.addStop(/* TripStop */)
trip.fetchFullRoute { _, result in
// Handle RouteResponse (TrimbleMapsWebservicesClient), then build TrimbleMapsNavigationService
}
Configuring for headless use
Do not present NavigationViewController (TrimbleMapsNavigation). Construct TrimbleMapsNavigationService, assign a NavigationServiceDelegate, and call start(). Updates arrive through that delegate.
Distance / units (TrimbleMapsCoreNavigation)
Use NavigationSettings.shared.distanceUnit together with RouteOptions.locale (TrimbleMapsWebservicesClient).
TripStop (TrimbleMapsCoreNavigation)
Describes waypoints on a trip.
var stop = TripStop(
coordinate: CLLocationCoordinate2D(latitude: destLat, longitude: destLon),
isPOI: false
)
stop.placeName = "Destination"
trip.addStop(stop)
Setup and initialization
Step 1 — Configure the trip
- Set
trip.origintoCLLocation(CoreLocation). - Add
TripStopvalues for intermediate stops and destination. - Optionally set
trip.routingProfile, locale, and other trip fields onTrimbleMapsTrip.
Step 2 — Fetch the route
trip.fetchFullRoute { _, result in
switch result {
case .success(let response):
guard let route = response.routes?.first,
case let .route(routeOptions) = response.options else {
// handle empty routes
return
}
// proceed to Step 3
case .failure(let error):
// handle error
break
}
}
fetchFullRoute starts from the planned origin. For remaining legs only (user already en route), use fetchRemainingRoute on TrimbleMapsTrip per API requirements.
Step 3 — Create TrimbleMapsNavigationService
let service = TrimbleMapsNavigationService(
route: route,
routeIndex: 0,
routeOptions: routeOptions,
simulating: .always,
enableMapDownload: false,
downloadOnboardMapDataOnCellular: false
)
service.simulationSpeedMultiplier = 2.0
NavigationSettings.shared.distanceUnit = routeOptions.locale.usesMetricSystem ? .kilometer : .mile
trip.navigation = service
service.delegate = myDelegate // NSObject + NavigationServiceDelegate
trip.status = .InProgress
Chained delegate: With trip.navigation set and service.delegate assigned, TrimbleMapsNavigationService can forward events to both your delegate and TrimbleMapsTrip. See the delegate property documentation on TrimbleMapsNavigationService.
Step 4 — Start navigation
service.start()
NavigationServiceDelegate callbacks
Implement NavigationServiceDelegate (TrimbleMapsCoreNavigation) on a type (usually an NSObject subclass) and set service.delegate. Default implementations exist for many methods—override what you need.
Route progress
| Kind of update | Delegate method |
|---|---|
| Distance, ETA, leg/step progress, snapped and raw locations | navigationService(_:didUpdate:with:rawLocation:)
|
Use RouteProgress (TrimbleMapsCoreNavigation) for distanceRemaining, durationRemaining, and leg/step state.
func navigationService(
_ service: NavigationService,
didUpdate progress: RouteProgress,
with location: CLLocation,
rawLocation: CLLocation
) {
let meters = progress.distanceRemaining
let seconds = progress.durationRemaining
// Update UI (prefer main queue for UIKit/SwiftUI)
}
Voice instruction triggers
| Kind of update | Delegate method |
|---|---|
| Spoken instruction point along the route | navigationService(_:didPassSpokenInstructionPoint:routeProgress:)
|
Use SpokenInstruction.text and ssmlText (TrimbleMapsWebservicesClient) with AVSpeechSynthesizer or another TTS engine.
Banner / visual instructions
| Kind of update | Delegate method |
|---|---|
| Visual banner instruction point | navigationService(_:didPassVisualInstructionPoint:routeProgress:)
|
Use VisualInstructionBanner, VisualInstruction (TrimbleMapsWebservicesClient)—e.g. primaryInstruction, secondaryInstruction—for turn-card UI.
Off route / reroute
| Kind of update | Delegate methods (examples) |
|---|---|
| Reroute lifecycle and policy | willRerouteFrom, didRerouteAlong, didFailToRerouteWith, shouldRerouteFrom, and related (TrimbleMapsCoreNavigation)
|
Location (enhanced vs raw)
Delivered in navigationService(_:didUpdate:with:rawLocation:): location is road-aligned, rawLocation is the raw fix (CoreLocation).
Arrival
| Kind of update | Delegate method |
|---|---|
| Arrival at a waypoint | navigationService(_:didArriveAt:) — return Bool to control automatic leg advancement (see protocol docs). Waypoint type: Waypoint (TrimbleMapsWebservicesClient).
|
Simulated navigation
Use TrimbleMapsNavigationService with SimulationMode (TrimbleMapsCoreNavigation):
simulating: .always— internalSimulatedLocationManagerdrives the route without live GPS.simulationSpeedMultiplier— e.g.2.0for double speed.
let service = TrimbleMapsNavigationService(
route: route,
routeIndex: 0,
routeOptions: routeOptions,
simulating: .always
)
service.simulationSpeedMultiplier = 2.0
Simulation speed reference
| Multiplier | Typical use |
|---|---|
1.0
| Real-time |
2.0
| Faster integration testing |
5.0 / higher
| Quick regression passes |
With .always, fixes follow the route geometry; off-route callbacks are uncommon unless the route or injected locations change.
Optional: NavigationNative.shared.setLiveGpsUpdateTimerSeconds (TrimbleMapsNavigationNative) for specific simulation timing tweaks—use only when your integration requires it.
API reference (summary)
NavigationService / TrimbleMapsNavigationService (TrimbleMapsCoreNavigation)
| Method / property | Purpose |
|---|---|
start()
| Begin navigation along the route |
stop()
| Pause routing / location updates |
endNavigation(feedback:)
| End session and telemetry |
delegate
| NavigationServiceDelegate callbacks
|
simulationMode, simulationSpeedMultiplier
| Simulation control |
indexedRoute, route, router
| Active route and progress |
TrimbleMapsTrip (TrimbleMapsCoreNavigation)
| Method / property | Purpose |
|---|---|
origin, stops, addStop
| Trip definition |
fetchFullRoute, fetchRemainingRoute
| Directions requests |
navigation
| Active NavigationService
|
status
| Trip lifecycle (e.g. .InProgress)
|
Limitations
Headless mode does not automatically include:
- Map camera, puck, or route line—implement if you show a map (TrimbleMaps / your map stack).
- Built-in speech—wire
SpokenInstructionor adoptRouteVoiceController(TrimbleMapsNavigation) explicitly if you want packaged voice behavior. - Onboard corridor download UI—use
TrimbleMapsNavigationServiceinitializer flagsenableMapDownloadanddownloadOnboardMapDataOnCellular(TrimbleMapsCoreNavigation) when offline corridor data is required.
Rerouting depends on router settings and NavigationServiceDelegate responses such as shouldRerouteFrom.
Best practices
Lifecycle
- Call
endNavigation(feedback: nil)orstop()when the session ends. - Set
trip.navigation = niland releaseTrimbleMapsNavigationService.
Threading
- Marshal UI work to the main queue; delegate delivery may not always be main-thread bound.
Errors
- Validate
RouteResponse(TrimbleMapsWebservicesClient) for empty routes, missing options, and request failures.
Testing
- Prefer
simulating: .alwaysandsimulationSpeedMultiplierfor repeatable tests without driving.
Troubleshooting
| Symptom | Things to check |
|---|---|
| Navigation never updates | start() called? Route fetch succeeded? trip.status set appropriately? delegate assigned before start()?
|
| No voice / banner text | RouteOptions.includesSpokenInstructions / includesVisualInstructions (TrimbleMapsWebservicesClient); TrimbleMapsTrip sets common defaults when building options.
|
| No distance formatting | NavigationSettings.shared.distanceUnit vs RouteOptions.locale
|
| Memory growth after closing | stop() / endNavigation, clear trip.navigation, release the service strongly held references
|
| Carthage / link errors | Verify every binary in your distribution’s manifest is pinned; TrimbleMapsNavigationNative must match the TrimbleMapsCoreNavigation / TrimbleMapsNavigation versions your release notes prescribe
|
Related links
- Trimble developer documentation (CoPilot Native Nav SDK hub): developer.trimblemaps.com — CoPilot Native Nav SDK
- Apple
AVSpeechSynthesizer: AVFAudio documentation