ה-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();