דף זה תורגם על ידי Cloud Translation API.

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

אחרי שמגדירים את 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>

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

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

לדוגמה, נניח שיש לכם דף אינטרנט עם ישות 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.

טיפים:

מוודאים שהדף מכיל רכיב <div> שמכיל את תצוגת המפה. בדוגמה הבאה, שם הרכיב <div> הוא map_canvas.
חשוב לדעת מהם כללי ברירת המחדל של הרשאות הגישה שמערכת 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);

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

שגיאות שמתרחשות באופן אסינכרוני כתוצאה מהבקשה לקבלת פרטי המשלוח מפעילות אירועי 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 כדי לטפל בשגיאות בלתי צפויות.

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

התאמת סגנון למפה