Adopt named arrival instructions from Directions API

[1ec5]

Spoken instructions for an arrive step should include the name of the waypoint. In typical SDK usage, the developer supplies a Waypoint.name that’s either the name of a point of interest or an address. The user would find it very useful to hear the address when arriving at the destination. Arriving at a named waypoint is a basic use case, so the SDK should handle it without requiring any developer intervention.

Currently, the arrival instructions come from the Directions API, like any other instruction. In the absence of Directions API support for this feature, the SDK would need to ignore the arrive step’s SpokenInstruction objects in favor of its own homegrown instruction strings. For localization, we have two options:

• Translate the arrival instructions as part of this SDK’s Transifex project. The strings will be somewhat redundant with OSRM Text Instructions. We won’t be able to take advantage of the grammar support in OSRM Text Instructions, which would be very unfortunate for Russian, because declination is required for the waypoint name.
• Add named waypoint strings to OSRM Text Instructions and depend on OSRM Text Instructions for Swift once again. Russian declination would need to be fixed in Apply grammar rules to token replacement values Project-OSRM/osrm-text-instructions.swift#49.

/cc @mapbox/navigation-ios @mapbox/guidance

[1ec5]

Note that it would be insufficient to append the waypoint name to the server-generated instruction, for the following reasons:

• This SDK sends an SSML string to the Voice API. We lack access to an XML parser, so we can’t reliably modify the SSML string in any way, not even to append to the sentence.
• If OSRM knows which side of the street the destination is on, the instruction includes the phrase “on the left/right”; the waypoint name would have to come before that phrase.
• Appending the waypoint name to the instruction would be ungrammatical in some of the languages we support (and some major languages we don’t yet support, like Japanese).

[bsudekum]

@1ec5 would this require some server involvement? IE the response would change to

"voiceInstruction": "You have arrived at {replace text here}."

[1ec5]

would this require some server involvement?

That would be a sensible alternative to what’s proposed above. However, if the Directions API doesn’t add any support for this option, then we’d need to build some of our own voice instructions on the client side, essentially.

[akitchen]

Server will name the waypoint in the banner, but MapboxDirections.swift will eventually need to change.

[brsbl-zz]

This should no longer be blocked upstream

[1ec5]

Next steps:

• MapboxDirections.swift specifies the waypoint_names parameter: DirectionsOptions should include waypoint names in URL parameter mapbox-directions-swift#271
• Remove this special case for arrival banners:

  mapbox-navigation-ios/MapboxNavigation/StepsViewController.swift

  Lines 203 to 207 in d7f8c4d

  	func instructionForArrivalInstruction(text: String?) -> VisualInstruction {
  	let component = VisualInstructionComponent(type: .text, text: text, imageURL: nil, abbreviation: nil, abbreviationPriority: NSNotFound)
  	let instruction = VisualInstruction(text: nil, maneuverType: .arrive, maneuverDirection: .none, textComponents: [component])
  	return instruction
  	}

[vincethecoder]

Update:
Per conversation with @1ec5, here is an update for this ticket requirement:

The DirectionsOptions.params getter needs to add another URLQueryItem to the array based on mapping all the waypoints to their names.

[1ec5]

☝️ will happen as part of mapbox/mapbox-directions-swift#271.

[vincethecoder]

• MapboxDirections.swift specifies the waypoint_names parameter:
  PR reference - New query parameter, waypoint names added to directions options. mapbox-directions-swift#273

[vincethecoder]

• Remove this special case for arrival banners:
  func instructionForArrivalInstruction(text: String?) -> VisualInstruction
  PR reference: Changes to adopt the named arrival instructions from Directions API #1406