public class MapboxNavigation extends Object implements ServiceConnection
Instance of this class are used to setup, customize, start, and end a navigation session.
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.
|
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 |
addMilestone(Milestone milestone)
Navigation
Milestone s 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 |
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.
|
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 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. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
onBindingDied, onNullBinding
public MapboxNavigation(@NonNull Context context, @NonNull String accessToken)
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)
.
context
- required in order to create and bind the navigation serviceaccessToken
- a valid Mapbox access tokenpublic MapboxNavigation(@NonNull Context context, @NonNull String accessToken, @NonNull MapboxNavigationOptions options)
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)
.
context
- required in order to create and bind the navigation serviceoptions
- a custom built MapboxNavigationOptions
classaccessToken
- a valid Mapbox access tokenMapboxNavigationOptions
public MapboxNavigation(@NonNull Context context, @NonNull String accessToken, @NonNull MapboxNavigationOptions options, @NonNull com.mapbox.android.core.location.LocationEngine locationEngine)
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.context
- required in order to create and bind the navigation serviceaccessToken
- a valid Mapbox access tokenoptions
- a custom built MapboxNavigationOptions
classlocationEngine
- a LocationEngine to provide Location updatesMapboxNavigationOptions
public void onDestroy()
public void addMilestone(@NonNull Milestone milestone)
Milestone
s 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.
milestone
- a custom built milestonepublic void addMilestones(@NonNull List<Milestone> milestones)
Milestone
to be triggered during navigation.
Milestones can only be added once and must be removed and added back if any changes are desired.
milestones
- a list of custom built milestonepublic void removeMilestone(@Nullable Milestone milestone)
milestone
- a milestone you'd like to have removed or null if you'd like to remove all
milestonespublic void removeMilestone(int milestoneIdentifier)
milestoneIdentifier
- identifier matching one of the milestonespublic void setLocationEngine(@NonNull com.mapbox.android.core.location.LocationEngine locationEngine)
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
.
locationEngine
- a LocationEngine
used for the navigation session@NonNull public com.mapbox.android.core.location.LocationEngine getLocationEngine()
setLocationEngine(LocationEngine)
is offered which will replace the default.public void setLocationEngineRequest(@NonNull com.mapbox.android.core.location.LocationEngineRequest locationEngineRequest)
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
.
locationEngineRequest
- to be used with the current LocationEngine
public void startNavigation(@NonNull com.mapbox.api.directions.v5.models.DirectionsRoute directionsRoute)
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.
directionsRoute
- a DirectionsRoute
that makes up the path your user should
traverse alongpublic void stopNavigation()
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.
public void addMilestoneEventListener(@NonNull MilestoneEventListener milestoneEventListener)
It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.
milestoneEventListener
- an implementation of MilestoneEventListener
which hasn't
already been addedMilestoneEventListener
public void removeMilestoneEventListener(@Nullable MilestoneEventListener milestoneEventListener)
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.
milestoneEventListener
- an implementation of MilestoneEventListener
which
currently exist in the milestoneEventListener listMilestoneEventListener
public void addProgressChangeListener(@NonNull ProgressChangeListener progressChangeListener)
It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.
progressChangeListener
- an implementation of ProgressChangeListener
which hasn't
already been addedProgressChangeListener
public void removeProgressChangeListener(@Nullable ProgressChangeListener progressChangeListener)
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.
progressChangeListener
- an implementation of ProgressChangeListener
which
currently exist in the progressChangeListener listProgressChangeListener
public void addOffRouteListener(@NonNull OffRouteListener offRouteListener)
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.
offRouteListener
- an implementation of OffRouteListener
which hasn't already been
addedOffRouteListener
public void removeOffRouteListener(@Nullable OffRouteListener offRouteListener)
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.
offRouteListener
- an implementation of OffRouteListener
which currently exist in
the offRouteListener listOffRouteListener
public void addNavigationEventListener(@NonNull NavigationEventListener navigationEventListener)
It is not possible to add the same listener implementation more then once and a warning will be printed in the log if attempted.
navigationEventListener
- an implementation of NavigationEventListener
which
hasn't already been addedNavigationEventListener
public void removeNavigationEventListener(@Nullable NavigationEventListener navigationEventListener)
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.
navigationEventListener
- an implementation of NavigationEventListener
which
currently exist in the navigationEventListener listNavigationEventListener
public void addFasterRouteListener(@NonNull FasterRouteListener fasterRouteListener)
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.
fasterRouteListener
- an implementation of FasterRouteListener
FasterRouteListener
public void removeFasterRouteListener(@Nullable FasterRouteListener fasterRouteListener)
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.
fasterRouteListener
- an implementation of FasterRouteListener
which currently exist in
the fasterRouteListeners listFasterRouteListener
public void setCameraEngine(@NonNull Camera cameraEngine)
SimpleCamera
. If you would like to customize how the camera is
positioned, create a new Camera
and set it here.cameraEngine
- camera engine used to configure camera position while routing@NonNull public Camera getCameraEngine()
SimpleCamera
is used.public void setSnapEngine(@NonNull Snap snapEngine)
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.
snapEngine
- a custom implementation of the Snap
classSnap
public Snap getSnapEngine()
Snap
public void setOffRouteEngine(@NonNull OffRoute offRouteEngine)
The engine can be changed at anytime, even during a navigation session.
offRouteEngine
- a custom implementation of the OffRoute
classOffRoute
@NonNull public OffRoute getOffRouteEngine()
OffRoute
public void setFasterRouteEngine(@NonNull FasterRoute fasterRouteEngine)
The engine can be changed at anytime, even during a navigation session.
fasterRouteEngine
- a custom implementation of the FasterRoute
classFasterRoute
@NonNull public FasterRoute getFasterRouteEngine()
FasterRoute
public String recordFeedback(String feedbackType, String description, String source)
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.
feedbackType
- from list of set feedback typesdescription
- an option description to provide more detail about the feedbacksource
- either from the drop-in UI or a reroutepublic void updateFeedback(String feedbackId, String feedbackType, String description, String screenshot)
recordFeedback(String, String, String)
.
Uses a feedback ID to find the correct event and then adjusts the feedbackType and description.
feedbackId
- generated from recordFeedback(String, String, String)
feedbackType
- from list of set feedback typesdescription
- an optional description to provide more detail about the feedbackscreenshot
- an optional encoded screenshot to provide more detail about the feedbackpublic void cancelFeedback(String feedbackId)
recordFeedback(String, String, String)
.
Uses a feedback ID to find the correct event and then cancels it (will no longer be recorded).
feedbackId
- generated from recordFeedback(String, String, String)
public boolean updateRouteLegIndex(int legIndex)
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()
.
legIndex
- to be setpublic String retrieveHistory()
public void toggleHistory(boolean isEnabled)
public String retrieveSsmlAnnouncementInstruction(int index)
public void onServiceConnected(ComponentName name, IBinder service)
onServiceConnected
in interface ServiceConnection
public void onServiceDisconnected(ComponentName name)
onServiceDisconnected
in interface ServiceConnection
© 2019 Mapbox. All rights reserved.