Écouter les événements de navigation

Suivez ce guide pour permettre à votre application d'écouter et de répondre à divers événements qui changent à mesure qu'un utilisateur parcourt un itinéraire. Ce guide ne traite pas de la définition d'un itinéraire, mais uniquement de la réponse aux événements le long d'un itinéraire.

Présentation

Le SDK Navigation pour iOS vous fournit des écouteurs associés à la position de l'utilisateur et aux conditions le long de l'itinéraire, ainsi que des données importantes sur la durée et la distance. Sur le contrôleur de vue de la carte, votre application doit adopter les protocoles pour ces écouteurs : GMSRoadSnappedLocationProviderListener et GMSNavigatorListener.

Cette liste présente les méthodes d'écouteur disponibles pour les événements de navigation :

Voir le code

Déclarer la conformité aux protocoles requis

Avant d'implémenter les méthodes de navigation, le contrôleur de vue doit adopter les protocoles suivants :

Swift

class ViewController:
  UIViewController,
  GMSNavigatorListener,
  GMSRoadSnappedLocationProviderListener
{
}

Objective-C

@interface ViewController () <GMSNavigatorListener, GMSRoadSnappedLocationProviderListener>
@end

Après avoir adopté les protocoles de navigation, définissez les écouteurs sur le contrôleur de vue. Par exemple, vous pouvez ajouter le code suivant à la méthode viewDidLoad().

Swift

mapView.navigator?.add(self)
mapView.roadSnappedLocationProvider?.add(self)

Objective-C

[_mapView.navigator addListener:self];
[_mapView.roadSnappedLocationProvider addListener:self];

Recevoir ou arrêter de recevoir des notifications de position

Les mises à jour de la position sont nécessaires pour afficher la progression de l'utilisateur sur la carte.

L'instance location expose les propriétés suivantes :

Propriété de l'emplacement Description
altitude Altitude actuelle.
coordinate.latitude Coordonnée de latitude actuelle projetée sur la route.
coordinate.longitude Coordonnée de longitude actuelle alignée sur la route.
cours Orientation actuelle en degrés.
speed Vitesse actuelle.
code temporel Date/Heure de la lecture actuelle.

Pour recevoir des notifications de position en continu, appelez mapView.roadSnappedLocationProvider.startUpdatingLocation et utilisez GMSRoadSnappedLocationProviderListener pour gérer l'événement didUpdateLocation.

L'exemple suivant vous montre comment appeler startUpdatingLocation :

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

Le code suivant crée un GMSRoadSnappedLocationProviderListener qui gère l'événement didUpdateLocation.

Swift

func locationProvider(_ locationProvider: GMSRoadSnappedLocationProvider,
                      didUpdate location: CLLocation) {
  print("Location: \(location.description)")
}

Objective-C

- (void)locationProvider:(GMSRoadSnappedLocationProvider *)locationProvider
       didUpdateLocation:(CLLocation *)location {
  NSLog(@"Location: %@", location.description);
}

Pour recevoir des notifications de position lorsque l'application est en arrière-plan, définissez allowsBackgroundLocationUpdates sur "true" :

Swift

mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true

Objective-C

 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;

Détecter les événements d'arrivée

Votre application utilise l'événement didArriveAtWaypoint pour détecter quand une destination a été atteinte. Vous pouvez reprendre le guidage et passer au point de cheminement suivant en appelant continueToNextDestinationWithCompletion(), puis en réactivant le guidage. Votre application doit réactiver le guidage après avoir appelé continueToNextDestinationWithCompletion().

Une fois que l'application a appelé continueToNextDestinationWithCompletion, le navigateur ne dispose plus de données sur la destination précédente. Si vous souhaitez analyser les informations d'une étape d'itinéraire, vous devez les récupérer à partir du navigateur avant d'appeler continueToNextDestinationWithCompletion().

L'exemple de code suivant montre une méthode permettant de gérer l'événement didArriveAtWaypoint :

Swift

