com.mapbox.services.android.navigation.v5.navigation

Class MapboxNavigation

java.lang.Object

com.mapbox.services.android.navigation.v5.navigation.MapboxNavigation

All Implemented Interfaces:

ServiceConnection

public class MapboxNavigation
extends Object
implements ServiceConnection

A MapboxNavigation class for interacting with and customizing a navigation session.

Instance of this class are used to setup, customize, start, and end a navigation session.

Since:

0.1.0

See Also:

Navigation documentation

Constructor Summary

Constructors

Constructor and Description
MapboxNavigation(Context context, String accessToken) Constructs a new instance of this class using the default options.
MapboxNavigation(Context context, String accessToken, MapboxNavigationOptions options) Constructs a new instance of this class using a custom built options class.
MapboxNavigation(Context context, String accessToken, MapboxNavigationOptions options, com.mapbox.android.core.location.LocationEngine locationEngine) Constructs a new instance of this class using a custom built options class.

Method Summary

Modifier and Type	Method and Description
void	addFasterRouteListener(FasterRouteListener fasterRouteListener) This adds a new faster route listener which is invoked when a new, faster DirectionsRoute has been retrieved by the specified criteria in FasterRoute.
void	addHistoryEvent(String eventType, String eventJsonProperties)
void	addMilestone(Milestone milestone) Navigation Milestones provide a powerful way to give your user instructions at custom defined locations along their route.
void	addMilestoneEventListener(MilestoneEventListener milestoneEventListener) This adds a new milestone event listener which is invoked when a milestone gets triggered.
void	addMilestones(List<Milestone> milestones) Adds the given list of Milestone to be triggered during navigation.
void	addNavigationEventListener(NavigationEventListener navigationEventListener) This adds a new navigation event listener which is invoked when navigation service begins running in the background and again when the service gets destroyed.
void	addOffRouteListener(OffRouteListener offRouteListener) This adds a new off route listener which is invoked when the devices location veers off the route and the specified criteria's in MapboxNavigationOptions have been met.
void	addProgressChangeListener(ProgressChangeListener progressChangeListener) This adds a new progress change listener which is invoked when a location change occurs and the navigation engine successfully runs it's calculations on it.
void	addRawLocationListener(RawLocationListener rawLocationListener) This adds a new raw location listener which is invoked when a new Location has been pushed by the LocationEngine.
void	cancelFeedback(String feedbackId) Cancels an existing feedback event generated by recordFeedback(String, String, String).
Camera	getCameraEngine() Returns the current camera engine used to configure the camera position while routing.
FasterRoute	getFasterRouteEngine() This will return the currently set faster-route engine which will or is being used during the navigation session.
com.mapbox.android.core.location.LocationEngine	getLocationEngine() Will return the currently set location engine.
OffRoute	getOffRouteEngine() This will return the currently set off-route engine which will or is being used during the navigation session.
Snap	getSnapEngine() This will return the currently set snap engine which will or is being used during the navigation session.
void	onDestroy() Critical to place inside your navigation activity so that when your application gets destroyed the navigation service unbinds and gets destroyed, preventing any memory leaks.
void	onServiceConnected(ComponentName name, IBinder service)
void	onServiceDisconnected(ComponentName name)
String	recordFeedback(String feedbackType, String description, String source) Creates a new FeedbackEvent with a given type, description, and source.
void	removeFasterRouteListener(FasterRouteListener fasterRouteListener) This removes a specific faster route listener by passing in the instance of it or you can pass in null to remove all the listeners.
void	removeMilestone(int milestoneIdentifier) Remove a specific milestone by passing in the identifier associated with the milestone you'd like to remove.
void	removeMilestone(Milestone milestone) Remove a specific milestone by passing in the instance of it.
void	removeMilestoneEventListener(MilestoneEventListener milestoneEventListener) This removes a specific milestone event listener by passing in the instance of it or you can pass in null to remove all the listeners.
void	removeNavigationEventListener(NavigationEventListener navigationEventListener) This removes a specific navigation event listener by passing in the instance of it or you can pass in null to remove all the listeners.
void	removeOffRouteListener(OffRouteListener offRouteListener) This removes a specific off route listener by passing in the instance of it or you can pass in null to remove all the listeners.
void	removeProgressChangeListener(ProgressChangeListener progressChangeListener) This removes a specific progress change listener by passing in the instance of it or you can pass in null to remove all the listeners.
void	removeRawLocationListener(RawLocationListener rawLocationListener) This removes a specific raw location listener by passing in the instance of it or you can pass in null to remove all the listeners.
String	retrieveHistory()
String	retrieveSsmlAnnouncementInstruction(int index)
void	setCameraEngine(Camera cameraEngine) Navigation uses a camera engine to determine the camera position while routing.
void	setFasterRouteEngine(FasterRoute fasterRouteEngine) This API is used to pass in a custom implementation of the faster-route detection logic, A default faster-route detection engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.
void	setLocationEngine(com.mapbox.android.core.location.LocationEngine locationEngine) Navigation needs an instance of location engine in order to acquire user location information and handle events based off of the current information.
void	setLocationEngineRequest(com.mapbox.android.core.location.LocationEngineRequest locationEngineRequest) This method updates the LocationEngineRequest that is used with the LocationEngine.
void	setOffRouteEngine(OffRoute offRouteEngine) This API is used to pass in a custom implementation of the off-route logic, A default off-route detection engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.
void	setSnapEngine(Snap snapEngine) This API is used to pass in a custom implementation of the snapping logic, A default snap-to-route engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.
void	startNavigation(com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute) Calling this method begins a new navigation session using the provided directions route.
void	startNavigation(com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute, DirectionsRouteType routeType) Calling this method with DirectionsRouteType.NEW_ROUTE begins a new navigation session using the provided directions route.
void	stopNavigation() Call this when the navigation session needs to end before the user reaches their final destination.
void	toggleHistory(boolean isEnabled)
void	updateFeedback(String feedbackId, String feedbackType, String description, String screenshot) Updates an existing feedback event generated by recordFeedback(String, String, String).
boolean	updateRouteLegIndex(int legIndex) Use this method to update the leg index of the current DirectionsRoute being traveled along.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface android.content.ServiceConnection

