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

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

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