מעקב אחר משלוח

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

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

הגדרת מפה

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

טעינת מפה חדשה באמצעות Google Maps JavaScript API

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

  • הפרמטר callback מריץ את הפונקציה initMap אחרי שה-API נטען.
  • המאפיין defer מאפשר לדפדפן להמשיך לעבד את שאר הדף בזמן שה-API נטען.

משתמשים בפונקציה initMap כדי ליצור מופע של Consumer SDK. לדוגמה:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

טעינת מפה קיימת

אפשר גם לטעון מפה קיימת שנוצרה באמצעות Google Maps JavaScript API, כמו מפה שכבר נמצאת בשימוש.

לדוגמה, נניח שיש לכם דף אינטרנט עם ישות google.maps.Map רגילה שמוצג בה סמן, כפי שמוגדר בקוד ה-HTML הבא. כך מוצגת המפה באמצעות אותה פונקציה initMap בקריאה החוזרת בסוף:

    <!DOCTYPE html>
    <html>
      <head>
        <style>
           /* Set the size of the div element that contains the map */
          #map {
            height: 400px;  /* The height is 400 pixels */
            width: 100%;  /* The width is the width of the web page */
           }
        </style>
      </head>
      <body>
        <h3>My Google Maps Demo</h3>
        <!--The div element for the map -->
        <div id="map"></div>
        <script>
        // Initialize and add the map
        function initMap() {
          // The location of Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // The map, initially centered at Mountain View, CA.
          var map = new google.maps.Map(document.getElementById('map'));
          map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});

          // The marker, now positioned at Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * The callback parameter executes the initMap() function.
        -->
        <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
        </script>
      </body>
    </html>

יצירת מופע של ספק מיקום המשלוח

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

הדוגמאות הבאות מראות איך ליצור מופע של ספק המיקום.

JavaScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

TypeScript

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

הצגת המסלול המשותף

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

טיפים:

  1. מוודאים שהדף מכיל רכיב <div> שמכיל את תצוגת המפה. בדוגמה הבאה, הרכיב <div> נקרא map_canvas.

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

הדוגמאות הבאות מראות איך לאתחל תצוגת מפה.

JavaScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

TypeScript

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // Any undefined styling options will use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts as soon as this is set.
  locationProvider.trackingId = 'your-tracking-id';

  // Give the map an initial viewport to allow it to
  // initialize; otherwise the 'ready' event above may
  // not fire. The user also has access to the mapView
  // object to customize as they wish.
  mapView.map.setCenter({lat: 37.2, lng: -121.9});
  mapView.map.setZoom(14);
}

עדכון התקדמות המשלוח

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

  • זמן הגעה משוער
  • מספר התחנות שנותרו
  • המרחק שנותר עד לאיסוף או למסירה

בדוגמה הבאה אפשר לראות איך להאזין לאירועי השינוי האלה.

JavaScript

locationProvider.addListener('update', e => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  // e.taskTrackingInfo contains data that may be useful
  // to the rest of the UI.
  console.log(e.taskTrackingInfo.remainingStopCount);
});

הצגת קריטריונים למספר משימות

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

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

קריטריונים למשימות תוצאה
פתיחת משימות איסוף
קיים בדיוק אחד הצגת המשימה
יש כמה שגיאה ביצירה
משימות איסוף סגורות
קיים בדיוק אחד הצגת המשימה
יש כמה (בחלק מהם יש זמני תוצאות) הצגת המשימה עם זמן התוצאה האחרון
יש כמה אירועים (לאף אחד מהם אין זמני תוצאה) שגיאה ביצירה
משימות פתוחות של מסירה
קיים בדיוק אחד הצגת המשימה
יש כמה שגיאה ביצירה
משימות מסירה סגורות
קיים בדיוק אחד הצגת המשימה
יש כמה (בחלק מהם יש זמני תוצאות) הצגת המשימה עם זמן התוצאה האחרון
יש כמה אירועים (לאף אחד מהם אין זמני תוצאה) שגיאה ביצירה

הפסקת המעקב אחרי משלוח

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

הסרת המזהה לצורכי מעקב

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

הסרת ספק המיקום מתצוגת המפה

בדוגמה הבאה מוסבר איך להסיר ספק מיקום מתצוגת המפה.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

טיפול בשגיאות במעקב אחר משלוחים

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

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

הערה: חשוב לעטוף את הקריאות לספרייה בבלוקים של try...catch כדי לטפל בשגיאות לא צפויות.

המאמרים הבאים