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

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

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

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

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

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

שלבי ההטמעה

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

  • יש לכם אפליקציה ל-Android שכבר משולבת עם Driver SDK
  • אתחלתם את DeliveryDriverApi באפליקציה עם אובייקט הקשר שאפשר למצוא

פרטים נוספים זמינים במאמר תחילת העבודה עם Driver SDK ל-Android.

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

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

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

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

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


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

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

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

אירוע של שינוי מסלול מתרחש בכל פעם שמעדכנים את הנתיב לכל אחת מהתחנות שהוקצו לרכב, כשמסדרים מחדש עצירה או כש-Flet 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 – פינוי מקום

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

הסרת האזנה לאירוע ספציפי

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

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

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

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

vehicleRouteOverview.clearEventListeners();

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

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

vehicleRouteOverview.clearInstance();