מעקב אחר הצי שלך באמצעות ספריית המעקב של המאגר של JavaScript

הספרייה למעקב אחר צי JavaScript מאפשרת להציג באופן חזותי את המיקומים של כלי הרכב בצים שלהם כמעט בזמן אמת. הספרייה משתמשת ב-Deliveries API כדי להציג תצוגה חזותית של כלי רכב למשלוחים וגם משימות. בדומה לספריית המעקב אחר משלוחים ב-JavaScript, היא מכילה רכיב מפה של JavaScript שמחליף את 'הצורך' בישות google.maps.Map רגילה ורכיבי נתונים שאפשר להתחבר אל Fleet Engine.

רכיבים

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

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

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

ספקי מיקום

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

ספק מיקום הרכב למשלוח

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

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

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

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

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

רכבי משלוח

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

סמני מיקום של משימות

תחנות מתוכננות של רכבים מוצגות במפה כסמני עצירה של רכבים. הסמנים למשימות שהושלמו מוצגים בסגנון שונה מהסגנון של עצירות הביניים המתוכננות ברכב.

המיקום של תוצאות המשימה מוצג עם הסמנים של תוצאות המשימה. משימות עם תוצאה מסוג {2}ברשת מוצגות עם סמני משימה שהצליחו, ואילו כל שאר המשימות מוצגות עם סמני משימה שנכשלים.

תחילת העבודה עם ספריית המעקב של Fleet ב-JavaScript

לפני שמשתמשים ב-JavaScript Fleet Tracking Library, חשוב להכיר את Fleet Engine ולהבין איך מקבלים מפתח API. לאחר מכן יוצרים מזהה משימה והצהרת בעלות על מזהה הרכב למשלוח.

יצירת מזהה משימה והצהרה על מזהה הרכב למשלוח

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

כדי ליצור את המטען הייעודי (payload) של JWT, מוסיפים הצהרה בקטע ההרשאה עם המפתחות taskid ו-deliveryvehicleid, ומגדירים את הערך של כל מפתח ל-*. את האסימון צריך ליצור באמצעות תפקיד ה-IAM של Fleet Engine Service Super User. שימו לב שמעניקים גישה רחבה ליצירה, לקריאה ולשינוי של ישויות ב-Fleet Engine, וצריך לשתף אותו רק עם משתמשים מהימנים.

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

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "taskid": "*",
     "deliveryvehicleid": "*",
   }
}

יצירת שליפת אסימון אימות

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

המאחזר צריך להחזיר מבנה נתונים עם שני שדות, שמוקף בהבטחה:

• מחרוזת token.
• מספר expiresInSeconds. התוקף של האסימון יפוג תוך פרק הזמן הזה אחרי השליפה.

ספריית המעקב של Fleet JavaScript מבקשת אסימון באמצעות מאחזר אסימוני האימות כשמתקיים אחד מהתנאים הבאים:

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

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

הדוגמה הבאה מציגה איך ליצור כלי לשליפה של אסימון אימות:

JavaScript

function authTokenFetcher(options) {
  // options is a record containing two keys called 
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
  };
}

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

• נקודת הקצה חייבת להחזיר מועד תפוגה של האסימון. בדוגמה שלמעלה, הוא מוגדר כ-data.ExpiresInSeconds.
• מאחזר אסימון האימות חייב להעביר את מועד התפוגה (בשניות, ממועד השליפה) לספרייה, כפי שמוצג בדוגמה.
• ה-server_TOKEN_URL תלוי בהטמעה של הקצה העורפי. אלה כתובות ה-URL של הקצה העורפי לדוגמה של האפליקציה:
  • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
  • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
  • https://SERVER_URL/token/fleet_reader

טעינת מפה מ-HTML

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

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

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

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

יצירת אובייקטים של ספק מיקום של רכב למשלוחים

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

JavaScript

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

          // Optionally, you may specify 
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-id',
});

TypeScript

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

          // Optionally, you may specify
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-id',
});

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

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

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// 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 wish.
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],
  // Styling customizations; see below.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// 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 wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

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

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

JavaScript

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

TypeScript

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

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

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

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

הפסקת מעקב

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

JavaScript

locationProvider.deliveryVehicleId = '';

TypeScript

locationProvider.deliveryVehicleId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

הצגת צי משלוחים

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

יצירת אובייקט של ספק מיקום של צי משלוחים

ספריית המעקב אחר Fleet JavaScript מגדירה מראש ספק מיקום שמאחזר מספר כלי רכב מ-FleetEngine Deliveries API. תוכלו להשתמש במזהה הפרויקט שלכם וגם בהפניה למאחזר האסימון כדי ליצור אותו.

JavaScript

locationProvider =
    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"',
        });

TypeScript

locationProvider =
    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"',
        });

deliveryVehicleFilter מציין שאילתה שמשמשת לסינון כלי רכב שמוצגים במפה. המסנן הזה מועבר ישירות אל Fleet Engine. ב-ListDeliveryVehiclesRequest.filter תוכלו לראות את הפורמטים הנתמכים.

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

לאחר בניית ספק המיקום, מאתחלים את תצוגת המפה.

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

אפשר להגדיר את הגבולות של 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;
    }
  });

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

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

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

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

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

הפסקת מעקב

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

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

מעקב אחר רכב משלוח תוך כדי צפייה בצי משלוחים

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

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

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

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

התאמה אישית של העיצוב והסגנון של המפה הבסיסית

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

שימוש בעיצוב מפות מבוסס-ענן

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

