Follow this guide to plot a route within your app to a single destination, using the Navigation SDK for iOS.
Overview
- Integrate the Navigation SDK into your app, as described in the Set up your project section.
- Configure a
GMSMapView
. - Prompt the user to accept the terms and conditions, and authorize location services and background notifications.
- Create an array containing one or more destinations.
Define a
GMSNavigator
to control turn-by-turn navigation.- Add destinations using
setDestinations
. - Set
isGuidanceActive
totrue
to start navigation. - Use
simulateLocationsAlongExistingRoute
to simulate the progress of the vehicle along the route, for testing, debugging, and demonstrating your app.
- Add destinations using
See the code
Prompt the user for the necessary authorizations
Before using the Navigation SDK, the user must agree to the terms and conditions, and authorize the use of location services, which is required for navigation. If your app will run in the background, it must also prompt the user to authorize guidance alert notifications. This section shows how to display the required authorization prompts.
Authorize location services
The Navigation SDK uses location services, which requires user authorization. To enable location services and display the authorization dialog, take these steps:
- Add the
NSLocationAlwaysUsageDescription
key toInfo.plist
. For the value, add a short explanation of why your app requires location services. For example: "This app needs permission to use location services for turn-by-turn navigation."
To display the authorization dialog, call
requestAlwaysAuthorization()
of the location manager instance.
Swift
self.locationManager.requestAlwaysAuthorization()
Objective-C
[_locationManager requestAlwaysAuthorization];
Authorize alert notifications for background guidance
The Navigation SDK needs user permission to provide alert notifications when the app is running in the background. Add the following code to prompt the user for permission to display these notifications:
Swift
UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
granted, error in
// Handle denied authorization to display notifications.
if !granted || error != nil {
print("User rejected request to display notifications.")
}
}
Objective-C
// Request authorization for alert notifications.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
completionHandler:
^(
BOOL granted,
NSError *_Nullable error) {
if (!error && granted) {
NSLog(@"iOS Notification Permission: newly Granted");
} else {
NSLog(@"iOS Notification Permission: Failed or Denied");
}
}];
Accept the terms and conditions
Use the following code to show the terms and conditions dialog, and enable navigation when the user accepts the terms. Note that this example includes the code for location services and guidance alert notifications (shown previously).
Swift
let termsAndConditionsOptions = GMSNavigationTermsAndConditionsOptions(companyName: "Ride Sharing Co.")
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
with: termsAndConditionsOptions) { termsAccepted in
if termsAccepted {
// Enable navigation if the user accepts the terms.
self.mapView.isNavigationEnabled = true
self.mapView.settings.compassButton = true
// Request authorization to use location services.
self.locationManager.requestAlwaysAuthorization()
// Request authorization for alert notifications which deliver guidance instructions
// in the background.
UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
granted, error in
// Handle rejection of notification authorization.
if !granted || error != nil {
print("Authorization to deliver notifications was rejected.")
}
}
} else {
// Handle rejection of terms and conditions.
}
}
Objective-C
GMSNavigationTermsAndConditionsOptions *termsAndConditionsOptions = [[GMSNavigationTermsAndConditionsOptions alloc] initWithCompanyName:@"Ride Sharing Co."];
[GMSNavigationServices
showTermsAndConditionsDialogIfNeededWithOptions:termsAndConditionsOptions
callback:^(BOOL termsAccepted) {
if (termsAccepted) {
// Enable navigation if the user accepts the terms.
_mapView.navigationEnabled = YES;
_mapView.settings.compassButton = YES;
// Request authorization to use the current device location.
[_locationManager requestAlwaysAuthorization];
// Request authorization for alert notifications which deliver guidance instructions
// in the background.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
completionHandler:
^(
BOOL granted,
NSError *_Nullable error) {
if (!error && granted) {
NSLog(@"iOS Notification Permission: newly Granted");
} else {
NSLog(@"iOS Notification Permission: Failed or Denied");
}
}];
} else {
// Handle rejection of the terms and conditions.
}
}];
Create a route and start guidance
To plot a route, call the Navigator’s setDestinations()
method with an array
containing one or more destinations (GMSNavigationWaypoint
) to visit. If successfully
computed, the route is shown on the map. To start guidance along the route,
beginning with the first destination, set isGuidanceActive
to true
in the
callback.
The following example shows:
- Creating a new route with two destinations.
- Starting guidance.
- Enabling background guidance notifications.
- Simulating travel along the route (optional).
- Setting the camera mode to "follow" (optional).
Swift
func startNav() {
var destinations = [GMSNavigationWaypoint]()
destinations.append(GMSNavigationWaypoint.init(placeID: "ChIJnUYTpNASkFQR_gSty5kyoUk",
title: "PCC Natural Market")!)
destinations.append(GMSNavigationWaypoint.init(placeID:"ChIJJ326ROcSkFQRBfUzOL2DSbo",
title:"Marina Park")!)
mapView.navigator?.setDestinations(destinations) { routeStatus in
self.mapView.navigator?.isGuidanceActive = true
self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
self.mapView.cameraMode = .following
}
}
Objective-C
- (void)startNav {
NSArray<GMSNavigationWaypoint *> *destinations =
@[[[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJnUYTpNASkFQR_gSty5kyoUk"
title:@"PCC Natural Market"],
[[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJJ326ROcSkFQRBfUzOL2DSbo"
title:@"Marina Park"]];
[_mapView.navigator setDestinations:destinations
callback:^(GMSRouteStatus routeStatus){
[_mapView.locationSimulator simulateLocationsAlongExistingRoute];
_mapView.navigator.guidanceActive = YES;
_mapView.cameraMode = GMSNavigationCameraModeFollowing;
}];
}
To learn about Place IDs please refer to Place IDs.
Set travel mode
Travel mode determines which type of route will be fetched, and the way that the user's course is determined. You can set one of four travel modes for a route: driving, cycling, walking, and taxi. In driving and taxi mode, the user's course is based on the direction of travel; in cycling and walking mode the course is represented by the direction the device is facing.
Set the travelMode
property of the map view, as shown in the following example:
Swift
self.mapView.travelMode = .cycling
Objective-C
_mapView.travelMode = GMSNavigationTravelModeCycling;
Set roads to avoid
Use the avoidsHighways
and avoidsTolls
BOOL
properties to avoid
highways and/or toll roads along a route.
Swift
self.mapView.navigator?.avoidsTolls = true
Objective-C
_mapView.navigator.avoidsTolls = YES;
PlaceID finder
You can use the PlaceID Finder
to find place IDs to use for route destinations. Add a destination from a placeID
with GMSNavigationWaypoint
.
Floating text
You can add floating text anywhere in your app, as long as the Google attribution isn't covered. The Navigation SDK doesn't support anchoring the text to a latitude/longitude on the map, or to a label. For more information, see Info windows.