Class TrimbleMapsNavigation
-
- All Implemented Interfaces:
@UiThread() public final class TrimbleMapsNavigation
An entry point for interacting with the TrimbleMaps Navigation SDK.
Only one instance of this class should be used per application process. Use TrimbleMapsNavigationProvider to easily manage the instance across lifecycle.
Feel free to visit our docs pages and examples before diving in!
The TrimbleMapsNavigation implementation can enter into a couple of internal states:
IdleFree DriveActive Guidance
The SDK starts off in an
Idlestate.Whenever the startTripSession is called, the SDK will enter the
Free Drivestate starting to request and propagate location updates via the LocationObserver.This observer provides 2 location update values in mixed intervals - either the raw one received from the provided LocationEngine or the enhanced one map-matched internally using SDK's native capabilities.
In
Free Drivemode, the enhanced location is computed using nearby to user location's routing tiles that are continuously updating in the background. This can be configured using the OnboardRouterOptions in the NavigationOptions.If the session is stopped, the SDK will stop listening for raw location updates and enter the
Idlestate.A route can be requested with requestRoutes. If the request is successful and returns a non-empty list of routes in the RoutesObserver, the first route at index 0 is going to be chosen as a primary one.
If the SDK is in an
Idlestate, it stays in this same state even when a primary route is available.If the SDK is already in the
Free Drivemode or entering it whenever a primary route is available, the SDK will enter theActive Guidancemode instead and propagate meaningful RouteProgress.If a new routes request is made, or the routes are manually cleared, the SDK automatically fall back to either
IdleorFree Drivestate.You can use setRoutes to provide new routes, clear current ones, or change the route at primary index 0.
-
-
Field Summary
Fields Modifier and Type Field Description public final static StringTAGprivate StringstorageDirprivate final NavigationOptionsnavigationOptions
-
Constructor Summary
Constructors Constructor Description TrimbleMapsNavigation(NavigationOptions navigationOptions)
-
Method Summary
Modifier and Type Method Description final StringgetStorageDir()final UnitsetStorageDir(String storageDir)final NavigationOptionsgetNavigationOptions()final UnitstartTripSession()Starts listening for location updates and enters an Active Guidancestate if there's a primary route available or aFree Drivestate otherwise.final UnitstopTripSession()Stops listening for location updates and enters an Idlestate.final UnitresetTripSession()Reset the session with the same configuration. final UnitsetRouteRefreshCallback(RouteRefreshCallback routeRefreshCallback)final RouteProgressgetRouteProgress()final StringgetRouteUUID()final TripSessionStategetTripSessionState()Return the current TripSession's state. final UnitrequestRoutes(RouteOptions routeOptions, RoutesRequestCallback routesRequestCallback)Requests a route using the provided Router implementation. final UnitrequestRoutes(RouteOptions routeOptions)Requests a route using the provided Router implementation. final UnitcancelRouteRequest()final UnitsetTrip(TrimbleMapsTrip trip)Set a list of routes. final List<DirectionsRoute>getRoutes()Get a list of routes. final UnitonDestroy()Call this method whenever this instance of the TrimbleMapsNavigation is not going to be used anymore and should release all of its resources. final StringretrieveHistory()API used to retrieve logged location and route progress samples for debug purposes. final UnittoggleHistory(Boolean isEnabled)API used to enable/disable location and route progress samples logs for debug purposes. final UnitaddHistoryEvent(String eventType, String eventJsonProperties)API used to artificially add debug events to logs. final StringretrieveSsmlAnnouncementInstruction(Integer index)API used to retrieve the SSML announcement for voice instructions. final UnitregisterLocationObserver(LocationObserver locationObserver)Registers LocationObserver. final UnitunregisterLocationObserver(LocationObserver locationObserver)Unregisters LocationObserver. final UnitregisterRouteProgressObserver(RouteProgressObserver routeProgressObserver)Registers RouteProgressObserver. final UnitunregisterRouteProgressObserver(RouteProgressObserver routeProgressObserver)Unregisters RouteProgressObserver. final UnitregisterRerouteStateObserver(RerouteController.RerouteStateObserver rerouteStateObserver)final UnitunregisterRerouteStateObserver(RerouteController.RerouteStateObserver rerouteStateObserver)final UnitregisterOnboardMapDownloadStatusObserver(OnboardMapDownloadStatusListener onboardMapDataStatusListener)Registers OnboardMapDownloadStatusListener. final UnitunregisterOnboardMapDownloadStatusObserver(OnboardMapDownloadStatusListener onboardMapDataStatusListener)Unregisters OnboardMapDownloadStatusListener. final UnitregisterTunnelObserver(TunnelObserver tunnelObserver)final UnitunregisterTunnelObserver(TunnelObserver tunnelObserver)final UnitregisterOffRouteObserver(OffRouteObserver offRouteObserver)Registers OffRouteObserver. final UnitunregisterOffRouteObserver(OffRouteObserver offRouteObserver)Unregisters OffRouteObserver. final UnitregisterRoutesObserver(RoutesObserver routesObserver)Registers RoutesObserver. final UnitunregisterRoutesObserver(RoutesObserver routesObserver)Unregisters RoutesObserver. final UnitregisterBannerInstructionsObserver(BannerInstructionsObserver bannerInstructionsObserver)Registers BannerInstructionsObserver. final UnitunregisterBannerInstructionsObserver(BannerInstructionsObserver bannerInstructionsObserver)Unregisters BannerInstructionsObserver. final UnitregisterVoiceInstructionsObserver(VoiceInstructionsObserver voiceInstructionsObserver)Registers VoiceInstructionsObserver. final UnitunregisterVoiceInstructionsObserver(VoiceInstructionsObserver voiceInstructionsObserver)Unregisters VoiceInstructionsObserver. final UnitregisterTripSessionStateObserver(TripSessionStateObserver tripSessionStateObserver)Registers TripSessionStateObserver. final UnitunregisterTripSessionStateObserver(TripSessionStateObserver tripSessionStateObserver)Unregisters TripSessionStateObserver. final UnitregisterRouteRestrictionObserver(RouteRestrictionObserver routeRestrictionObserver)final UnitunregisterRouteRestrictionObserver(RouteRestrictionObserver routeRestrictionObserver)final UnitunregisterAllRouteRestrictionObservers()final UnitsetArrivalController(ArrivalController arrivalController)Set your own controller to determine when drivers arrived at stops via ArrivalController. final UnitsetArrivalController()Set your own controller to determine when drivers arrived at stops via ArrivalController. final UnitsetRerouteController(RerouteController rerouteController)Set RerouteController that's automatically invoked when user is off-route. final UnitsetRerouteController()Set RerouteController that's automatically invoked when user is off-route. final RerouteControllergetRerouteController()Get currently set RerouteController. final UnitregisterArrivalObserver(ArrivalObserver arrivalObserver)Registers ArrivalObserver. final UnitunregisterArrivalObserver(ArrivalObserver arrivalObserver)Unregisters ArrivalObserver. final BooleannavigateNextRouteLeg()After arriving at a stop, this can be used to manually decide when to start navigating to the next stop. final UnitregisterRouteAlertsObserver(RouteAlertsObserver routeAlertsObserver)Registers an observer that gets notified whenever the route changes and provides the list of alerts on this new route, if there are any. final UnitunregisterRouteAlertsObserver(RouteAlertsObserver routeAlertsObserver)Unregisters the route alerts observer. final UnitregisterEHorizonObserver(EHorizonObserver eHorizonObserver)Observer will be called when the EHorizon changes. final UnitunregisterEHorizonObserver(EHorizonObserver eHorizonObserver)Unregisters a EHorizon observer. final UnitregisterMapMatcherResultObserver(MapMatcherResultObserver mapMatcherResultObserver)Registers an observer that gets notified whenever a new enhanced location update is available with details about the status of the enhanced location. final UnitunregisterMapMatcherResultObserver(MapMatcherResultObserver mapMatcherResultObserver)Unregisters a MapMatcherResultObserver. final UnitpostUserFeedback(String feedbackType, String description, String feedbackSource, String screenshot, Array<String> feedbackSubType, AppMetadata appMetadata)Send user feedback about an issue or problem with the Navigation SDK. final UnitattachFasterRouteObserver(FasterRouteObserver fasterRouteObserver)Start observing faster routes for a trip session via FasterRouteObserver final UnitdetachFasterRouteObserver()Stop observing the possibility of faster routes. final UnitupdateSensorEvent(SensorEvent sensorEvent)Sends an event to improve navigation positioning. final static NavigationOptions.BuilderdefaultNavigationOptionsBuilder(Context context)Returns a pre-build set of NavigationOptions with smart defaults.
-
-
-
Method Detail
-
getStorageDir
final String getStorageDir()
-
setStorageDir
final Unit setStorageDir(String storageDir)
-
getNavigationOptions
final NavigationOptions getNavigationOptions()
-
startTripSession
@RequiresPermission(anyOf = {"android.permission.ACCESS_COARSE_LOCATION", "android.permission.ACCESS_FINE_LOCATION"}) final Unit startTripSession()
Starts listening for location updates and enters an
Active Guidancestate if there's a primary route available or aFree Drivestate otherwise.
-
stopTripSession
final Unit stopTripSession()
Stops listening for location updates and enters an
Idlestate.
-
resetTripSession
final Unit resetTripSession()
Reset the session with the same configuration. The location becomes unknown, but the NavigationOptions stay the same. This can be used to transport the navigator to a new location.
-
setRouteRefreshCallback
final Unit setRouteRefreshCallback(RouteRefreshCallback routeRefreshCallback)
-
getRouteProgress
final RouteProgress getRouteProgress()
-
getRouteUUID
final String getRouteUUID()
-
getTripSessionState
final TripSessionState getTripSessionState()
Return the current TripSession's state. The state is TripSessionState.STARTED when the session is active, running a foreground service and requesting and returning location updates. The state is TripSessionState.STOPPED when the session is inactive.
-
requestRoutes
@JvmOverloads() final Unit requestRoutes(RouteOptions routeOptions, RoutesRequestCallback routesRequestCallback)
Requests a route using the provided Router implementation. If the request succeeds and the SDK enters an
Active Guidancestate, meaningful RouteProgress updates will be available.Use RoutesObserver and TrimbleMapsNavigation.registerRoutesObserver to observe whenever the routes list reference managed by the SDK changes, regardless of a source.
Use TrimbleMapsNavigation.setRoutes to supply a transformed list of routes, or a list from an external source, to be managed by the SDK.
- Parameters:
routeOptions- params for the route requestroutesRequestCallback- listener that gets notified when request state changes
-
requestRoutes
@JvmOverloads() final Unit requestRoutes(RouteOptions routeOptions)
Requests a route using the provided Router implementation. If the request succeeds and the SDK enters an
Active Guidancestate, meaningful RouteProgress updates will be available.Use RoutesObserver and TrimbleMapsNavigation.registerRoutesObserver to observe whenever the routes list reference managed by the SDK changes, regardless of a source.
Use TrimbleMapsNavigation.setRoutes to supply a transformed list of routes, or a list from an external source, to be managed by the SDK.
- Parameters:
routeOptions- params for the route request
-
cancelRouteRequest
final Unit cancelRouteRequest()
-
setTrip
final Unit setTrip(TrimbleMapsTrip trip)
Set a list of routes.
If the list is empty, the SDK will exit the
Active Guidancestate.If the list is not empty, the route at index 0 is going to be treated as the primary route and used for route progress calculations and off route events.
Use RoutesObserver and TrimbleMapsNavigation.registerRoutesObserver to observe whenever the routes list reference managed by the SDK changes, regardless of a source.
-
getRoutes
final List<DirectionsRoute> getRoutes()
Get a list of routes.
If the list is not empty, the route at index 0 is the one treated as the primary route and used for route progress, off route events and map-matching calculations.
-
onDestroy
final Unit onDestroy()
Call this method whenever this instance of the TrimbleMapsNavigation is not going to be used anymore and should release all of its resources.
-
retrieveHistory
final String retrieveHistory()
API used to retrieve logged location and route progress samples for debug purposes.
-
toggleHistory
final Unit toggleHistory(Boolean isEnabled)
API used to enable/disable location and route progress samples logs for debug purposes.
-
addHistoryEvent
final Unit addHistoryEvent(String eventType, String eventJsonProperties)
API used to artificially add debug events to logs.
-
retrieveSsmlAnnouncementInstruction
final String retrieveSsmlAnnouncementInstruction(Integer index)
API used to retrieve the SSML announcement for voice instructions.
-
registerLocationObserver
final Unit registerLocationObserver(LocationObserver locationObserver)
Registers LocationObserver. The updates are available whenever the trip session is started.
-
unregisterLocationObserver
final Unit unregisterLocationObserver(LocationObserver locationObserver)
Unregisters LocationObserver.
-
registerRouteProgressObserver
final Unit registerRouteProgressObserver(RouteProgressObserver routeProgressObserver)
Registers RouteProgressObserver. The updates are available whenever the trip session is started and a primary route is available.
-
unregisterRouteProgressObserver
final Unit unregisterRouteProgressObserver(RouteProgressObserver routeProgressObserver)
Unregisters RouteProgressObserver.
-
registerRerouteStateObserver
final Unit registerRerouteStateObserver(RerouteController.RerouteStateObserver rerouteStateObserver)
-
unregisterRerouteStateObserver
final Unit unregisterRerouteStateObserver(RerouteController.RerouteStateObserver rerouteStateObserver)
-
registerOnboardMapDownloadStatusObserver
final Unit registerOnboardMapDownloadStatusObserver(OnboardMapDownloadStatusListener onboardMapDataStatusListener)
Registers OnboardMapDownloadStatusListener. The updates are available whenever the trip session is started and a primary route is available.
-
unregisterOnboardMapDownloadStatusObserver
final Unit unregisterOnboardMapDownloadStatusObserver(OnboardMapDownloadStatusListener onboardMapDataStatusListener)
Unregisters OnboardMapDownloadStatusListener.
-
registerTunnelObserver
final Unit registerTunnelObserver(TunnelObserver tunnelObserver)
-
unregisterTunnelObserver
final Unit unregisterTunnelObserver(TunnelObserver tunnelObserver)
-
registerOffRouteObserver
final Unit registerOffRouteObserver(OffRouteObserver offRouteObserver)
Registers OffRouteObserver. The updates are available whenever SDK is in an
Active Guidancestate and detects an off route event.The SDK will automatically request redirected route. You can control or observe this request with RerouteController and RerouteState.
-
unregisterOffRouteObserver
final Unit unregisterOffRouteObserver(OffRouteObserver offRouteObserver)
Unregisters OffRouteObserver.
-
registerRoutesObserver
final Unit registerRoutesObserver(RoutesObserver routesObserver)
Registers RoutesObserver. The updates are available when a new list of routes is set. The route at index 0, if exist, will be treated as the primary route for 'Active Guidance'.
-
unregisterRoutesObserver
final Unit unregisterRoutesObserver(RoutesObserver routesObserver)
Unregisters RoutesObserver.
-
registerBannerInstructionsObserver
final Unit registerBannerInstructionsObserver(BannerInstructionsObserver bannerInstructionsObserver)
Registers BannerInstructionsObserver. The updates are available whenever SDK is in an
Active Guidancestate. The SDK will push this event only once per route step.
-
unregisterBannerInstructionsObserver
final Unit unregisterBannerInstructionsObserver(BannerInstructionsObserver bannerInstructionsObserver)
Unregisters BannerInstructionsObserver.
-
registerVoiceInstructionsObserver
final Unit registerVoiceInstructionsObserver(VoiceInstructionsObserver voiceInstructionsObserver)
Registers VoiceInstructionsObserver. The updates are available whenever SDK is in an
Active Guidancestate. The SDK will push this event only once per route step.
-
unregisterVoiceInstructionsObserver
final Unit unregisterVoiceInstructionsObserver(VoiceInstructionsObserver voiceInstructionsObserver)
Unregisters VoiceInstructionsObserver.
-
registerTripSessionStateObserver
final Unit registerTripSessionStateObserver(TripSessionStateObserver tripSessionStateObserver)
Registers TripSessionStateObserver. Monitors the trip session's state.
-
unregisterTripSessionStateObserver
final Unit unregisterTripSessionStateObserver(TripSessionStateObserver tripSessionStateObserver)
Unregisters TripSessionStateObserver.
-
registerRouteRestrictionObserver
final Unit registerRouteRestrictionObserver(RouteRestrictionObserver routeRestrictionObserver)
-
unregisterRouteRestrictionObserver
final Unit unregisterRouteRestrictionObserver(RouteRestrictionObserver routeRestrictionObserver)
-
unregisterAllRouteRestrictionObservers
final Unit unregisterAllRouteRestrictionObservers()
-
setArrivalController
@JvmOverloads() final Unit setArrivalController(ArrivalController arrivalController)
Set your own controller to determine when drivers arrived at stops via ArrivalController. Use navigateNextRouteLeg to manually move navigator to the next stop. To reset to the automatic arrival controller, call setArrivalController.
By default uses AutoArrivalController.
Set null disables arrival at stops completely. Use this if you want to write your own mechanism for handling arrival at stops.
- Parameters:
arrivalController- ArrivalController
-
setArrivalController
@JvmOverloads() final Unit setArrivalController()
Set your own controller to determine when drivers arrived at stops via ArrivalController. Use navigateNextRouteLeg to manually move navigator to the next stop. To reset to the automatic arrival controller, call setArrivalController.
By default uses AutoArrivalController.
Set null disables arrival at stops completely. Use this if you want to write your own mechanism for handling arrival at stops.
-
setRerouteController
@JvmOverloads() final Unit setRerouteController(RerouteController rerouteController)
Set RerouteController that's automatically invoked when user is off-route.
By default uses TrimbleMapsRerouteController. Setting null disables auto-reroute.
-
setRerouteController
@JvmOverloads() final Unit setRerouteController()
Set RerouteController that's automatically invoked when user is off-route.
By default uses TrimbleMapsRerouteController. Setting null disables auto-reroute.
-
getRerouteController
final RerouteController getRerouteController()
Get currently set RerouteController.
-
registerArrivalObserver
final Unit registerArrivalObserver(ArrivalObserver arrivalObserver)
Registers ArrivalObserver. Monitor arrival at stops and destinations. For more control of arrival at stops, see setArrivalController.
-
unregisterArrivalObserver
final Unit unregisterArrivalObserver(ArrivalObserver arrivalObserver)
Unregisters ArrivalObserver.
-
navigateNextRouteLeg
final Boolean navigateNextRouteLeg()
After arriving at a stop, this can be used to manually decide when to start navigating to the next stop. Use the ArrivalController to control when to call navigateNextRouteLeg.
-
registerRouteAlertsObserver
final Unit registerRouteAlertsObserver(RouteAlertsObserver routeAlertsObserver)
Registers an observer that gets notified whenever the route changes and provides the list of alerts on this new route, if there are any. The alerts returned here are equal to the ones available in RouteProgress.upcomingRouteAlerts, but they capture the whole route (not only what's ahead of us) and don't have the UpcomingRouteAlert.distanceToStart data.
-
unregisterRouteAlertsObserver
final Unit unregisterRouteAlertsObserver(RouteAlertsObserver routeAlertsObserver)
Unregisters the route alerts observer.
-
registerEHorizonObserver
final Unit registerEHorizonObserver(EHorizonObserver eHorizonObserver)
Observer will be called when the EHorizon changes.
Registering an EHorizonObserver activates the Electronic Horizon module.
-
unregisterEHorizonObserver
final Unit unregisterEHorizonObserver(EHorizonObserver eHorizonObserver)
Unregisters a EHorizon observer.
Unregistering all observers deactivates the module.
-
registerMapMatcherResultObserver
final Unit registerMapMatcherResultObserver(MapMatcherResultObserver mapMatcherResultObserver)
Registers an observer that gets notified whenever a new enhanced location update is available with details about the status of the enhanced location.
-
unregisterMapMatcherResultObserver
final Unit unregisterMapMatcherResultObserver(MapMatcherResultObserver mapMatcherResultObserver)
Unregisters a MapMatcherResultObserver.
-
postUserFeedback
final Unit postUserFeedback(String feedbackType, String description, String feedbackSource, String screenshot, Array<String> feedbackSubType, AppMetadata appMetadata)
Send user feedback about an issue or problem with the Navigation SDK.
- Parameters:
feedbackType- one of FeedbackEvent.Typedescription- description messagefeedbackSource- one of FeedbackEvent.Sourcescreenshot- encoded screenshot (optional)feedbackSubType- array of FeedbackEvent.Description (optional)appMetadata- AppMetadata information (optional)
-
attachFasterRouteObserver
final Unit attachFasterRouteObserver(FasterRouteObserver fasterRouteObserver)
Start observing faster routes for a trip session via FasterRouteObserver
- Parameters:
fasterRouteObserver- FasterRouteObserver
-
detachFasterRouteObserver
final Unit detachFasterRouteObserver()
Stop observing the possibility of faster routes.
-
updateSensorEvent
final Unit updateSensorEvent(SensorEvent sensorEvent)
Sends an event to improve navigation positioning. See SensorEventEmitter to register
- Parameters:
sensorEvent- the Android sensor event, it will be ignored if it is not recognized
-
defaultNavigationOptionsBuilder
final static NavigationOptions.Builder defaultNavigationOptionsBuilder(Context context)
Returns a pre-build set of NavigationOptions with smart defaults.
Use NavigationOptions.toBuilder to easily customize selected options.
- Parameters:
context- Context
-
-