onBindingDied, onNullBinding

Constructor Detail

MapboxNavigation

public MapboxNavigation(@NonNull
                        Context context,
                        @NonNull
                        String accessToken)

Constructs a new instance of this class using the default options. This should be used over MapboxNavigation(Context, String, MapboxNavigationOptions) if all the default options fit your needs.

Initialization will also add the default milestones and create a new location engine which will be used during navigation unless a different engine gets passed in through setLocationEngine(LocationEngine).

Parameters:

context - required in order to create and bind the navigation service

accessToken - a valid Mapbox access token

Since:

0.5.0

MapboxNavigation

public MapboxNavigation(@NonNull
                        Context context,
                        @NonNull
                        String accessToken,
                        @NonNull
                        MapboxNavigationOptions options)

Constructs a new instance of this class using a custom built options class. Building a custom MapboxNavigationOptions object and passing it in allows you to further customize the user experience. While many of the default values have been tested thoroughly, you might find that your app requires special tweaking. Once this class is initialized, the options specified through the options class cannot be modified.

Initialization will also add the default milestones and create a new location engine which will be used during navigation unless a different engine gets passed in through setLocationEngine(LocationEngine).

Parameters:

context - required in order to create and bind the navigation service

options - a custom built MapboxNavigationOptions class

accessToken - a valid Mapbox access token

Since:

0.5.0

See Also:

MapboxNavigationOptions

MapboxNavigation

public MapboxNavigation(@NonNull
                        Context context,
                        @NonNull
                        String accessToken,
                        @NonNull
                        MapboxNavigationOptions options,
                        @NonNull
                        com.mapbox.android.core.location.LocationEngine locationEngine)

Constructs a new instance of this class using a custom built options class. Building a custom MapboxNavigationOptions object and passing it in allows you to further customize the user experience. Once this class is initialized, the options specified through the options class cannot be modified.

Parameters:

context - required in order to create and bind the navigation service

accessToken - a valid Mapbox access token

options - a custom built MapboxNavigationOptions class

locationEngine - a LocationEngine to provide Location updates

Since:

0.19.0

See Also:

MapboxNavigationOptions

Method Detail

onDestroy

public void onDestroy()

Critical to place inside your navigation activity so that when your application gets destroyed the navigation service unbinds and gets destroyed, preventing any memory leaks. Calling this also removes all listeners that have been attached.

addMilestone

public void addMilestone(@NonNull
                         Milestone milestone)

Navigation Milestones provide a powerful way to give your user instructions at custom defined locations along their route. Default milestones are automatically added unless MapboxNavigationOptions.defaultMilestonesEnabled() is set to false but they can also be individually removed using the removeMilestone(Milestone) API. Once a custom milestone is built, it will need to be passed into the navigation SDK through this method.

Milestones can only be added once and must be removed and added back if any changes are desired.

Parameters:

milestone - a custom built milestone

Since:

0.4.0

addMilestones

public void addMilestones(@NonNull
                          List<Milestone> milestones)

