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

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

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

הגדרת מפה

כדי לעקוב אחרי איסוף או משלוח של חבילה באפליקציית האינטרנט, צריך לטעון מפה וליצור מופע של 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
  });

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

כדי להציג את ההתקדמות של משימה מתוזמנת, צריך לאתחל את התצוגה שלה, וכך להגדיר את המסגרת של המפה כך שתתאים למיקום של המסלול המעקב. לאחר מכן, ה-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);
});

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

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

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

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

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

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

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

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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 כדי לטפל בשגיאות לא צפויות.

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