Cómo detectar eventos de navegación

Usa esta guía para habilitar tu app para que escuche y responda a una variedad de eventos que cambian a medida que un usuario navega por una ruta. En esta guía, no se explica cómo definir una ruta, solo cómo responder a los eventos que se producen en ella.

Descripción general

El SDK de Navigation para iOS te proporciona objetos de escucha asociados con la ubicación del usuario y las condiciones de la ruta, así como datos importantes de tiempo y distancia. En el controlador de vista del mapa, tu app debe adoptar los protocolos para estos objetos de escucha: GMSRoadSnappedLocationProviderListener y GMSNavigatorListener.

En esta lista, se muestran los métodos de objeto de escucha disponibles para los eventos de navegación:

Consulta el código

Declara la conformidad con los protocolos requeridos

Antes de implementar los métodos de navegación, el controlador de vista debe adoptar los protocolos:

Swift

class ViewController:
  UIViewController,
  GMSNavigatorListener,
  GMSRoadSnappedLocationProviderListener
{
}

Objective-C

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

Después de adoptar los protocolos de navegación, configura los objetos de escucha en el controlador de vista. Por ejemplo, puedes agregar el siguiente código al método viewDidLoad().

Swift

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

Objective-C

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

Cómo recibir o detener actualizaciones de ubicación

Las actualizaciones de ubicación son necesarias para mostrar el progreso del usuario en el mapa.

La instancia de location expone las siguientes propiedades:

Propiedad de ubicación Descripción
Altitud Altitud actual.
coordinate.latitude Es la coordenada de latitud actual ajustada a la ruta.
coordinate.longitude Coordenada de longitud actual ajustada a la ruta.
curso Es la orientación actual en grados.
velocidad Velocidad actual.
timestamp Fecha y hora de la lectura actual.

Para recibir actualizaciones de ubicación continuas, llama a mapView.roadSnappedLocationProvider.startUpdatingLocation y usa GMSRoadSnappedLocationProviderListener para controlar el evento didUpdateLocation.

En el siguiente ejemplo, se muestra cómo llamar a startUpdatingLocation:

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

El siguiente código crea un GMSRoadSnappedLocationProviderListener que controla el evento 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);
}

Para recibir actualizaciones de ubicación cuando la app está en segundo plano, establece allowsBackgroundLocationUpdates como verdadero:

Swift

mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true

Objective-C

 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;

Detecta eventos de llegada

Tu app usa el evento didArriveAtWaypoint para detectar cuándo se llegó a un destino. Puedes reanudar la guía y avanzar al siguiente punto de referencia llamando a continueToNextDestinationWithCompletion() y, luego, volviendo a habilitar la guía. Tu app debe volver a habilitar la guía después de llamar a continueToNextDestinationWithCompletion().

Después de que la app llama a continueToNextDestinationWithCompletion, el navegador ya no tiene datos sobre el destino anterior. Si deseas analizar información sobre un tramo de ruta, debes recuperarla del navegador antes de llamar a continueToNextDestinationWithCompletion().

En el siguiente ejemplo de código, se muestra un método para controlar el evento 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;
}

Recibe actualizaciones de cambios de ruta

Para recibir una notificación cada vez que cambie la ruta, crea un método que controle el evento navigatorDidChangeRoute. Puedes acceder a la ruta nueva con las propiedades routeLegs y currentRouteLeg de GMSNavigator.

Swift

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

Objective-C

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

Recibe actualizaciones sobre el tiempo hasta el destino

Para recibir actualizaciones continuas del tiempo hasta el destino, crea un método que controle el evento didUpdateRemainingTime. El parámetro time proporciona el tiempo estimado, en segundos, hasta que se alcance el siguiente destino.

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);
}

Para establecer el cambio mínimo en el tiempo estimado hasta el próximo destino, configura la propiedad timeUpdateThreshold en GMSNavigator. El valor se especifica en segundos. Si no se establece esta propiedad, los servicios usan un valor predeterminado de un segundo.

Swift

navigator?.timeUpdateThreshold = 10

Objective-C

navigator.timeUpdateThreshold = 10;

Recibe actualizaciones de la distancia hasta el destino

Para recibir actualizaciones continuas de la distancia hasta el destino, crea un método que controle el evento didUpdateRemainingDistance. El parámetro distance proporciona la distancia estimada, en metros, hasta el próximo destino.

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]);
}

Para establecer el cambio mínimo en la distancia estimada hasta el próximo destino, configura la propiedad distanceUpdateThreshold en GMSNavigator (el valor se especifica en metros). Si no se establece esta propiedad, los servicios usan un valor predeterminado de un metro.

Swift

navigator?.distanceUpdateThreshold = 100

Objective-C

navigator.distanceUpdateThreshold = 100;

Recibe actualizaciones del tráfico

Para recibir actualizaciones continuas del flujo de tráfico de la ruta restante, crea un método que controle el evento didUpdateDelayCategory. Una llamada a delayCategoryToNextDestination devuelve GMSNavigationDelayCategory, que proporciona un valor de 0 a 3. Las actualizaciones de la categoría se basan en la posición actual del usuario de la app. Si los datos de tráfico no están disponibles, GMSNavigationDelayCategory devuelve 0. Los números del 1 al 3 indican un aumento del flujo, de leve a abundante.

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 propiedad GMSNavigationDelayCategory expone los siguientes niveles de retraso:

Categoría de retraso Descripción
GMSNavigationDelayCategoryNoData 0: No disponible, no hay datos de tráfico o :
la ruta.
GMSNavigationDelayCategoryHeavy 1: Intenso
GMSNavigationDelayCategoryMedium 2 - Moderado
GMSNavigationDelayCategoryLight 3 - Ligera.

Recibe actualizaciones sobre exceso de velocidad

Para recibir actualizaciones cuando un conductor exceda el límite de velocidad, crea un método que controle el evento 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);
}

Cambiando el modo de iluminación sugerido

GMSNavigator calcula el modo de iluminación sugerido según la hora del día y la ubicación del dispositivo, y llama al método de objeto de escucha didChangeSuggestedLightingMode solo cuando cambia el modo sugerido (como al amanecer o al atardecer). Para asegurarte de que el mapa se inicie con el modo de iluminación adecuado cuando el usuario inicie tu app, establece mapView.lightingMode en el suggestedLightingMode del navegador durante la inicialización y, luego, implementa didChangeSuggestedLightingMode para controlar los cambios posteriores.

En el siguiente ejemplo, se muestra cómo configurar el modo de iluminación inicial y escuchar los cambios sugeridos en el modo de iluminación:

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;
}

Para obtener más información sobre la configuración automática y manual del modo de iluminación, consulta Configura los modos normal y de poca luz.