Adds the given list of Milestone to be triggered during navigation.

Milestones can only be added once and must be removed and added back if any changes are desired.

Parameters:

milestones - a list of custom built milestone

Since:

0.14.0

removeMilestone

public void removeMilestone(@Nullable
                            Milestone milestone)

Remove a specific milestone by passing in the instance of it. Removal of all the milestones can be achieved by passing in null rather than a specific milestone.

Parameters:

milestone - a milestone you'd like to have removed or null if you'd like to remove all milestones

Since:

0.4.0

removeMilestone

public void removeMilestone(int milestoneIdentifier)

Remove a specific milestone by passing in the identifier associated with the milestone you'd like to remove. If the identifier passed in does not match one of the milestones in the list, a warning will return in the log.

Parameters:

milestoneIdentifier - identifier matching one of the milestones

Since:

0.5.0

setLocationEngine

public void setLocationEngine(@NonNull
                              com.mapbox.android.core.location.LocationEngine locationEngine)

Navigation needs an instance of location engine in order to acquire user location information and handle events based off of the current information. By default, a LocationEngine is created using LocationEngineProvider.getBestLocationEngine(Context).

In ideal conditions, the Navigation SDK will receive location updates once every second with mild to high horizontal accuracy. The location update must also contain all information an Android location object would expect including bearing, speed, timestamp, and latitude/longitude.

This method can be called during an active navigation session. The active LocationEngine will be replaced and the new one (passed via this method) will be activated with the current LocationEngineRequest.

Parameters:

locationEngine - a LocationEngine used for the navigation session

Since:

0.1.0

getLocationEngine

@NonNull
public com.mapbox.android.core.location.LocationEngine getLocationEngine()

Will return the currently set location engine. By default, the LOST location engine that's created on initialization of this class. If a custom location engine is preferred to be used, setLocationEngine(LocationEngine) is offered which will replace the default.

Returns:

the location engine which is will or currently is being used during the navigation session

Since:

0.5.0

setLocationEngineRequest

public void setLocationEngineRequest(@NonNull
                                     com.mapbox.android.core.location.LocationEngineRequest locationEngineRequest)

This method updates the LocationEngineRequest that is used with the LocationEngine.

If a request is not provided via setLocationEngineRequest(LocationEngineRequest), a default will be provided with optimized settings for navigation.

This method can be called during an active navigation session. The active LocationEngineRequest will be replaced and the new one (passed via this method) will be activated with the current LocationEngine.

Parameters:

locationEngineRequest - to be used with the current LocationEngine

startNavigation

public void startNavigation(@NonNull
                            com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute)

Calling this method begins a new navigation session using the provided directions route. This API is also intended to be used when a reroute occurs passing in the updated directions route.

On initial start of the navigation session, the navigation services gets created and bound to your activity. Unless disabled, a notification will be displayed to the user and will remain until the service stops running in the background.

The directions route should be acquired by building a NavigationRoute object and calling NavigationRoute.getRoute(Callback) on it. Using navigation route request a route with the required parameters needed while at the same time, allowing for flexibility in other parts of the request.

Parameters:

directionsRoute - a DirectionsRoute that makes up the path your user should traverse along

Since:

0.1.0

startNavigation

public void startNavigation(@NonNull
                            com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute,
                            @NonNull
                            DirectionsRouteType routeType)

Calling this method with DirectionsRouteType.NEW_ROUTE begins a new navigation session using the provided directions route. If called with DirectionsRouteType.FRESH_ROUTE, only leg annotation data will be update - can be used with RouteRefresh.

Parameters:

directionsRoute - a DirectionsRoute that makes up the path your user should traverse along

routeType - either new or fresh to determine what data navigation should consider

See Also:

startNavigation(DirectionsRoute)

stopNavigation

public void stopNavigation()

Call this when the navigation session needs to end before the user reaches their final destination.

Ending the navigation session ends and unbinds the navigation service meaning any milestone, progress change, or off-route listeners will not be invoked anymore. A call returning false will occur to NavigationEventListener.onRunning(boolean) to notify you when the service ends.

Since:

0.1.0

addMilestoneEventListener

public void addMilestoneEventListener(@NonNull
                                      MilestoneEventListener milestoneEventListener)

This adds a new milestone event listener which is invoked when a milestone gets triggered. If more then one milestone gets triggered on a location update, each milestone event listener will be invoked for each of those milestones. This is important to consider if you are using voice instructions since this would cause multiple instructions to be said at once. Ideally the milestones setup should avoid triggering too close to each other.

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

milestoneEventListener - an implementation of MilestoneEventListener which hasn't already been added

Since:

0.4.0

See Also:

MilestoneEventListener

removeMilestoneEventListener

public void removeMilestoneEventListener(@Nullable
                                         MilestoneEventListener milestoneEventListener)

This removes a specific milestone event listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

milestoneEventListener - an implementation of MilestoneEventListener which currently exist in the milestoneEventListener list

Since:

0.4.0

See Also:

MilestoneEventListener

addProgressChangeListener

public void addProgressChangeListener(@NonNull
                                      ProgressChangeListener progressChangeListener)

This adds a new progress change listener which is invoked when a location change occurs and the navigation engine successfully runs it's calculations on it.

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

progressChangeListener - an implementation of ProgressChangeListener which hasn't already been added

Since:

0.1.0

See Also:

ProgressChangeListener

removeProgressChangeListener

public void removeProgressChangeListener(@Nullable
                                         ProgressChangeListener progressChangeListener)

This removes a specific progress change listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

progressChangeListener - an implementation of ProgressChangeListener which currently exist in the progressChangeListener list

Since:

0.1.0

See Also:

ProgressChangeListener

addOffRouteListener

public void addOffRouteListener(@NonNull
                                OffRouteListener offRouteListener)

This adds a new off route listener which is invoked when the devices location veers off the route and the specified criteria's in MapboxNavigationOptions have been met.

The behavior that causes this listeners callback to get invoked vary depending on whether a custom off route engine has been set using setOffRouteEngine(OffRoute).

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

offRouteListener - an implementation of OffRouteListener which hasn't already been added

Since:

0.2.0

See Also:

OffRouteListener

removeOffRouteListener

public void removeOffRouteListener(@Nullable
                                   OffRouteListener offRouteListener)

This removes a specific off route listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

offRouteListener - an implementation of OffRouteListener which currently exist in the offRouteListener list

Since:

0.2.0

See Also:

OffRouteListener

addNavigationEventListener

public void addNavigationEventListener(@NonNull
                                       NavigationEventListener navigationEventListener)

This adds a new navigation event listener which is invoked when navigation service begins running in the background and again when the service gets destroyed.

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

navigationEventListener - an implementation of NavigationEventListener which hasn't already been added

Since:

0.1.0

See Also:

NavigationEventListener

removeNavigationEventListener

public void removeNavigationEventListener(@Nullable
                                          NavigationEventListener navigationEventListener)

This removes a specific navigation event listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

navigationEventListener - an implementation of NavigationEventListener which currently exist in the navigationEventListener list

Since:

0.1.0

See Also:

NavigationEventListener

addFasterRouteListener

public void addFasterRouteListener(@NonNull
                                   FasterRouteListener fasterRouteListener)

This adds a new faster route listener which is invoked when a new, faster DirectionsRoute has been retrieved by the specified criteria in FasterRoute.

The behavior that causes this listeners callback to get invoked vary depending on whether a custom faster route engine has been set using setFasterRouteEngine(FasterRoute).

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

fasterRouteListener - an implementation of FasterRouteListener

Since:

0.9.0

See Also:

FasterRouteListener

removeFasterRouteListener

public void removeFasterRouteListener(@Nullable
                                      FasterRouteListener fasterRouteListener)

This removes a specific faster route listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

fasterRouteListener - an implementation of FasterRouteListener which currently exist in the fasterRouteListeners list

Since:

0.9.0

See Also:

FasterRouteListener

addRawLocationListener

public void addRawLocationListener(@NonNull
                                   RawLocationListener rawLocationListener)

This adds a new raw location listener which is invoked when a new Location has been pushed by the LocationEngine.

It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.

Parameters:

rawLocationListener - an implementation of RawLocationListener

removeRawLocationListener

public void removeRawLocationListener(@Nullable
                                      RawLocationListener rawLocationListener)

This removes a specific raw location listener by passing in the instance of it or you can pass in null to remove all the listeners. When onDestroy() is called, all listeners get removed automatically, removing the requirement for developers to manually handle this.

If the listener you are trying to remove does not exist in the list, a warning will be printed in the log.

Parameters:

rawLocationListener - an implementation of RawLocationListener

setCameraEngine

public void setCameraEngine(@NonNull
                            Camera cameraEngine)

Navigation uses a camera engine to determine the camera position while routing. By default, it uses a SimpleCamera. If you would like to customize how the camera is positioned, create a new Camera and set it here.

Parameters:

cameraEngine - camera engine used to configure camera position while routing

Since:

0.10.0

getCameraEngine

@NonNull
public Camera getCameraEngine()

Returns the current camera engine used to configure the camera position while routing. By default, a SimpleCamera is used.

