Skip to main content

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?

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:

  • TrimbleMapsCoreNavigation and TrimbleMapsWebservicesClient carry TrimbleMapsNavigationService, TrimbleMapsTrip, and directions types.
  • TrimbleMapsNavigationNative is required for the native navigation engine backing TrimbleMapsNavigationService.
  • TrimbleMapsNavigation remains the module that ships NavigationViewController / 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:

  • NSLocationWhenInUseUsageDescription
  • NSLocationTemporaryUsageDescriptionDictionary when prompting for temporary precise location; include TMGLAccuracyAuthorizationDescription when 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.origin to CLLocation (CoreLocation).
  • Add TripStop values for intermediate stops and destination.
  • Optionally set trip.routingProfile, locale, and other trip fields on TrimbleMapsTrip.

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()

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.

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 — internal SimulatedLocationManager drives the route without live GPS.
  • simulationSpeedMultiplier — e.g. 2.0 for 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)

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 SpokenInstruction or adopt RouteVoiceController (TrimbleMapsNavigation) explicitly if you want packaged voice behavior.
  • Onboard corridor download UI—use TrimbleMapsNavigationService initializer flags enableMapDownload and downloadOnboardMapDataOnCellular (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) or stop() when the session ends.
  • Set trip.navigation = nil and release TrimbleMapsNavigationService.

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: .always and simulationSpeedMultiplier for 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
Last updated November 10, 2026.