AI-generated Key Takeaways

outlined_flag

• The turn-by-turn data feed provides navigation guidance information (icons, road names, distances, and time) for devices with limited display capabilities.

• Implement an event listener for thedidChangeNavInfo event to access trip and step information and provide turn-by-turn navigation updates to users.

• Monitor the navigation state (enroute, rerouting, stopped) using thenavState property ofGMSNavigationNavInfo to display appropriate guidance and handle navigation changes.

• Utilize lane guidance information fromGMSNavigationLane andGMSNavigationLaneDirection to visualize recommended lane directions for users.

• Create and use maneuver icons based onGMSNavigationManeuver values or leverage the SDK's built-in icon generation for clear visual turn instructions.

A turn-by-turn data feed provides navigation-only information to devices notdesigned for map-based navigation guidance. It provides upcoming maneuvers withelements you supply:

• icons (left, right, U-turn)
• turn numbers in roundabouts
• road names
• estimated distances and time to the next navigation step or finaldestination

You can use the turn-by-turn feed to create experiences where the fullNavigation SDK UI is not appropriate, such as for small screen displays. Forexample, you might use this for two-wheeled vehicle riders, where you canproject navigation-only guidance to help them reach their destinations fasterand more confidently with minimal distractions.

Essential navigation display elements

The primary fields for each navigation step are the full road name,maneuver, and total distance of the step, which are available inGMSNavigationStepInfo.

For the overall trip, you may want to display the remaining time and distanceto the current step or to the destination, all of which are available inGMSNavigationNavInfo.The image to the right shows an example of these essential navigation elements.

Set up an event listener

To use navigation-only data, you have to implement an event listener for thedidChangeNavInfo event. Within the event listener, access trip andstep information to provide turn by turn navigation to your users.

To implement event handlers, the view controller of the map must implement theGMSNavigatorListenerprotocol. For detailed information on handling events in theNavigation SDK for iOS, seeListen for navigation events.

Handling thedidChangeNavInfo event

Create a listener for thedidChangeNavInfo event to add turn-by-turn supportto your app. In the event listener, use the following classes and enums tocontrol turn-by-turn navigation:

• GMSNavigationNavInfo— Class defining information about the state of navigation.

• GMSNavigationStepInfo— Class defining information about a single step along a navigationroute.

• GMSNavigationNavState— Enum defining the current state of a navigation, such as enroute,rerouting, or stopped.

• GMSNavigationDrivingSide— Enum defining whether this step is on a drive-on-right ordrive-on-left route.

• GMSNavigationManeuver— Enum defining the navigation action to take, such as turn left orturn right.

Shown below are example event listeners for thedidChangeNavInfo event:

// ViewController.swiftclassSomeViewController:UIViewController{...mapView.navigator?.add(self);...}extensionSomeViewController:GMSNavigatorListener{funcnavigator(_navigator:GMSNavigator,didUpdateNavInfonavInfo:GMSNavigationNavInfo){// Get the current step informationifnavInfo.navState==.enroute{ifletcurrentStep=navInfo.currentStep{...roadNameLabel.text=currentStep.simpleRoadName...}}}}

// ViewController.h@interfaceSomeViewController()<GMSNavigatorListener>@end// ViewController.m@implementationSomeViewController// Some initialization code....{...[_mapView.navigatoraddListener:self];...}#pragma mark GMSNavigatorListener  -(void)navigator:(GMSNavigator*)navigatordidUpdateNavInfo:(GMSNavigationNavInfo*)navInfo{// Get the current step informationif(navInfo.navState==GMSNavigationNavStateEnroute){GMSNavigationStepInfo*currentStep=navInfo.currentStep;if(currentStep){...roadNameLabel.text=currentStep.simpleRoadName;...}}...}

Navigation states

UsenavState property ofGMSNavigationNavInfoto get the current state of navigation, which is one of the following:

• Enroute - TheGMSNavigationNavStateEnroute state means that guidednavigation is active and the user is on the provided route.Information about the current upcoming maneuver step is available.

• Rerouting -GMSNavigationNavStateRerouting means that navigation is inprogress, but the navigator is looking for a new route. The upcomingmaneuver step is not available, because there's no new route yet.

• Stopped -GMSNavigationNavStateStopped means navigation has ended. Forexample, navigation stops when the user exits navigation in the app. In thesample app, aGMSNavigationNavStateStopped state clears the navigationinfo display to prevent lingering step instructions from being displayed.

Lane guidance

The Navigation SDK represents lanes in the navigation turn card asGMSNavigationLane andGMSNavigationLaneDirection data objects. AGMSNavigationLane object represents a specific lane during navigation and hasa list ofGMSNavigationLaneDirection objects that describe all the turns thatcan be made from this lane.

The recommended direction a driver should take in a lane is marked using therecommended field.

Lane guidance example

