GMSNavigator Class Reference

GMSNavigator Class Reference

Overview

This is the main class of the Google Navigation SDK for iOS and provides methods for controlling navigation to a destination and accessing route and progress information.

This class does not support subclassing.

This class is not thread-safe. All methods must be called from the main thread.

Public Member Functions

(void) - addListener:
 Adds a listener.
(BOOL) - removeListener:
 Removes a listener.
(void) - setDestinations:callback:
 Sets multiple destinations for navigation, overriding any previously set destinations.
(void) - setDestinations:routingOptions:callback:
 Sets multiple destinations for navigation, overriding any previously set destinations.
(void) - setDestinations:routeToken:callback:
 Sets multiple destinations for navigation, using a route token to navigate on a precomputed route.
(void) - getRouteInfoForDestination:withRoutingOptions:callback:
 Returns route information based on the routing strategy: default best or shorter route.
(nullable GMSNavigationWaypoint *) - continueToNextDestination
 Deprecated.
(void) - clearDestinations
 Clears all previously set destinations and removes any calculated routes from the map.
(NSTimeInterval) - timeToWaypoint:
 Returns the estimated time to the given waypoint, or CLTimeIntervalMax if the waypoint is not part of the current route.
(CLLocationDistance) - distanceToWaypoint:
 Returns the estimated distance to the given waypoint, or CLLocationDistanceMax if the waypoint is not part of the current route.
(void) - setTransactionIDs:errorHandler:
 Sets and logs to the server the ongoing transaction IDs that apply to the navigation events during the current navigation session.

Properties

BOOL avoidsHighways
 Whether to avoid highways when generating routes to destinations.
BOOL avoidsTolls
 Whether to avoid toll roads when generating routes to destinations.
BOOL avoidsFerries
 Whether to avoid ferries when generating routes to destinations.
GMSNavigationLicensePlateRestrictionlicensePlateRestriction
 Set license plate restriction with current driver's last digit of license plate and country code.
BOOL guidanceActive
 Whether turn-by-turn guidance is currently enabled.
BOOL stopGuidanceAtArrival
 Whether guidance should automatically stop when -navigator:didArriveAtWaypoint: is called.
NSTimeInterval timeUpdateThreshold
 The minimum change in estimated time to the next destination that will trigger the navigator:didUpdateRemainingTime: method to be called.
CLLocationDistance distanceUpdateThreshold
 The minimum change in estimated distance to the next destination that will trigger the navigator:didUpdateRemainingDistance: method to be called.
NSTimeInterval timeToNextDestination
 Returns the estimated time to the next destination.
CLLocationDistance distanceToNextDestination
 Returns the estimated distance to the next destination.
GMSNavigationDelayCategory delayCategoryToNextDestination
 Returns the delay category to the next destination.
GMSRouteLegcurrentRouteLeg
 The current leg of the journey.
NSArray< GMSRouteLeg * > * routeLegs
 An array of route legs where each leg corresponds to a destination that was set.
GMSPathtraveledPath
 The path that the user has traveled in the most recent guidance session, defined as the last time guidanceActive was set to YES.
GMSNavigationVoiceGuidance voiceGuidance
 Determines whether voice guidance should be enabled for traffic and turn-by-turn alerts.
GMSVoiceGuidanceAudioDeviceType audioDeviceType
 Determines what audio devices voice guidance may be played through.
BOOL vibrationEnabled
 Determines whether the device should also vibrate when voice alerts are played.
BOOL sendsBackgroundNotifications
 Determines whether UILocalNotifications containing guidance information will be presented when the app is in the background.
GMSNavigationLightingMode suggestedLightingMode
 The suggested lighting mode, based on the time of day and device location.
BOOL shouldDisplayPrompts
 Determines whether prompts for traffic, better routes and incidents should be displayed.
