ניווט במסלול

במדריך הזה מוסבר איך לתכנן מסלול ליעד אחד באפליקציה באמצעות Navigation SDK ל-iOS.

סקירה כללית

  1. משלבים את Navigation SDK באפליקציה, כמו שמתואר בקטע הגדרת הפרויקט.
  2. מגדירים GMSMapView.
  3. מבקשים מהמשתמש לאשר את התנאים וההגבלות, ולאשר את שירותי המיקום וההתראות ברקע.
  4. יוצרים מערך שמכיל יעד אחד או יותר.
  5. מגדירים GMSNavigator כדי לשלוט בניווט המפורט.

    • מוסיפים יעדים באמצעות setDestinations.
    • מגדירים את isGuidanceActive לערך true כדי להתחיל בניווט.
    • אפשר להשתמש ב-simulateLocationsAlongExistingRoute כדי לדמות את התקדמות הרכב לאורך המסלול, לצורך בדיקה, ניפוי באגים והדגמה של האפליקציה.

הצגת הקוד

מבקשים מהמשתמש את ההרשאות הנדרשות

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

אישור שירותי מיקום

‫Navigation SDK משתמש בשירותי מיקום, ולכן נדרשת הרשאה מהמשתמש. כדי להפעיל את שירותי המיקום ולהציג את תיבת הדו-שיח של ההרשאה:

  1. מפעילים את יכולות המיקום והרקע ב-Xcode:

    1. פותחים את היעד ב-Xcode ובוחרים בכרטיסייה Signing & Capabilities. פרטים נוספים זמינים במדריך של אפל בנושא הוספת יכולות לאפליקציה.
    2. מוסיפים את היכולות Location (Always)‎ ו-Location (When In Use)‎. בשדה הטקסט של כל אחד מהם, מוסיפים הסבר קצר על הסיבה לכך שהאפליקציה דורשת שירותי מיקום (לדוגמה: "האפליקציה הזו צריכה הרשאה להשתמש בשירותי מיקום לצורך ניווט מפורט").
    3. מוסיפים את היכולת Background Modes (מצבי רקע) ובוחרים בתיבת הסימון Location updates (עדכוני מיקום). בלי היכולת הזו, האפליקציה קורסת כשמתחילים את הניווט. לפרטים נוספים, עיינו במדריך של אפל בנושא טיפול בעדכוני מיקום ברקע.
  2. כדי להציג את תיבת הדו-שיח של ההרשאה, צריך להפעיל את ה-method‏ requestAlwaysAuthorization() של המופע של מנהל המיקום.

Swift

self.locationManager.requestAlwaysAuthorization()

Objective-C

[_locationManager requestAlwaysAuthorization];

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

אישור קבלת התראות על הנחיות ברקע

כדי שהאפליקציה תציג התראות כשהיא פועלת ברקע, צריך לתת ל-Navigation SDK הרשאת משתמש. מוסיפים את הקוד הבא כדי לבקש מהמשתמש הרשאה להציג את ההתראות האלה:

Swift

UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
  granted, error in
    // Handle denied authorization to display notifications.
    if !granted || error != nil {
      print("User rejected request to display notifications.")
    }
}

Objective-C

// Request authorization for alert notifications.
UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
UNAuthorizationOptions options = UNAuthorizationOptionAlert;
[center requestAuthorizationWithOptions:options
                      completionHandler:
 ^(
   BOOL granted,
   NSError *_Nullable error) {
     if (!error && granted) {
       NSLog(@"iOS Notification Permission: newly Granted");
     } else {
       NSLog(@"iOS Notification Permission: Failed or Denied");
     }
   }];

אישור חיישני תנועה

בגרסה ראשית עתידית, Navigation SDK ל-iOS ישלב נתוני מיקום בסיסיים עם חיישני תנועה במכשיר (CMAltimeter) כדי לחשב את הגובה של המסלול. כשה-SDK ניגש למד הגובה, מערכת iOS משתמשת במחרוזת הזו באופן אוטומטי כדי לבקש הרשאה מהמשתמש.

הוספת המפתח הזה עכשיו לא משפיעה על ההתנהגות הנוכחית, אבל מונעת קריסות באתחול כשמשדרגים את ה-SDK מאוחר יותר.

כדי להתכונן לשדרוגים עתידיים של ה-SDK, צריך להגדיר את ההרשאות של חיישן התנועה באופן הבא:

  1. פותחים את היעד ב-Xcode ועוברים לכרטיסייה Info, או פותחים את הקובץ Info.plist.

  2. מוסיפים מפתח חדש: Privacy - Motion Usage Description (NSMotionUsageDescription).

  3. מוסיפים הסבר קצר למשתמש. לדוגמה: "האפליקציה הזו דורשת גישה לחיישן התנועה כדי לחשב את הגובה ולשפר את הדיוק של מסלול המפה".

מאשרים את התנאים וההגבלות

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

Swift

  let termsAndConditionsOptions = GMSNavigationTermsAndConditionsOptions(companyName: "Ride Sharing Co.")

  GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
    with: termsAndConditionsOptions) { termsAccepted in
    if termsAccepted {
      // Enable navigation if the user accepts the terms.
      self.mapView.isNavigationEnabled = true
      self.mapView.settings.compassButton = true

      // Request authorization to use location services.
      self.locationManager.requestAlwaysAuthorization()

      // Request authorization for alert notifications which deliver guidance instructions
      // in the background.
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
      granted, error in
        // Handle rejection of notification authorization.
        if !granted || error != nil {
          print("Authorization to deliver notifications was rejected.")
        }
      }
    } else {
      // Handle rejection of terms and conditions.
    }
  }

