Milestones

Navigation milestones inside the SDK provide a powerful way to give your user instructions or get cues to hide or show custom UI at defined locations along their route. You can create custom milestones that fit your particular app needs.

Default Milestones

VoiceInstructionMilestone

The VoiceInstructionMilestone will fire every time it's time to announce an instruction along a given DirectionsRoute. This milestone provides a plain text instruction with VoiceInstructionMilestone#getInstruction as well as a SSML version of the same instruction with VoiceInstructionMilestone#getSsmlAnnouncement.
SSML stands for Speech Synthesis Markup Language and is designed to work with AWS Polly.

BannerInstructionMilestone

The BannerInstructionMilestone will fire every time textual instructions should be updated, most of the time in the format of a "banner" view on the top of the screen. This milestone provides a BannerInstructions object for the given point along the route. This object contains text and URLs for shield images that can be displayed on screen at the time the milestone fires.

Milestone event listener

All the milestones use the onMilestoneEvent callback to alert when they get triggered. If you want to make use of the milestones API, you will want to attach a MilestoneEventListener inside your app. When all the milestone trigger conditions are true, the callback is invoked and provides you with the latest routeProgress along with the milestone's corresponding String instruction and the Milestone itself that was triggered. You can use your text-to-speech engine of choice and have it consume the instruction.

@Override
public void onMilestoneEvent(RouteProgress routeProgress, String instruction, Milestone milestone) {
exampleInstructionPlayer.play(instruction);
}

Building a custom milestone

Milestones bring flexibility to your app and how it handles navigation events. Creating a milestone is done in just a few steps. First, choose how frequently you'd like the milestone to be triggered. Two options are currently provided, StepMilestone, which is triggered each step in the route and RouteMilestone, which will only get trigger once during the entire route. You can also implement your own behavior for triggers by extending the Milestone class. Give the milestone a unique identifier which can be used to determine which milestone triggered the onMilestoneEvent callback. Set the triggers using any combination of the properties shown in the table below. It is important to note that trigger properties have different corresponding variable types that need to be accounted for when setting the milestone up. Lastly, build the milestone and pass it into the MapboxNavigation instance using addMilestone().

The snippet of code provided below shows the creation of a RouteMilestone with two conditions, both of which need to be true for the milestone to be triggered. Since it is a RouteMilestone, the milestone event only occurs once. The trigger statement can be read as: both the step index must be less than 3 and the current step total distance must be greater than 200 meters for the milestone to be triggered.

navigation.addOffRouteListener(new OffRouteListener() {
@Override
public void userOffRoute(Location location) {
 
	navigation.addMilestone(new RouteMilestone.Builder()
	  .setIdentifier("begin-route-milestone")
	  .setTrigger(
	    Trigger.all(
		      Trigger.lt(TriggerProperty.STEP_INDEX, 3), Trigger.gt(TriggerProperty.STEP_DISTANCE_TOTAL_METERS, 200))).build()
);

Trigger conditions

Besides the triggers already mentioned above, the SDK comes equipped to handle pretty much any case you'd like to build. The table below shows all the conditions currently offered inside the SDK and whether it is a compound statement or a simple statement.

Trigger properties

Below are the available trigger properties that can be used along with the conditions above to filter when a milestone should be triggered. Note that instead of the boolean types using the primitive type true or false, the TriggerProperty class uses custom boolean values for the triggers.

We are actively adding more and more trigger properties every day while we continue building out the milestones API. Please open an issue on GitHub if you feel a trigger property is missing and include the use-case.

Custom instructions

You'll see in the next section about the milestone event listener that the callback provides a String instruction value. During the milestone creation process, you can add the logic that generates this instruction. Begin by creating a new Instruction object which will provide an override method, buildInstruction, which provides a RouteProgress object for producing the instructions string. With the provided route progress, you can add information such as distance and duration remaining until the next maneuver. Once the Instruction is initialized, you will need to give it to the milestone using setInstruction. The example below shows how to add the directions API instruction with no modifications as the milestone instruction.

Instruction myInstruction = new Instruction() {
@Override
public String buildInstruction(RouteProgress routeProgress) {
return routeProgress.currentLegProgress().upComingStep().maneuver().instruction();
}
};