JavaScript

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

TypeScript

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

שימוש בעיצוב מפה מבוסס-קוד

דרך נוספת להתאמה אישית של עיצוב המפה היא להגדיר את mapOptions כשיוצרים את JourneySharingMapView.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

שימוש בהתאמה אישית של סמנים

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

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

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

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

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

הספרייה Fleet Tracking מספקת את הפרמטרים הבאים להתאמה אישית:

• FleetEngineDeliveryVehicleLocationProviderOptions
  • deliveryVehicleMarkerCustomization
  • plannedStopMarkerCustomization
  • taskMarkerCustomization
  • taskOutcomeMarkerCustomization
• FleetEngineDeliveryFleetLocationProviderOptions
  • deliveryVehicleMarkerCustomization

שינוי הסגנון של הסמנים באמצעות MarkerOptions

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

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

שינוי העיצוב של הסמנים באמצעות פונקציות של התאמה אישית

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

הוספת טיפול בקליקים לסמנים

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

סינון של הסמנים הגלויים

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

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

בעזרת ספריית המעקב אחר Fleet ב-JavaScript תוכלו גם להתאים אישית את המראה והסגנון של המסלול של הרכב שבמעקב במפה. הספרייה יוצרת אובייקט google.maps.Polyline לכל צמד קואורדינטות בנתיב הפעיל או שנותר ברכב. ניתן לעצב את האובייקטים Polyline על ידי ציון התאמות אישיות של קווים פוליגוניים. לאחר מכן הספרייה מחילה את ההתאמות האישיות האלה בשני מצבים: לפני הוספת האובייקטים למפה וכשהנתונים שמשמשים בשביל האובייקטים משתנים.

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

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

אפשר לציין את ההתאמות האישיות באמצעות הפרמטרים שצוינו ב-FleetEngineDeliveryVehicleLocationProviderOptions. תוכלו להגדיר התאמות אישיות למצבי נתיב שונים במסע הרכב – כבר נסעתם, בנסיעה פעילה או שעדיין לא נסעתם. אלה הפרמטרים:

• takenPolylineCustomization, לנתיב שכבר עבר בו;
• activePolylineCustomization, לנתיב נסיעה פעיל;
• remainingPolylineCustomization, לנתיב שעדיין לא עברתם.

שינוי העיצוב של Polyline אובייקטים באמצעות PolylineOptions

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

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

שינוי העיצוב של Polyline אובייקטים באמצעות פונקציות של התאמה אישית

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

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: DeliveryVehiclePolylineCustomizationFunctionParams) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

שליטה בחשיפה של Polyline אובייקטים

כברירת מחדל, כל האובייקטים של Polyline גלויים. כדי להפוך אובייקט Polyline לבלתי נראה, מגדירים את המאפיין visible שלו:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

הצגת InfoWindow לסימון רכב או מיקום

תוכלו להשתמש ב-InfoWindow כדי להציג מידע נוסף על רכב או סמן מיקום.

הדוגמה הבאה ממחישה איך ליצור InfoWindow ולצרף אותו לסמן של הרכב.

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 2. Attach the info window to a vehicle marker.   
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 2. Attach the info window to a vehicle marker.   
    // This property can return multiple markers.
    const marker = mapView.vehicleMarkers[0];
    infoWindow.open(mapView.map, marker);
  }
});

// 3. Close the info window.
infoWindow.close();

השבתת התאמה אוטומטית

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

JavaScript

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

TypeScript

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

החלפה של מפה קיימת

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

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

<!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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, map: map});
}
    </script>
    <!-- Load the API from the specified URL.
       * The async attribute allows the browser to render the page while the API loads.
       * The key parameter will contain your own API key (which is not needed for this tutorial).
       * 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>

כדי להוסיף את הספרייה 'שיתוף מסלול' ב-JavaScript, שכוללת את 'מעקב אחר ציים':

1. צריך להוסיף קוד למפעל של אסימון האימות.
2. מפעילים ספק מיקום בפונקציה initMap().
3. אפשר לאתחל את תצוגת המפה בפונקציה initMap(). התצוגה מכילה את המפה.
4. מעבירים את ההתאמה האישית לפונקציית הקריאה החוזרת של תצוגת המפה.
5. מוסיפים את ספריית המיקומים לטעינת ה-API.

בדוגמה הבאה מוצגים השינויים שצריך לבצע:

<!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>
let locationProvider;

// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
  // options is a record containing two keys called 
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
      if (!response.ok) {
        throw new Error(response.statusText);
      }
      const data = await response.json();
      return {
        token: data.Token,
        expiresInSeconds: data.ExpiresInSeconds
      };
}

// Initialize and add the map
function initMap() {
  // (2) Initialize location provider. Use FleetEngineDeliveryVehicleLocationProvider
  // as appropriate.
  locationProvider = new google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProvider({
    YOUR_PROVIDER_ID,
    authTokenFetcher,
  });

  // (3) Initialize map view (which contains the map).
  const mapView = new google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map'),
    locationProviders: [locationProvider],
    // any styling options
  });

mapView.addListener('ready', () => {
  locationProvider.deliveryVehicleId = DELIVERY_VEHICLE_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, map: map});
  };
}
    </script>
    <!-- Load the API from the specified URL
      * The async attribute allows the browser to render the page while the API loads
      * The key parameter will contain your own API key (which is not needed for this tutorial)
      * The callback parameter executes the initMap() function
      *
      * (5) Add the journey sharing library to the API loader, which includes Fleet Tracking functionality.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

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