הצגת כלל המכשירים בארגון

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

במסמך הזה מפורטים הדברים שאפשר לעשות כשצופים בצי:

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

התחלת מעקב אחרי הצי

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

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

ספריית JavaScript למעקב אחר צי רכבים כוללת ספק מיקום שמחלץ כמה כלי רכב מ-Fleet Engine.

כדי ליצור מופע של האובייקט, מבצעים את השלבים הבאים:

1. משתמשים במזהה הפרויקט וגם בהפניה לכלי לאחזור אסימונים.

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

   • בשירותים על פי דרישה, משתמשים ב-vehicleFilter ומעיינים במאמר ListVehiclesRequest.filter
   • למשימות מתוזמנות, משתמשים ב-deliveryVehicleFilter ובודקים את ListDeliveryVehiclesRequest.filter

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

4. אתחול תצוגת המפה.

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

נסיעות על פי דרישה

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

משימות מתוזמנות

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately make the location provider active.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately make the location provider active.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

כדי להגדיר את locationRestriction אחרי ה-constructor, מוסיפים את locationProvider.locationRestriction בהמשך הקוד כמו בדוגמה הבאה של JavaScript.

הערה: הדוגמה היא למשימות מתוזמנות, אבל כדי לעשות את זה לנסיעות לפי דרישה, צריך להשתמש רק ב-google.maps.journeySharing.FleetEngineFleetLocationProvider.

   // You can choose to not set locationRestriction in the constructor.
   // In this case, the location provider *DOES NOT START* after this line, because
   // no locationRestriction is set.
   locationProvider = new google.maps.journeySharing.DeliveryFleetLocationProvider({
   ... // not setting locationRestriction here
   });

   // You can then set the locationRestriction *after* the constructor.
   // After this line, the location provider is active.
   locationProvider.locationRestriction = {
     north: 1,
     east: 2,
     south: 0,
     west: 1,
   };

הגדרת הגבלת מיקום באמצעות אזור התצוגה במפה

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

נסיעות על פי דרישה

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

משימות מתוזמנות

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location provider will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location provider will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

הפעלת תצוגת המפה

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

אחרי טעינת ספריית שיתוף המסלול ב-JavaScript, מאתחלים את תצוגת המפה ומוסיפים אותה לדף ה-HTML. הדף צריך להכיל רכיב <div> שמכיל את תצוגת המפה. רכיב <div> נקרא map_canvas בדוגמאות הבאות.=

נסיעות על פי דרישה

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-vehicle-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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.VehicleId
                        = 'your-vehicle-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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

משימות מתוזמנות

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-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 want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

האזנה לאירועים וטיפול בשגיאות

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

האזנה לאירועי שינוי

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

פרטים נוספים זמינים במאמרים הבאים:

• טבלת הסבר לאפשרויות של כלי רכב לנסיעות על פי דרישה
• הסבר על אפשרויות של משימות מתוזמנות לרכבים

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

נסיעות על פי דרישה

JavaScript

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

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineFleetLocationProviderUpdateEvent) => {
  // e.vehicles contains data that may be
  // useful to the rest of the UI.
  if (e.vehicles) {
    for (vehicle of e.vehicles) {
      console.log(vehicle.navigationStatus);
    }
  }
});

משימות מתוזמנות

JavaScript

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

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryFleetLocationProviderUpdateEvent) => {
  // e.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

האזנה לשגיאות

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

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

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);
});

הפסקת המעקב אחר צי הרכבים

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

הגדרת הגבולות של ספק המיקום ל-null

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

נסיעות על פי דרישה

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

משימות מתוזמנות

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

מעקב אחרי רכב משלוחים בזמן צפייה בצי רכבי משלוחים

אם אתם משתמשים בשירותי Mobility למשימות מתוזמנות, אתם יכולים לראות את צי הרכב ולהציג את המסלול ואת המשימות הקרובות של רכב מסירה ספציפי באותה תצוגת מפה. כדי לעשות את זה, צריך ליצור מופע של Delivery Fleet Location Provider וגם של Delivery Vehicle Location Provider, ולהוסיף את שניהם לתצוגת המפה. אחרי שיוצרים מופע של ספק המיקום של צי המשלוחים, מתחילים לראות את רכבי המשלוחים במפה. בדוגמאות הבאות מוסבר איך ליצור מופע של שני ספקי המיקום:

JavaScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

TypeScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

שימוש בהתאמה אישית של סמנים כדי לעקוב אחרי רכב משלוחים

כדי לאפשר לספק המיקום של כלי המשלוח לעקוב אחרי כלי משלוח כשלוחצים על הסמן שלו בצי, פועלים לפי השלבים הבאים:

1. להתאים אישית סמן ולהוסיף פעולת לחיצה.

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

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

דוגמאות לשלבים האלה מופיעות בקטעים הבאים.

התאמה אישית של סמן והוספת פעולת לחיצה

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params: google.maps.journeySharing.DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

הסתרת הסמן כדי למנוע כפילויות

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

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params: deliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

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

• הגדרת סגנון למפה