סקירה כללית של הנתיב ב-API

ה-Route Overview API הוא מוצר של Last Mile Fleet Solution שמבוסס על DriverSDK. שם אפשר לאחזר את פרטי המסלול של רכב נתון, כאחזור חד-פעמי או ברציפות באמצעות שימוש ב-listener לעדכונים. Route Overview API תומך בסוגי המידע הבאים:

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

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

דרישות מוקדמות

  • צריך להפעיל את האפליקציה ל-Android באמצעות גרסת אלפא ערוץ של DriverSDK מגרסה 4.1.0 ואילך . ערוץ האלפא זמין באמצעות transportation-driver-alpha כארטיפקט מזהה של Maven.
  • ה-API משתמש בפרטי המסלול שמסופקים על ידי Fleet Engine דרך ממשק API לאספקה. אפשר לספק את ההוראות האלה דרך ממשקי ה-API ב-DriverSDK. (DeliveryDriverApi) או ישירות אל Fleet Engine.

שלבי ההטמעה

בקטע הזה מתוארים השלבים הבסיסיים שדרושים לשילוב האפליקציה לנהג/ת ל-Android באמצעות ה-API. ההנחיות האלה מבוססות על ההנחות הבאות:

  • יש לך אפליקציה קיימת ל-Android שכבר שולבה עם SDK לנהג
  • הפעלת את DeliveryDriverApi באפליקציה עם הקשר שאפשר למצוא

צפייה תחילת העבודה עם Driver SDK ל-Android לקבלת פרטים.

שלב 0 – הגדרת המסלול

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

כדי לטעון את פרטי העצירה והמשימה ל-Fleet Engine, צריך רכב משלוח שהוקצה למסלול חוקי. הסיבה לכך היא של-Rout Overview API נדרש אימות כדי לאחזר נתונים. מסלולים חוקיים מורכבים מסדרה של ציוני דרך ועצירות, וכן עצירה יכולה להתקיים רק אם יש לה לפחות עצירה אחת למשימה הזו. לצפייה מדריך השילוב שלFleet Engine API אפשר לקבל מידע נוסף.

שלב 1 – אתחול ה-API

אחרי שיוצרים מסלול תקין עם עצירות ומשימות משויכות, אפשר להפעיל את Route Overview API. האתחול מספק את ה-framework שנדרש לחיבור בין Fleet Engine לבין ה-API. המסלול ממשקי ה-API של הסקירה הכללית צריכים להיות מופעלים עם אותו אובייקט הקשר שבו השתמשתם כדי מאתחלים את DeliveryDriverApi ב-DriverSDK, כי האובייקט מתייחס אותו מזהה רכב שהוגדר קודם לכן באובייקט DriverContext. הבאים דוגמה שממחישה איך ליצור מכונה של RouteOverviewApi.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

שלב 2 – רושמים רכב לאירועים של שינוי מסלול

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

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


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

שלב 3 – מפעילים את ה-API

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

vehicleRouteOverview.setRouteOverviewEnabled(true);

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

שלב 4 – משרטטים את המסלול במפות Google

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

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

צילום מסך שמציג תמונה של סקירה כללית של המסלול

התוצאה תהיה תצוגה שדומה לצילום המסך שמשמאל:

שלב 5 – קבלת תמונת מצב של המסלול

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

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

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

שלב 6 – הסרת המשאבים

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

הסרה של אוזן אירוע ספציפי

צריך להסיר האזנה לאירועים כשמאזינים ספציפיים כבר לא הנחוצים.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

ניקוי כל פונקציות event listener

כחלק משגרת הניקוי, אפשר להסיר בבת אחת את כל פונקציות ה-event listener השונות שנרשמו.

vehicleRouteOverview.clearEventListeners();

ניקוי מופע של Route Overview API

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

vehicleRouteOverview.clearInstance();