תכנון מסלול

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

• קו פוליגוני של המסלול

• היעדים שלכם במסלול

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

• צמצום זמן המשלוח: עסק שמספק משלוחי אוכל יכול לצמצם את הזמן שלוקח לספק את האוכל.

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

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

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

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

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

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

כשמשתמשים בטוקן מסלול מ-Routes API או מ-Route Optimization API, יש לכם יותר שליטה על המסלול שמתקבל:

• תכנון מסלול מראש לשימוש ב-Navigation SDK.

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

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

• להגדיר יעדי מסלול מתקדמים יותר, כמו מסלול ידידותי לסביבה או המסלול הקצר ביותר.

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

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

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

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

1. ‫Routes API או Route Optimization API מחזירים אסימון מסלול מוצפן שכולל את הקו הפוליגוני של המסלול ואת יעדי המסלול.

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

3. ‫Navigation SDK מתחיל את הניווט במסלול המתוכנן, גם אם יש מסלול מהיר יותר.

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

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

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

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

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

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

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

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

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

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

1. מבקשים טוקן מסלול באחת מהשיטות הבאות:

   • ‫Routes API: computeRoutes. מידע נוסף על בקשת טוקן מסלול ב-Routes API זמין במאמרים חישוב מסלול וקבלת טוקן מסלול.

   • ‫Route Optimization API: optimizeTours או batchOptimizeTours. מידע נוסף על בקשת טוקן מסלול ב-Route Optimization API זמין במאמר קווים פוליגוניים של מעברים וטוקנים של מסלולים.

2. מגדירים את בקשת ה-API של Routes כך שתעמוד בדרישות לשימוש בטוקן מסלול:

   • מגדירים את travelMode לערך DRIVE או TWO_WHEELER.
   • מגדירים את routingPreference לערך TRAFFIC_AWARE או TRAFFIC_AWARE_OPTIMAL.
   • אל תשתמשו ב-Via נקודות ציון.

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

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

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

   String routeToken = "route token returned by Routes API";
   

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

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

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

   setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
   setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
   

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

3. בודקים את סטטוס המסלול בקריאה החוזרת (callback). כשה-SDK לניווט מסיים לחשב את המסלול, הוא מעביר RouteDescription לקריאה החוזרת (callback). אם נמצא מסלול ממיקום הרכב ליעדים שמופיעים בטוקן המסלול, RouteDescription.getRouteStatus מחזירה את הערך Navigator.RouteStatus.OK ואפשר להתחיל את ההנחיה. לדוגמה:

   navigator.setDestinationsWithToken(
       routeToken,
       routeDescription -> {
         if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
           navigator.startGuidance();
         }
       });
   

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

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

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

1. מוודאים שהפונקציה RouteDescription.getRouteStatus מחזירה את הערך Navigator.RouteStatus.OK. ‫Navigation SDK מספק פרטים על אסימון המסלול רק כשהוא מוצא מסלול. מידע נוסף זמין בשלב 2.

2. קוראים ל-RouteDescription.getRouteTokenExecutionDetails כדי לקבל אובייקט RouteTokenExecutionDetails. אם השרת לא מספק פרטים על אסימון המסלול, השיטה הזו מחזירה את הערך null.

3. מפעילים את getTokenExecutionStatus באובייקט RouteTokenExecutionDetails. אם הפונקציה מחזירה את הערך TOKEN_SUCCESSFULLY_APPLIED, המסלול תואם למסלול המתוכנן. כל סטטוס אחר מציין שהמסלול עשוי להיות שונה מהמסלול שתכננתם. במאמר ערכי סטטוס הביצוע של אסימונים מוסבר על כל סטטוס בהרחבה.

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

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

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

סטטוס	המסלול המתוכנן שלכם	תיאור
TOKEN_SUCCESSFULLY_APPLIED	כן	‫Navigation SDK החיל את טוקן המסלול.
TOKEN_APPLIED_WITH_LOCATION_MISMATCH	לא בהכרח	‫Navigation SDK לא הצליח לבנות מחדש את המסלול המתוכנן כי מיקום בבקשת המסלול היה במרחק של יותר מ-25 מטרים מהמיקום התואם בטוקן המסלול. ב-setDestinationsWithToken, המשמעות היא שהמכשיר היה במרחק של יותר מ-25 מטרים מנקודת המוצא בטוקן המסלול. המסלול עדיין מוביל ליעדים, אבל ה-Navigation SDK לא יכול לאשר שהוא משתמש באפשרויות המסלול מהאסימון של המסלול, כמו הימנעות מכבישי אגרה.
TOKEN_IGNORED_OTHER	לא בהכרח	ה-Navigation SDK לא הצליח לבנות מחדש את המסלול המתוכנן מסיבה אחרת, למשל כי כביש במסלול המתוכנן סגור. המסלול עדיין מוביל ליעדים, אבל ה-Navigation SDK לא יכול לאשר שהוא משתמש באפשרויות המסלול מהאסימון של המסלול, כמו הימנעות מכבישי אגרה.
NO_TOKEN_PROVIDED	לא רלוונטי	בקשת המסלול לא כללה אסימון מסלול.
UNKNOWN	לא ידוע	הסטטוס לא ידוע.

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

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

הפונקציה getResolvedParameters מחזירה אובייקט RouteTokenResolvedParameters, או null אם אפשרויות הניתוב לא זמינות. ‫RouteTokenResolvedParameters כולל את השיטות הבאות:

• ‫getTravelMode: אופן הנסיעה במסלול, למשל RoutingOptions.TravelMode.DRIVING. ‫Navigation SDK מדווח גם על RoutingOptions.TravelMode.DRIVING כשהמסלול משתמש באמצעי נסיעה שאין לו ערך תואם, או כשאמצעי הנסיעה לא זמין.
• ‫getAvoidTolls: אם המסלול נמנע מכבישי אגרה.
• ‫getAvoidHighways: אם המסלול עוקף כבישים מהירים.
• ‫getAvoidFerries: אם המסלול עוקף מעבורות.

דוגמה

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

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

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

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

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

• מבטל את כל היעדים שהוגדרו קודם.

• משתמש במיקום ההתחלה של הרכב.

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

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

  • RoutingOptions.avoidHighways
  • RoutingOptions.avoidTolls
  • RoutingOptions.avoidFerries
  • Navigator.setLicensePlateRestrictionInfo
  • אמצעי ההגעה שמוגדר באפליקציה

• פועלת לפי ההגדרות האלה כשהיא מחשבת או משנה את המסלול:

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

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