‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

תכנון מסלול

לפעמים תרצו לתכנן את המסלול שהאפליקציה שלכם מספקת למשתמשים. שימוש בטוקן מסלול מ-Routes API, מ-Routes Preferred API או מ-Route Optimization API יכול לעזור לכם לציין שני דברים במסלול המתוכנן:

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

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

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

מידע נוסף על תכנון מסלול באמצעות טוקן מסלול זמין במאמר קבלת טוקן מסלול ב-Routes API ובמאמר מעבר בין קווים פוליגוניים לטוקנים של מסלולים ב-Route Optimization API.

למה כדאי להשתמש באסימון מסלול ליעדי מסלול

טוקן מסלול מ-Routes API, מ-Routes Preferred API או מ-Route Optimization API מאפשר לכם לשלוט טוב יותר במסלול שמוצג:

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

איך פועלים אסימוני מסלול

אתם יכולים להשתמש ב-Routes API, ב-Routes Preferred API או ב-Route Optimization API כדי לתכנן מסלול באמצעות יעדי מסלול. אתם יכולים להעביר טוקן מסלול שמוחזר מכל אחד מממשקי ה-API האלה ל-Navigation SDK כדי להנחות את אופן הניווט של הרכב.

זה מה שקורה כשמבקשים טוקן מסלול ומשתמשים בו:

‫Routes API,‏ Routes Preferred API או Route Optimization API מחזירים טוקן מסלול מוצפן שכולל את הקו הפוליגוני של המסלול ואת יעדי המסלול.
מעבירים את הטוקן של המסלול ל-Navigation SDK.
‫Navigation SDK מתחיל את הניווט במסלול המתוכנן, גם אם יש מסלול מהיר יותר.
במהלך הנסיעה, אם תנאי התנועה או הכביש משתנים, או אם הרכב סוטה מהמסלול המתוכנן, ה-Navigation SDK מחשב מסלול חדש בהתאם ליעדי המסלול ולאפשרויות המסלול שהוגדרו בטוקן המסלול.

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

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

הניווט מתחיל במסלול המתוכנן, אבל המסלול בפועל יכול להיות שונה ממנו במצבים כמו:

הרכב מתחיל את הנסיעה מחוץ לנקודת ההתחלה המתוכננת.
מצב התנועה או הכביש משתנה במהלך הנסיעה.
הרכב סוטה מהמסלול המתוכנן.

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

תכנון מסלול באמצעות טוקן מסלול

כדי לתכנן מסלול, אתם יכולים ליצור טוקן מסלול ואז להעביר אותו ל-Navigation SDK, כמו שמתואר בשלבים הבאים:

שלב 1: יוצרים טוקן מסלול באמצעות Routes API,‏ Routes Preferred API או Route Optimization API

מבקשים טוקן מסלול באחת מהשיטות הבאות:
- ‫Routes API: computeRoutes. מידע נוסף על בקשת טוקן מסלול ב-Routes API זמין במאמרים חישוב מסלול וקבלת טוקן מסלול.
- ‫Routes Preferred API: computeCustomRoutes. למידע נוסף על בקשת טוקן מסלול ב-Routes Preferred API, ראו תכנון מסלול.
- ‫Route Optimization API: optimizeTours או batchOptimizeTours. מידע נוסף על בקשת טוקן מסלול ב-Route Optimization API זמין במאמר קווים פוליגוניים של מעברים וטוקנים של מסלולים.
מגדירים את הבקשה ל-Routes API או ל-Routes Preferred API כך שתעמוד בדרישות לשימוש בטוקן מסלול:
- מגדירים את travelMode לערך DRIVE או TWO_WHEELER.
- מגדירים את routingPreference לערך TRAFFIC_AWARE או TRAFFIC_AWARE_OPTIMAL.
- אל תשתמשו ב-Via נקודות ציון.

שלב 2: מעבירים את הטוקן של המסלול ל-Navigation SDK

אחסון הטוקן של המסלול: ב-Navigation SDK, מגדירים מחרוזת לאחסון הטוקן של המסלול. לדוגמה:

let routeToken = "route token returned by Routes API"

דוגמה לטוקן מסלול שמוחזר בתגובה:

