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. | |
GMSNavigationLicensePlateRestriction * | licensePlateRestriction |
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. | |
GMSRouteLeg * | currentRouteLeg |
The current leg of the journey. | |
NSArray< GMSRouteLeg * > * | routeLegs |
An array of route legs where each leg corresponds to a destination that was set. | |
GMSPath * | traveledPath |
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. | |
GMSNavigationSpeedAlertOptions * | speedAlertOptions |
GMSNavigationSpeedAlertOptions for customizing the triggering thresholds for GMSNavigationSpeedAlertSeverity. | |
Related Functions | |
(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:
-
listener An object conforming to the GMSNavigatorListener
protocol.
- (BOOL) removeListener: | (id< GMSNavigatorListener >) | listener |
Removes a listener.
- Parameters:
-
listener An 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:
-
destinations An array of destination waypoints. routingOptions The options that influence routing logic (routing strategy). callback Called 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:
-
destinations An array of destination waypoints, should be the same as the destinations given to RoutesPreferred API to get the route token. routeToken A 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. callback Called 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:
-
destination The destination waypoint. routingOptions The 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. callback The callback called when routes information are received.
- (nullable GMSNavigationWaypoint *) continueToNextDestination |
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.
- (void) clearDestinations |
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:
-
transactionIDs The 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). errorHandler A block that will be invoked asynchronously on the main thread if an error occurs when the transaction IDs are invalid.
Friends And Related Function Documentation
- (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:
-
routeInfo The 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.
- (GMSNavigationLicensePlateRestriction*) licensePlateRestriction [read, write, assign] |
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.
- (GMSVoiceGuidanceAudioDeviceType) audioDeviceType [read, write, assign] |
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.
- (GMSNavigationLightingMode) suggestedLightingMode [read, assign] |
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*) speedAlertOptions [read, write, assign] |
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.