The following snippet illustrates the data representation of the lanes displayedin the preceding screenshot.

// Lane 1GMSNavigationLaneDirections=[{/*GMSNavigationLaneShape=*/GMSNavigationLaneShapeNormalLeft,/*recommended=*/true}]// Lane 2GMSNavigationLaneDirections=[{/*GMSNavigationLaneShape=*/GMSNavigationLaneShapeNormalLeft,/*recommended=*/true}]// Lane 3GMSNavigationLaneDirections=[{/*GMSNavigationLaneShape=*/GMSNavigationLaneShapeStraight,/*recommended=*/false}]// Lane 4GMSNavigationLaneDirections=[{/*GMSNavigationLaneShape=*/GMSNavigationLaneShapeStraight,/*recommended=*/false},{/*GMSNavigationLaneShape=*/GMSNavigationLaneShapeNormalRight,/*recommended=*/false}]

Lane guidance images

The Navigation SDK supports generation of lane images for each navigation stepas conveyed byGMSNavigationStepInfo. These icons fitCarPlay's image sizingguidance.

letcurrentStepInfo=navInfo.currentStepletoptions=GMSNavigationStepImageOptions()options.maneuverImageSize=.square96options.screenMetrics=UIScreen.mainScreenletmaneuverImage=currentStepinfo.maneuverImage(options:options)

GMSNavigationStepInfo*stepInfo=navInfo.currentStep;GMSNavigationStepImageOptions*options=[[GMSNavigationStepImageOptionsalloc]init];options.maneuverImageSize=GMSNavigationManeuverImageSizeSquare96;options.screenMetrics=UIScreen.mainScreen;UIImage*maneuverImage=[stepInfomaneuverImageWithOptions:options];

Creating icons for maneuvers

TheGMSNavigationManeuverenum defines each possible maneuver that could occur while navigating, and youcan get the maneuver for a given step from themaneuver property ofGMSNavigationStepInfo.

You must create maneuver icons and pair them with their associated maneuvers.For some maneuvers, you can set up a one-to-one mapping to an icon, such asGMSNavigationManeuverDestinationLeft andGMSNavigationManeuverDestinationRight. However, since some maneuvers sharecharacteristics with other maneuvers, you might want to map more than onemaneuver to a single icon. For exampleGMSNavigationManeuverTurnLeft andGMSNavigationManeuverOnRampLeft could both map to the left turn icon.

Some maneuvers contain an additional "Clockwise" or "CounterClockwise" label,which the SDK determines based on the driving side of a country. For example,in countries where driving is on the left side of the road, drivers take aroundabout or U-turn in a clockwise direction, whereas right-side-of-the-roadcountries go counterclockwise. The Navigation SDK detectswhether a maneuver occurs in left- or right-side traffic and outputsthe appropriate maneuver. Therefore, your maneuver icon may be differentfor a clockwise versus a counterclockwise maneuver.

Expand to see examples icons for different maneuvers

Sample Icon	Turn-By-Turn Maneuvers
	DEPART UNKNOWN
	STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
	TURN_RIGHT ON_RAMP_RIGHT
	TURN_LEFT ON_RAMP_LEFT
	TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
	TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
	TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
	TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
	TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
	TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
	ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_RIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
	ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
	ROUNDABOUT_STRAIGHT_CLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
	ROUNDABOUT_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_LEFT_CLOCKWISE
	ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
	ROUNDABOUT_SHARP_LEFT_CLOCKWISE
	ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
	ROUNDABOUT_U_TURN_CLOCKWISE
	ROUNDABOUT_COUNTERCLOCKWISE
	ROUNDABOUT_CLOCKWISE
	ROUNDABOUT_EXIT_COUNTERCLOCKWISE
	ROUNDABOUT_EXIT_CLOCKWISE
	MERGE_RIGHT OFF_RAMP_RIGHT
	MERGE_LEFT OFF_RAMP_LEFT
	FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
	FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
	MERGE_UNSPECIFIED
	DESTINATION
	DESTINATION_RIGHT
	DESTINATION_LEFT
	FERRY_BOAT
	FERRY_TRAIN

Use generated icons

The Navigation SDK supports generation of maneuver icons for a givenGMSNavigationStepInfo. These icons fitCarPlay image sizingguidance.

letcurrentStepInfo=navInfo.currentStepletoptions=GMSNavigationStepImageOptions()options.maneuverImageSize=.square96options.screenMetrics=UIScreen.mainScreenletmaneuverImage=currentStepinfo.maneuverImage(options:options)

GMSNavigationStepInfo*stepInfo=navInfo.currentStep;GMSNavigationStepImageOptions*options=[[GMSNavigationStepImageOptionsalloc]init];options.maneuverImageSize=GMSNavigationManeuverImageSizeSquare96;options.screenMetrics=UIScreen.mainScreen;UIImage*maneuverImage=[stepInfomaneuverImageWithOptions:options];