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

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

סקירה כללית

‫Navigation SDK ל-iOS מספק מאזינים שמשויכים למיקום של המשתמש ולתנאים לאורך המסלול, ונתונים חשובים על זמן ומרחק. ב-view controller של המפה, האפליקציה צריכה לאמץ את הפרוטוקולים של המאזינים האלה: 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, לנווט אין יותר נתונים על היעד הקודם. אם אתם רוצים לנתח מידע על מקטע במסלול, אתם צריכים לאחזר אותו מהנווט לפני שאתם קוראים ל-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;
}

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