{
// Other fields
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
}

מעבירים את הטוקן של המסלול ל-Navigation SDK באמצעות ה-method‏ setDestinationsWithToken:completionHandler: של mapView.navigator. ‫Navigation SDK מקבל את היעדים ואת אפשרויות המסלול מהאסימון, כך שלא צריך להעביר נקודות דרך.

אמצעי ההגעה שמוגדר באפליקציה, למשל mapView.travelMode, חייב להיות אחד מהערכים הבאים:
- .driving (GMSNavigationTravelModeDriving): נהיגה. זהו ערך ברירת המחדל, כך שברוב האפליקציות אין צורך לשנות אותו.
- ‫.twoWheeler (GMSNavigationTravelModeTwoWheeler): רכב דו-גלגלי.
כל אמצעי תחבורה אחר יגרום לשגיאה .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). בכל אחד מהערכים הנתמכים, המסלול משתמש באמצעי התחבורה שמוגדר בטוקן המסלול. לדוגמה, אם באפליקציה שלכם מוגדרת נהיגה, והאסימון של המסלול הוא למסלול של רכב דו-גלגלי, ה-Navigation SDK מספק מסלול לרכב דו-גלגלי. כדי לבדוק באיזה אמצעי תחבורה משתמשים במסלול, בודקים את resolvedParameters.travelMode. מידע נוסף זמין במאמר אפשרויות ניתוב שנפתרו.

הערה: אם באפליקציה שלכם מותקנת גרסה של Navigation SDK שקודמת ל-11.3, אתם צריכים להשתמש במקום זאת ב-method שהוצא משימוש setDestinations:routeToken:callback:, ולהעביר את אותן נקודות ציון של היעד שבהן השתמשתם כדי ליצור את הטוקן של המסלול.
בודקים את סטטוס המסלול ב-completion handler. כשה-Navigation SDK מסיים לחשב את המסלול, הוא מעביר GMSNavigationRouteDescription ל-completion handler. אם נמצא מסלול ממיקום הרכב ליעדים שמופיעים בטוקן המסלול, הערך של routeStatus בתיאור המסלול הוא .OK (GMSRouteStatusOK), ואפשר להתחיל את ההנחיה. אחרת, ה-completion handler יקבל גם NSError שמתאר את הכישלון. לדוגמה:
```
mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  if routeDescription?.routeStatus == .OK {
    self?.mapView.navigator?.isGuidanceActive = true
  }
}
```

איך בודקים אם ה-Navigation SDK החיל את הטוקן של המסלול

סטטוס מסלול של .OK מציין ש-Navigation SDK מצא מסלול, אבל לא בהכרח את המסלול שתכננתם. כדי לבדוק אם המסלול תואם למסלול המתוכנן, מבצעים את השלבים הבאים ב-completion handler:

מוודאים שהערך של routeStatus בתיאור הנתיב הוא .OK. ‫Navigation SDK מספק פרטים של אסימון מסלול רק כשהוא מוצא מסלול. מידע נוסף זמין בשלב 2.
מקבלים את תיאור המסלול routeTokenExecutionDetails, אובייקט שתואם לפרוטוקול GMSNavigationRouteTokenExecutionDetails. אם השרת לא מספק פרטים על טוקן המסלול, המאפיין הזה הוא nil.
בודקים את המאפיין tokenExecutionStatus של פרטי הביצוע. אם הוא .tokenSuccessfullyApplied, המסלול תואם למסלול המתוכנן. כל סטטוס אחר מציין שהמסלול עשוי להיות שונה מהמסלול שתכננתם. במאמר ערכי סטטוס הביצוע של אסימון מוסבר על כל סטטוס בהרחבה.
אופציונלי: אם הסטטוס הוא .tokenSuccessfullyApplied, בודקים את המאפיין resolvedParameters של אותם פרטי ביצוע כדי לראות באילו אפשרויות ניתוב המסלול משתמש, למשל אם הוא נמנע מכבישי אגרה. מידע נוסף זמין במאמר אפשרויות ניתוב שנפתרו.

ערכי סטטוס הביצוע של הטוקן