func navigator(_ navigator: GMSNavigator, didArriveAt waypoint: GMSNavigationWaypoint) {
  print("You have arrived at: \(waypoint.title)")
  mapView.navigator?.continueToNextDestinationWithCompletion { _, _ in }
  mapView.navigator?.isGuidanceActive = true
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator didArriveAtWaypoint:(GMSNavigationWaypoint *)waypoint {
  NSLog(@"You have arrived at: %@", waypoint.title);
  [_mapView.navigator continueToNextDestinationWithCompletion:^(GMSNavigationWaypoint *waypoint,
                                                                GMSRouteStatus status){
  }];
  _mapView.navigator.guidanceActive = YES;
}

Recevoir des notifications de changement d'itinéraire

Pour recevoir une notification chaque fois que l'itinéraire est modifié, créez une méthode pour gérer l'événement navigatorDidChangeRoute. Vous pouvez accéder au nouvel itinéraire à l'aide des propriétés routeLegs et currentRouteLeg de GMSNavigator.

Swift

func navigatorDidChangeRoute(_ navigator: GMSNavigator) {
  print("The route has changed.")
}

Objective-C

- (void)navigatorDidChangeRoute:(GMSNavigator *)navigator {
  NSLog(@"The route has changed.");
}

Recevoir des notifications sur la durée du trajet jusqu'à la destination

Pour recevoir des mises à jour continues du temps de trajet jusqu'à la destination, créez une méthode pour gérer l'événement didUpdateRemainingTime. Le paramètre time fournit l'estimation du temps, en secondes, avant d'atteindre la prochaine destination.

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingTime time: TimeInterval) {
  print("Time to next destination: \(time)")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator didUpdateRemainingTime:(NSTimeInterval)time {
  NSLog(@"Time to next destination: %f", time);
}

Pour définir la modification minimale de l'heure d'arrivée estimée à la prochaine destination, définissez la propriété timeUpdateThreshold sur GMSNavigator. La valeur est spécifiée en secondes. Si cette propriété n'est pas définie, les services utilisent une valeur par défaut d'une seconde.

Swift

navigator?.timeUpdateThreshold = 10

Objective-C

navigator.timeUpdateThreshold = 10;

Recevoir des informations sur la distance jusqu'à la destination

Pour recevoir des informations continues sur la distance jusqu'à la destination, créez une méthode pour gérer l'événement didUpdateRemainingDistance. Le paramètre distance fournit la distance estimée, en mètres, jusqu'à la destination suivante.

Swift

func navigator(_ navigator: GMSNavigator, didUpdateRemainingDistance distance: CLLocationDistance)
{
  let miles = distance * 0.00062137
  print("Distance to next destination: \(miles) miles.")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator
    didUpdateRemainingDistance:(CLLocationDistance)distance {
  double miles = distance * 0.00062137;
  NSLog(@"%@", [NSString stringWithFormat:@"Distance to next destination: %.2f.", miles]);
}

Pour définir la variation minimale de la distance estimée jusqu'à la prochaine destination, définissez la propriété distanceUpdateThreshold sur GMSNavigator (la valeur est spécifiée en mètres). Si cette propriété n'est pas définie, les services utilisent une valeur par défaut d'un mètre.

Swift

navigator?.distanceUpdateThreshold = 100

Objective-C

navigator.distanceUpdateThreshold = 100;

Recevoir des informations sur le trafic

Pour recevoir des mises à jour continues du flux de trafic pour l'itinéraire restant, créez une méthode pour gérer l'événement didUpdateDelayCategory. Un appel à delayCategoryToNextDestination renvoie GMSNavigationDelayCategory, qui fournit une valeur comprise entre 0 et 3. Les mises à jour de la catégorie sont basées sur la position actuelle de l'utilisateur de l'application. Si les données de trafic ne sont pas disponibles, GMSNavigationDelayCategory renvoie 0. Les chiffres de 1 à 3 indiquent un flux croissant, de léger à abondant.

Swift

func navigator(_ navigator: GMSNavigator,
               didUpdate delayCategory: GMSNavigationDelayCategory)
{
  print("Traffic flow to next destination: \(delayCategory)")
}

Objective-C

- (void)navigator:(GMSNavigator *)navigator
    didUpdateDelayCategory:(GMSNavigationDelayCategory)delayCategory {
  NSLog(@"Traffic flow to next destination: %ld", (long)delayCategory);
}

La propriété GMSNavigationDelayCategory expose les niveaux de retard suivants :

Catégorie de retard Description
GMSNavigationDelayCategoryNoData 0 : non disponible, aucune donnée sur le trafic ou :
sur l'itinéraire.
GMSNavigationDelayCategoryHeavy 1 – Fortes.
GMSNavigationDelayCategoryMedium 2 - Moyenne.
GMSNavigationDelayCategoryLight 3 – Léger.

Recevoir des informations sur les excès de vitesse

Pour recevoir des notifications lorsqu'un conducteur dépasse la limite de vitesse, créez une méthode pour gérer l'événement didUpdateSpeedingPercentage.

Swift

// Listener to handle speeding events.
func navigator(_ navigator: GMSNavigator,
               didUpdateSpeedingPercentage percentageAboveLimit: CGFloat)
{
  print("Speed is \(percentageAboveLimit) above the limit.")
}

Objective-C

// Listener to handle speeding events.
- (void)navigator:(GMSNavigator *)navigator
    didUpdateSpeedingPercentage:(CGFloat)percentageAboveLimit {
  NSLog(@"Speed is %f percent above the limit.", percentageAboveLimit);
}

Modification du mode d'éclairage suggéré…

GMSNavigator calcule le mode d'éclairage suggéré en fonction de l'heure et de l'emplacement de l'appareil, et n'appelle la méthode d'écouteur didChangeSuggestedLightingMode que lorsque le mode suggéré change (par exemple, au lever ou au coucher du soleil). Pour vous assurer que la carte démarre avec le mode d'éclairage approprié lorsque l'utilisateur lance votre application, définissez mapView.lightingMode sur suggestedLightingMode du navigateur lors de l'initialisation, puis implémentez didChangeSuggestedLightingMode pour gérer les modifications ultérieures.

L'exemple suivant montre comment définir le mode d'éclairage initial et écouter les suggestions de changement de mode d'éclairage :

Swift

// Set the initial lighting mode on launch or setup.
mapView.lightingMode = mapView.navigator?.suggestedLightingMode ?? .normal

// Define a listener for suggested changes to lighting mode.
func navigator(_ navigator: GMSNavigator,
               didChangeSuggestedLightingMode lightingMode: GMSNavigationLightingMode)
{
  print("Suggested lighting mode has changed: \(String(describing: lightingMode))")

  // Make the suggested change.
  mapView.lightingMode = lightingMode
}

Objective-C

// Set the initial lighting mode on launch or setup.
_mapView.lightingMode = _mapView.navigator.suggestedLightingMode;

// Define a listener for suggested changes to lighting mode.
- (void)navigator:(GMSNavigator *)navigator
    didChangeSuggestedLightingMode:(GMSNavigationLightingMode)lightingMode {
  NSLog(@"Suggested lighting mode has changed: %ld", (long)lightingMode);

  // Make the suggested change.
  _mapView.lightingMode = lightingMode;
}

Pour en savoir plus sur la configuration automatique et manuelle du mode d'éclairage, consultez Configurer les modes normal et faible luminosité.