Objective-C

GMSNavigationTermsAndConditionsOptions *termsAndConditionsOptions = [[GMSNavigationTermsAndConditionsOptions alloc] initWithCompanyName:@"Ride Sharing Co."];

[GMSNavigationServices
  showTermsAndConditionsDialogIfNeededWithOptions:termsAndConditionsOptions
  callback:^(BOOL termsAccepted) {
   if (termsAccepted) {
     // Enable navigation if the user accepts the terms.
     _mapView.navigationEnabled = YES;
     _mapView.settings.compassButton = YES;

     // Request authorization to use the current device location.
     [_locationManager requestAlwaysAuthorization];

     // Request authorization for alert notifications which deliver guidance instructions
     // in the background.
     UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
     UNAuthorizationOptions options = UNAuthorizationOptionAlert;
     [center requestAuthorizationWithOptions:options
                           completionHandler:
     ^(
       BOOL granted,
       NSError *_Nullable error) {
         if (!error && granted) {
           NSLog(@"iOS Notification Permission: newly Granted");
         } else {
           NSLog(@"iOS Notification Permission: Failed or Denied");
         }
       }];
   } else {
     // Handle rejection of the terms and conditions.
   }
 }];

יצירת מסלול והתחלת ההנחיה

כדי לתכנן מסלול, מפעילים את ה-method‏ setDestinations של ה-navigator עם מערך של יעד אחד או יותר מסוג GMSNavigationWaypoint. אם המסלול מחושב בהצלחה, הוא מופיע במפה. כדי להתחיל את ההנחיה לאורך המסלול, מגדירים את isGuidanceActive ל-true בקריאה החוזרת (callback).

בדוגמה הבאה מוצגים:

  • יצירת מסלול חדש עם יעד אחד.
  • ההדרכה מתחילה.
  • הפעלת התראות על הנחיות ברקע.
  • סימולציה של נסיעה לאורך המסלול (אופציונלי).
  • הגדרת מצב המצלמה ל "מעקב" (אופציונלי).

Swift

func startNav() {
  var destinations = [GMSNavigationWaypoint]()
  destinations.append(GMSNavigationWaypoint.init(placeID: "ChIJnUYTpNASkFQR_gSty5kyoUk",
                                                 title: "PCC Natural Market")!)

  mapView.navigator?.setDestinations(destinations) { routeStatus in
    self.mapView.navigator?.isGuidanceActive = true
    self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
    self.mapView.cameraMode = .following
  }
}

Objective-C

- (void)startNav {
  NSArray<GMSNavigationWaypoint *> *destinations =
  @[[[GMSNavigationWaypoint alloc] initWithPlaceID:@"ChIJnUYTpNASkFQR_gSty5kyoUk"
                                             title:@"PCC Natural Market"]];

  [_mapView.navigator setDestinations:destinations
                             callback:^(GMSRouteStatus routeStatus){
                               [_mapView.locationSimulator simulateLocationsAlongExistingRoute];
                               _mapView.navigator.guidanceActive = YES;
                               _mapView.cameraMode = GMSNavigationCameraModeFollowing;
                             }];
}

מידע נוסף על מזהי מקומות

תרחישים עם כמה עצירות

אפשר להגדיר עד 25 ציוני דרך.

אמצעי התחבורה setDestinations לא תומך בנסיעות עם כמה עצירות. משתמשים ב-continueToNextDestinationWithCompletion() כדי להעביר את נקודת הציון לחלק הבא של הנסיעה.

הגדרת מצב נסיעה

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

מגדירים את המאפיין travelMode של תצוגת המפה, כמו בדוגמה הבאה:

Swift

self.mapView.travelMode = .cycling

Objective-C

_mapView.travelMode = GMSNavigationTravelModeCycling;

הגדרת כבישים שרוצים להימנע מהם

כדי להימנע מכבישים מהירים, מכבישי אגרה או משניהם לאורך מסלול, משתמשים במאפיינים avoidsHighways ו-avoidsTolls BOOL.

Swift

self.mapView.navigator?.avoidsTolls = true

Objective-C

_mapView.navigator.avoidsTolls = YES;

הגדרת עוצמת הקול של ההנחיה הקולית

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

Swift

self.mapView.navigator?.volumeLevel = .low

Objective-C

_mapView.navigator.volumeLevel = GMSNavigationVolumeLevelLow;

כלי למציאת מזהה מקום

אתם יכולים להשתמש בכלי לאיתור מזהי מקומות כדי למצוא מזהי מקומות שבהם אפשר להשתמש כיעדים במסלול. הוספת יעד מ-placeID באמצעות GMSNavigationWaypoint.

טקסט צף

אפשר להוסיף טקסט צף בכל מקום באפליקציה, כל עוד הוא לא מכסה את השיוך ל-Google. ‫Navigation SDK לא תומך בעיגון הטקסט לקואורדינטות ספציפיות (קו רוחב, קו אורך) במפה או לתווית. מידע נוסף זמין במאמר חלונות מידע.