Maneuver instructions
This page uses v1.4.2 of the Mapbox Navigation SDK. A newer version of the SDK is available. Learn about the latest version, v2.19.0, in the Navigation SDK documentation.
Core Navigation tracks the device location and listens for other significant events that are used to trigger visual and spoken maneuver instructions. These include events related to progress along a route, before and after reroutes, arrival at waypoints, and more.
Drop-in UI
The drop-in UI uses logic from Mapbox Core Navigation to trigger a comprehensive system of visual and spoken instructions by default. There are default styling rules for visual instructions and default settings for voice instructions. Instructions can be customized to synchronize your application's behavior with instructions coming from the Mapbox Navigation SDK and customizing the style of visual instructions to fit with your application.
Visual instruction events
By default, visual instructions will be displayed when NavigationServiceDelegate.navigationService(_:didPassVisualInstructionPoint:routeProgress:) is called and Notification.Name.routeControllerDidPassVisualInstructionPoint is posted when the user passes the appropriate point at which to display a visual instruction. A visual instruction point occurs near the beginning of a step. There may be additional visual instruction points along the step as additional information, like turn lanes, become relevant.
Spoken instruction events
By default, spoken instructions will be played when NavigationServiceDelegate.navigationService(_:didPassSpokenInstructionPoint:routeProgress:) is called and Notification.Name.routeControllerDidPassSpokenInstructionPoint is posted when the user passes the appropriate point at which to announce a spoken instruction. A spoken instruction point occurs near the end of a step. There may be additional spoken instruction points, as time allows, at a comfortable distance before the end of the step and near the beginning of the step. A single spoken instruction point may correspond to an instruction about two maneuvers in that are nearby.
Customization in the drop-in UI
For customizing the language used in visual and spoken instructions, see Localization and internationalization.
You can change the appearance of various UI elements. For example, you can customize the bottom banner by passing a ContainerViewController into NavigationOptions(styles:navigationService:voiceController:bottomBanner:).
let customBottomBanner: ContainerViewController = CustomBottomBannerController(delegate: someDelegate)
let navigationOptions = NavigationOptions(bottomBanner: customBottomBanner)
let navigationViewController = NavigationViewController(route: route, routeOptions: routeOptions, navigationOptions: navigationOptions)
For more information on customizing the style of visual instructions, see App styling.
Custom instructions
Visual instructions
You can use VisualInstructionDelegate.label(_:willPresent:as:) to adjust the predefined contents of visual instruction provided by the Directions API, but you cannot trigger an arbitrary message outside the visual instructions that are triggered by default.
func label(_ label: InstructionLabel, willPresent instruction: VisualInstruction, as presented: NSAttributedString) -> NSAttributedString? {
let range = NSRange(location: 0, length: presented.length)
let mutable = NSMutableAttributedString(attributedString: presented)
mutable.mutableString.applyTransform(.latinToKatakana, reverse: false, range: range, updatedRange: nil)
return mutable
}
Spoken instructions
An application can call RouteVoiceController.speak(_:) at any time to interrupt any in-progress spoken instruction with a custom spoken instruction.
func voiceController(_ voiceController: RouteVoiceController, willSpeak instruction: SpokenInstruction, routeProgress: RouteProgress) -> SpokenInstruction? {
return SpokenInstruction(distanceAlongStep: instruction.distanceAlongStep, text: "New Instruction!", ssmlText: "<speak>New Instruction!</speak>")
}
For more information on supported SSML tags see Amazon's SSML Tags Supported by Amazon Polly guide.
Device notifications
The application should import the UserNotifications framework and request authorization to present user notifications before beginning turn-by-turn navigation. If authorized, the Navigation SDK automatically displays user notifications while the screen is locked.