סקירה כללית של הנתיב ב-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 דרך ה-Deliveries API. אפשר לספק את התוכנה דרך ממשקי ה-API ב-DriverSDK (DeliveryDriverApi) או ישירות ב-Fleet Engine.

שלבי ההטמעה

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

  • יש לכם אפליקציה קיימת ל-Android שכבר שולבה עם Driver 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. ה-Route Overview 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();