Returns:

camera engine used to configure camera position while routing

Since:

0.10.0

setSnapEngine

public void setSnapEngine(@NonNull
                          Snap snapEngine)

This API is used to pass in a custom implementation of the snapping logic, A default snap-to-route engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.

In general, snap logic can be anything that modifies the device's true location. For more information see the implementation notes in Snap.

The engine can be changed at anytime, even during a navigation session.

Parameters:

snapEngine - a custom implementation of the Snap class

Since:

0.5.0

See Also:

Snap

getSnapEngine

public Snap getSnapEngine()

This will return the currently set snap engine which will or is being used during the navigation session. If no snap engine has been set yet, the default engine will be returned.

Returns:

the snap engine currently set and will/is being used for the navigation session

Since:

0.5.0

See Also:

Snap

setOffRouteEngine

public void setOffRouteEngine(@NonNull
                              OffRoute offRouteEngine)

This API is used to pass in a custom implementation of the off-route logic, A default off-route detection engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.

The engine can be changed at anytime, even during a navigation session.

Parameters:

offRouteEngine - a custom implementation of the OffRoute class

Since:

0.5.0

See Also:

OffRoute

getOffRouteEngine

@NonNull
public OffRoute getOffRouteEngine()

This will return the currently set off-route engine which will or is being used during the navigation session. If no off-route engine has been set yet, the default engine will be returned.

Returns:

the off-route engine currently set and will/is being used for the navigation session

Since:

0.5.0

See Also:

OffRoute

setFasterRouteEngine

public void setFasterRouteEngine(@NonNull
                                 FasterRoute fasterRouteEngine)

This API is used to pass in a custom implementation of the faster-route detection logic, A default faster-route detection engine is attached when this class is first initialized; setting a custom one will replace it with your own implementation.

The engine can be changed at anytime, even during a navigation session.

Parameters:

fasterRouteEngine - a custom implementation of the FasterRoute class

Since:

0.9.0

See Also:

FasterRoute

getFasterRouteEngine

@NonNull
public FasterRoute getFasterRouteEngine()

This will return the currently set faster-route engine which will or is being used during the navigation session. If no faster-route engine has been set yet, the default engine will be returned.

Returns:

the faster-route engine currently set and will/is being used for the navigation session

Since:

0.9.0

See Also:

FasterRoute

recordFeedback

public String recordFeedback(String feedbackType,
                             String description,
                             String source)

Creates a new FeedbackEvent with a given type, description, and source.

Returns a String feedbackId that can be used to update or cancel this feedback event. There is a 20 second time period set after this method is called to do so.

Parameters:

feedbackType - from list of set feedback types

description - an option description to provide more detail about the feedback

source - either from the drop-in UI or a reroute

Returns:

String feedbackId

Since:

0.7.0

updateFeedback

public void updateFeedback(String feedbackId,
                           String feedbackType,
                           String description,
                           String screenshot)

Updates an existing feedback event generated by recordFeedback(String, String, String).

Uses a feedback ID to find the correct event and then adjusts the feedbackType and description.

Parameters:

feedbackId - generated from recordFeedback(String, String, String)

feedbackType - from list of set feedback types

description - an optional description to provide more detail about the feedback

screenshot - an optional encoded screenshot to provide more detail about the feedback

Since:

0.8.0

cancelFeedback

public void cancelFeedback(String feedbackId)

Cancels an existing feedback event generated by recordFeedback(String, String, String).

Uses a feedback ID to find the correct event and then cancels it (will no longer be recorded).

Parameters:

feedbackId - generated from recordFeedback(String, String, String)

Since:

0.7.0

updateRouteLegIndex

public boolean updateRouteLegIndex(int legIndex)

Use this method to update the leg index of the current DirectionsRoute being traveled along.

An index passed here that is not valid will be ignored. Please note, the leg index will automatically increment by default. To disable this, use MapboxNavigationOptions.enableAutoIncrementLegIndex().

Parameters:

legIndex - to be set

Returns:

true if leg index updated, false otherwise

retrieveHistory

public String retrieveHistory()

toggleHistory

public void toggleHistory(boolean isEnabled)

addHistoryEvent

public void addHistoryEvent(String eventType,
                            String eventJsonProperties)

retrieveSsmlAnnouncementInstruction

public String retrieveSsmlAnnouncementInstruction(int index)

onServiceConnected

public void onServiceConnected(ComponentName name,
                               IBinder service)

Specified by:

onServiceConnected in interface ServiceConnection

onServiceDisconnected

public void onServiceDisconnected(ComponentName name)

Specified by:

onServiceDisconnected in interface ServiceConnection