אם הערך של routeStatus הוא .OK, אפשר להתחיל את ההנחיה בכל סטטוס של ביצוע טוקן. הסטטוס מציין אם המסלול תואם למסלול המתוכנן.

סטטוס	המסלול המתוכנן שלכם	תיאור
`.tokenSuccessfullyApplied`	כן	‫Navigation SDK החיל את טוקן המסלול.
`.tokenAppliedWithLocationMismatch`	לא בהכרח	ערכת ה-SDK לניווט לא הצליחה לבנות מחדש את המסלול המתוכנן, והמכשיר היה במרחק של יותר מ-25 מטרים מנקודת המוצא בטוקן המסלול. המסלול עדיין משתמש ביעדים ובאפשרויות הניתוב מהאסימון של המסלול.
`.tokenIgnoredOther`	לא בהכרח	ה-Navigation SDK לא הצליח לבנות מחדש את המסלול המתוכנן מסיבה אחרת, למשל כי כביש במסלול המתוכנן סגור. המסלול עדיין משתמש ביעדים ובאפשרויות הניתוב מהאסימון של המסלול.
`.noTokenProvided`	לא רלוונטי	בקשת המסלול לא כללה אסימון מסלול.
`.unknown`	לא ידוע	הסטטוס לא ידוע.

אם המסלול לא בהכרח תואם למסלול המתוכנן והמסלול המדויק חשוב, למשל כי השתמשתם בו כדי לחשב מחיר, תעדו את הסטטוס או בקשו אסימון מסלול חדש מהמיקום הנוכחי של הרכב.

אפשרויות ניתוב שנפתרו

‫resolvedParameters הוא אובייקט שתואם לפרוטוקול GMSNavigationRouteTokenResolvedParameters, או nil אם אפשרויות הניתוב לא זמינות. המאפיינים שלו הם:

‫travelMode: אופן הנסיעה שבו משתמשים במסלול, למשל .driving (GMSNavigationTravelModeDriving). ערכת ה-Navigation SDK מדווחת גם על .driving כשהמסלול משתמש באופן נסיעה שאין לו ערך תואם, או כשאופן הנסיעה לא זמין.
‫avoidTolls: אם המסלול נמנע מכבישי אגרה.
‫avoidHighways: אם המסלול עוקף כבישים מהירים.
‫avoidFerries: אם המסלול עוקף מעבורות.
‫avoidTunnels: אם המסלול חושב כך שיימנע ממנהרות כשאפשר.
‫avoidVignettes: המדינות שבהן המסלול חושב כדי להימנע ממדבקות אגרה כשאפשר, בתור קודי אזור בני שתי אותיות של Unicode CLDR, כמו CH לשווייץ.
‫rerouteStrategy: האסטרטגיה שבה משתמש הקצה העורפי של הניתוב כדי לחשב מסלולים חדשים במהלך הנסיעה. האסטרטגיות כוללות את .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), שמשתמשת בפרמטרים של המסלול בטוקן המסלול כדי לחשב מסלולים חדשים.

אם סטטוס הביצוע של הטוקן הוא לא .tokenSuccessfullyApplied, ה-Navigation SDK מדווח רק על travelMode,‏ avoidTolls,‏ avoidHighways ו-avoidFerries. המאפיינים האחרים מקבלים את ערכי ברירת המחדל שלהם, גם אם ביקשתם להימנע ממנהרות או ממדבקות אגרה כשביקשתם את אסימון המסלול: avoidTunnels הוא false (NO), avoidVignettes ריק ו-rerouteStrategy הוא .unknown (GMSNavigationRerouteStrategyUnknown).

דוגמה

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

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

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

אפשר להגדיר עד 25 נקודות ציון.

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

איך טוקנים של מסלולים ו-Navigation SDK פועלים יחד

כך ה-Navigation SDK מטפל במסלול המתוכנן:

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

שימוש באפשרויות הניתוב שמוגדרות בטוקן המסלול במקום בהגדרות הבאות באפליקציה, כולל כשהאפליקציה מחשבת מסלול חדש במהלך הנסיעה:
- avoidsHighways
- avoidsTolls
- avoidsFerries
- licensePlateRestriction
- אמצעי ההגעה שמוגדר באפליקציה

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