GMSNavigationSpeedAlertOptionsspeedAlertOptions
 GMSNavigationSpeedAlertOptions for customizing the triggering thresholds for GMSNavigationSpeedAlertSeverity.

(Note that these are not member functions.)

typedef void(^ GMSRouteStatusCallback )(GMSRouteStatus routeStatus)
 Called when a route from the device's location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.
typedef void(^ GMSRouteInfoCallback )(GMSNavigationRouteInfo *_Nullable routeInfo)
 Called when the route information (ETA and distance) to the provided waypoint is calculated.
typedef void(^ GMSNavigationTransactionIDErrorHandler )(NSError *error)
 Called if setting transaction IDs through the setTransactionIDs fails.

Member Function Documentation

- (void) addListener: (id< GMSNavigatorListener >)  listener

Adds a listener.

The listener is held with a weak reference.

Parameters:
listenerAn object conforming to the GMSNavigatorListener protocol.
- (BOOL) removeListener: (id< GMSNavigatorListener >)  listener

Removes a listener.

Parameters:
listenerAn object conforming to the GMSNavigatorListener protocol.
Returns:
Returns YES if the listener was removed. Returns NO if the object was not a listener.
- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *)  destinations
callback: (GMSRouteStatusCallback callback 

Sets multiple destinations for navigation, overriding any previously set destinations.

The provided callback will be called with GMSRouteStatusOK if a route is found from the device's location to the given destination. If a new destination is set before a route is found, then the request will be canceled, and the callback will be called with GMSRouteStatusCanceled. If a route cannot be found for any other reason, the callback will be called with an appropriate error status.

The callback will always be dispatched asynchronously on the main queue.

- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *)  destinations
routingOptions: (GMSNavigationRoutingOptions *)  routingOptions
callback: (GMSRouteStatusCallback callback 

Sets multiple destinations for navigation, overriding any previously set destinations.

The returned routes are calculated using routing options.

Parameters:
destinationsAn array of destination waypoints.
routingOptionsThe options that influence routing logic (routing strategy).
callbackCalled when a route from the consumer’s location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.
- (void) setDestinations: (NSArray< GMSNavigationWaypoint * > *)  destinations
routeToken: (NSString *)  routeToken
callback: (GMSRouteStatusCallback callback 

Sets multiple destinations for navigation, using a route token to navigate on a precomputed route.

Routes will be the same, modulo changes to the driver starting location and to road/traffic conditions. Re-routes will still occur based on the routing options encoded in the token.

Only GMSNavigationTravelModeDriving and GMSNavigationTravelModeTwoWheeler are supported when you use the route token to start a navigation session. Configure the travel mode by setting travelMode. The call will fail if the current travel mode is unsupported, and a GMSRouteStatusTravelModeUnsupported will be returned in the callback.

Parameters:
destinationsAn array of destination waypoints, should be the same as the destinations given to RoutesPreferred API to get the route token.
routeTokenA route token string returned by RoutesPreferred API. Routing options specified in RoutesPreferred API are encoded in this route token, and will be used to regenerate the precomputed route or a new route when reroute happens.
callbackCalled when a route from the consumer's location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.
- (void) getRouteInfoForDestination: (GMSNavigationWaypoint *)  destination
withRoutingOptions: (GMSNavigationRoutingOptions *)  routingOptions
callback: (GMSRouteInfoCallback callback 

Returns route information based on the routing strategy: default best or shorter route.

This method is only available to Mobility Services customers who are billed by Google on a per-transaction basis. Returns a `nil` value if the project lacks permission to call this API.

Parameters:
destinationThe destination waypoint.
routingOptionsThe options used to fetch the route info. The routing strategy and alternate routes strategy are ignored since this method returns the route information for all routing strategies.
callbackThe callback called when routes information are received.

Deprecated.

Call one of the -setDestinations:... methods with the new list of destinations instead.

Pops the first destination from the current list of destinations. Following this call, guidance will be toward the next destination, if any.

Returns:
the waypoint guidance is now heading towards, or nil if there are no more waypoints left.
Note:
This is deprecated. Use one of the -setDestinations:... methods instead.

Clears all previously set destinations and removes any calculated routes from the map.

If guidance is active, this will automatically stop it.

- (NSTimeInterval) timeToWaypoint: (GMSNavigationWaypoint *)  waypoint

Returns the estimated time to the given waypoint, or CLTimeIntervalMax if the waypoint is not part of the current route.

This is updated based on the current device position while guidance is active.

Returns CLTimeIntervalMax if the provided waypoint is not a destination in the current route.

- (CLLocationDistance) distanceToWaypoint: (GMSNavigationWaypoint *)  waypoint

Returns the estimated distance to the given waypoint, or CLLocationDistanceMax if the waypoint is not part of the current route.

This will be updated based on the current device position whilst guidance is active.

Returns CLLocationDistanceMax if the provided waypoint is not a destination in the current route.

- (void) setTransactionIDs: (NSArray< NSString * > *)  transactionIDs
errorHandler: (nullable GMSNavigationTransactionIDErrorHandler errorHandler 

Sets and logs to the server the ongoing transaction IDs that apply to the navigation events during the current navigation session.

Transaction IDs will be cleared at the end of the navigation session. This method is only available to Mobility Services customers who are billed by Google on a per-transaction basis. Returns a `nil` value if the project lacks permission to call this API.

Parameters:
transactionIDsThe transaction IDs that apply to the current navigation session. The transaction ID must be unique for each billable transaction. An individual transaction ID must contain at least one and at most 64 characters. The list can be empty when a transaction has ended (but the session is still ongoing).
errorHandlerA block that will be invoked asynchronously on the main thread if an error occurs when the transaction IDs are invalid.

- (typedef void(^ GMSRouteStatusCallback)(GMSRouteStatus routeStatus)) [related]

Called when a route from the device's location to the provided destination(s) is found, or fails to be found for a reason indicated by the RouteStatus.

- (typedef void(^ GMSRouteInfoCallback)(GMSNavigationRouteInfo *_Nullable routeInfo)) [related]

Called when the route information (ETA and distance) to the provided waypoint is calculated.

Parameters:
routeInfoThe route information to the given destination. Will be nil if the calculation fails.
- (typedef void(^ GMSNavigationTransactionIDErrorHandler)(NSError *error)) [related]

Called if setting transaction IDs through the setTransactionIDs fails.

Refer documentation for the API for more details.


Property Documentation

- (BOOL) avoidsHighways [read, write, assign]

Whether to avoid highways when generating routes to destinations.

Defaults to NO.

- (BOOL) avoidsTolls [read, write, assign]

Whether to avoid toll roads when generating routes to destinations.

Defaults to NO.

- (BOOL) avoidsFerries [read, write, assign]

Whether to avoid ferries when generating routes to destinations.

Defaults to YES.

Set license plate restriction with current driver's last digit of license plate and country code.

This allows us to route around certain types of road restrictions which are based on license plate number. This will only apply to setDestinations calls made after this value is set. Ideally you'd set this immediately after getting the navigator.

Set to nil if there is no license plate restriction. Default to nil.

- (BOOL) guidanceActive [read, write, assign]

Whether turn-by-turn guidance is currently enabled.

If guidanceActive is YES, but no route is currently available then guidance will start when a route becomes available. This property will be set to NO if clearDestinations is called, or we arrive at a waypoint.

- (BOOL) stopGuidanceAtArrival [read, write, assign]

Whether guidance should automatically stop when -navigator:didArriveAtWaypoint: is called.

When NO, the navigation header and footer will continue to be shown after arrival. The navigation header will continue to show the final guidance step and the navigation footer will continue to update the remaining time and distance until a time/distance of 0 is reached. Additionally, -navigator:didUpdateRemainingTime and -navigator:didUpdateRemainingDistance updates will continue. Explicitly set guidanceActive to NO to stop guidance and remaining time/distance updates.

When YES, guidanceActive will automatically be set to NO upon arrival.

Defaults to YES.

- (NSTimeInterval) timeUpdateThreshold [read, write, assign]

The minimum change in estimated time to the next destination that will trigger the navigator:didUpdateRemainingTime: method to be called.

If this is set to NSTimeIntervalMax, then time update callbacks will be disabled. If this is set to a negative value, then the default threshold of one second will be used. Defaults to one second.

Note:
This value is ignored if no listeners implement navigator:didUpdateRemainingTime:.
- (CLLocationDistance) distanceUpdateThreshold [read, write, assign]

The minimum change in estimated distance to the next destination that will trigger the navigator:didUpdateRemainingDistance: method to be called.

If this is set to CLLocationDistanceMax, then distance update callbacks will be disabled. If this is set to a negative value, then the default threshold of one meter will be used. Defaults to one meter.

Note:
This value is ignored if no listeners implement navigator:didUpdateRemainingDistance:.
- (NSTimeInterval) timeToNextDestination [read, assign]

Returns the estimated time to the next destination.

This will be updated based on the current device position whilst guidance is active.

Returns CLTimeIntervalMax if no route is available.

- (CLLocationDistance) distanceToNextDestination [read, assign]

Returns the estimated distance to the next destination.

This will be updated based on the current device position whilst guidance is active.

Returns CLLocationDistanceMax if no route is available.

- (GMSNavigationDelayCategory) delayCategoryToNextDestination [read, assign]

Returns the delay category to the next destination.

This will be updated based on the current device position whilst guidance is active.

Returns GMSNavigationDelayCategoryNoData if no route is available or traffic data is unavailable.

- (GMSRouteLeg*) currentRouteLeg [read, assign]

The current leg of the journey.

This GMSRouteLeg will have its starting position as the most recent known (road-snapped) position of the device.

- (NSArray<GMSRouteLeg *>*) routeLegs [read, assign]

An array of route legs where each leg corresponds to a destination that was set.

- (GMSPath*) traveledPath [read, assign]

The path that the user has traveled in the most recent guidance session, defined as the last time guidanceActive was set to YES.

The path consists of road-snapped locations returned by the GMSRoadSnappedLocationProvider and simplified to produce line segments.

Note:
The system polls the client for GPS signals to obtain location data. Poor GPS signal can result in further interpolation, which might produce less precise routes. This path is empty if guidance has never started.
- (GMSNavigationVoiceGuidance) voiceGuidance [read, write, assign]

Determines whether voice guidance should be enabled for traffic and turn-by-turn alerts.

Defaults to GMSNavigationVoiceGuidanceAlertsAndGuidance.

Determines what audio devices voice guidance may be played through.

Defaults to GMSVoiceGuidanceAudioDeviceTypeBluetooth.

- (BOOL) vibrationEnabled [read, write, assign]

Determines whether the device should also vibrate when voice alerts are played.

- (BOOL) sendsBackgroundNotifications [read, write, assign]

Determines whether UILocalNotifications containing guidance information will be presented when the app is in the background.

Defaults to YES.

The suggested lighting mode, based on the time of day and device location.

- (BOOL) shouldDisplayPrompts [read, write, assign]

Determines whether prompts for traffic, better routes and incidents should be displayed.

Defaults to YES.

GMSNavigationSpeedAlertOptions for customizing the triggering thresholds for GMSNavigationSpeedAlertSeverity.

You can use this property to customize the speed alert triggering thresholds in percentage for both minor and major alerts. You can also use this method to customize the time based triggering threshold for major speed alert.

By setting nil, you won't receive any speeding feed data, and the NavSDK's default speed alert will display: speed alert shows red text when the speed is more than 5 mph or 10 kph over the speed limit, and shows white text and red background when speeding more than 10 mph or 20kph.