האזנה לאירועי ניווט

המדריך הזה יעזור לכם להגדיר את האפליקציה כך שתאזין ותגיב למגוון אירועים שמשתנים כשהמשתמש מנווט לאורך מסלול. המדריך הזה לא עוסק בהגדרת מסלול, אלא רק בתגובה לאירועים לאורך המסלול.

סקירה כללית

‫Navigation SDK ל-iOS מספק מאזינים שמשויכים למיקום של המשתמש ולתנאים לאורך המסלול, ונתונים חשובים על זמן ומרחק. בבקר התצוגה של המפה, האפליקציה צריכה לאמץ את הפרוטוקולים של המאזינים האלה: GMSRoadSnappedLocationProviderListener ו-GMSNavigatorListener.

ברשימה הזו מוצגות שיטות ה-listener שזמינות לאירועי ניווט:

לצפייה בקוד

הצהרה על תאימות לפרוטוקולים הנדרשים

לפני שמטמיעים את שיטות הניווט, צריך להגדיר את הפרוטוקולים הבאים ב-view controller:

Swift

class ViewController:
  UIViewController,
  GMSNavigatorListener,
  GMSRoadSnappedLocationProviderListener
{
}

Objective-C

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

אחרי שמאמצים את פרוטוקולי הניווט, מגדירים את המאזינים ל-view controller. לדוגמה, אפשר להוסיף את הקוד הבא ל-method‏ viewDidLoad().

Swift

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

Objective-C

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

קבלת עדכונים לגבי מיקום או הפסקת קבלת העדכונים

כדי להציג את ההתקדמות של המשתמש במפה, נדרשים עדכונים לגבי מיקום.

המופע של location חושף את המאפיינים הבאים:

מאפיין המיקום תיאור
גובה הגובה הנוכחי.
coordinate.latitude הקואורדינטה הנוכחית של קו הרוחב, מוצמדת לכביש.
coordinate.longitude הקואורדינטה הנוכחית של קו האורך, מוצמדת לכביש.
קורס הכיוון הנוכחי במעלות.
מהירות המהירות הנוכחית.
חותמת זמן התאריך והשעה של הקריאה הנוכחית.

כדי לקבל עדכוני מיקום רציפים, צריך להפעיל את mapView.roadSnappedLocationProvider.startUpdatingLocation ולהשתמש ב-GMSRoadSnappedLocationProviderListener כדי לטפל באירוע didUpdateLocation.

בדוגמה הבאה מוצגת קריאה ל-startUpdatingLocation:

Swift

mapView.roadSnappedLocationProvider.startUpdatingLocation()

Objective-C

[_mapView.roadSnappedLocationProvider startUpdatingLocation];

הקוד הבא יוצר GMSRoadSnappedLocationProviderListener שמטפל באירוע 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);
}

כדי לקבל עדכוני מיקום כשהאפליקציה פועלת ברקע, מגדירים את allowsBackgroundLocationUpdates כ-true:

Swift

mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = true

Objective-C

 _mapView.roadSnappedLocationProvider.allowsBackgroundLocationUpdates = YES;

זיהוי אירועי הגעה

האפליקציה משתמשת באירוע didArriveAtWaypoint כדי לזהות מתי המשתמש הגיע ליעד. כדי להמשיך את ההנחיה ולעבור לציון הדרך הבא, צריך להפעיל את continueToNextDestinationWithCompletion() ואז להפעיל מחדש את ההנחיה. האפליקציה צריכה להפעיל מחדש את ההנחיה אחרי הקריאה ל-continueToNextDestinationWithCompletion().

אחרי שהאפליקציה קוראת ל-continueToNextDestinationWithCompletion, ל-navigator אין יותר נתונים על היעד הקודם. אם רוצים לנתח מידע על מקטע במסלול, צריך לאחזר אותו מהנווט לפני שקוראים ל-continueToNextDestinationWithCompletion().

בדוגמת הקוד הבאה מוצגת שיטה לטיפול באירוע 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;
}

קבלת עדכונים על שינויים במסלול

כדי לקבל התראה בכל פעם שהמסלול משתנה, צריך ליצור שיטה לטיפול באירוע navigatorDidChangeRoute. אפשר לגשת לנתיב החדש באמצעות המאפיינים routeLegs ו-currentRouteLeg של GMSNavigator.

Swift

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

Objective-C

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

קבלת עדכונים על זמן ההגעה ליעד

כדי לקבל עדכונים רציפים על הזמן שנותר עד להגעה ליעד, צריך ליצור שיטה לטיפול באירוע didUpdateRemainingTime. הפרמטר time מספק את הזמן המשוער, בשניות, עד להגעה ליעד הבא.

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

כדי להגדיר את השינוי המינימלי בזמן המשוער עד ליעד הבא, מגדירים את המאפיין timeUpdateThreshold ב-GMSNavigator. הערך מצוין בשניות. אם המאפיין הזה לא מוגדר, השירותים משתמשים בערך ברירת המחדל של שנייה אחת.

Swift

navigator?.timeUpdateThreshold = 10

Objective-C

navigator.timeUpdateThreshold = 10;

קבלת עדכונים על המרחק ליעד

כדי לקבל עדכונים רציפים על המרחק ליעד, צריך ליצור שיטה לטיפול באירוע didUpdateRemainingDistance. הפרמטר distance מספק את המרחק המשוער במטרים ליעד הבא.

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

כדי להגדיר את השינוי המינימלי במרחק המשוער ליעד הבא, מגדירים את המאפיין distanceUpdateThreshold ב-GMSNavigator (הערך מצוין במטרים). אם המאפיין הזה לא מוגדר, השירותים משתמשים בערך ברירת המחדל של מטר אחד.

Swift

navigator?.distanceUpdateThreshold = 100

Objective-C

navigator.distanceUpdateThreshold = 100;

קבלת עדכונים על מצב התנועה

כדי לקבל עדכונים שוטפים על זרימת התנועה במסלול שנותר, צריך ליצור שיטה לטיפול באירוע didUpdateDelayCategory. קריאה לפונקציה delayCategoryToNextDestination מחזירה את הערך GMSNavigationDelayCategory, שמספק ערך בין 0 ל-3. העדכונים בקטגוריה מבוססים על המיקום הנוכחי של משתמש האפליקציה. אם נתוני התנועה לא זמינים, הפונקציה GMSNavigationDelayCategory מחזירה את הערך 0. המספרים 1 עד 3 מציינים את עוצמת הזרימה, מקלה ועד כבדה.

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

המאפיין GMSNavigationDelayCategory חושף את רמות העיכוב הבאות:

קטגוריית העיכוב תיאור
GMSNavigationDelayCategoryNoData ‫0 – לא זמין, אין נתונים לגבי תנועה או :
המסלול.
GMSNavigationDelayCategoryHeavy ‫1 – כבד.
GMSNavigationDelayCategoryMedium ‫2 – בינונית.
GMSNavigationDelayCategoryLight ‫3 – קל.

קבלת עדכונים על מהירות מופרזת

כדי לקבל עדכונים כשהנהג חורג מהמהירות המותרת, צריך ליצור שיטה לטיפול באירוע 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);
}

שינוי מצב התאורה המוצעת

GMSNavigator מחשב את מצב התאורה המוצע על סמך השעה ביום והמיקום של המכשיר, וקורא ל-listener method של didChangeSuggestedLightingMode רק כשהמצב המוצע משתנה (למשל בזריחה או בשקיעה). כדי לוודא שהמפה נפתחת במצב התאורה המתאים כשהמשתמש מפעיל את האפליקציה, מגדירים את mapView.lightingMode ל-suggestedLightingMode של הניווט במהלך האיניציאליזציה, ומטמיעים את didChangeSuggestedLightingMode כדי לטפל בשינויים הבאים.

בדוגמה הבאה אפשר לראות איך מגדירים את מצב התאורה הראשוני ומאזינים לשינויים המוצעים במצב התאורה:

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

מידע נוסף על הגדרה אוטומטית וידנית של מצב התאורה זמין במאמר הגדרת מצב תאורה רגילה ומצב תאורה חלשה.