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

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

רכיבים

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

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

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

ספקי מיקום

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

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

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

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

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

שליטה בחשיפה של מיקומים במעקב

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

משלוחי רכב

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

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

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

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

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

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

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

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

כדי ליצור את המטען הייעודי (payload) של JWT, מוסיפים הצהרה נוספת בקטע ההרשאה עם המפתחות taskid ו-deliveryvehicleid, ומגדירים את הערך של כל מפתח ל-*. כדי ליצור את האסימון באמצעות התפקיד Fleet Engine Service Super User ב-Cloud IAM, צריך ליצור את האסימון. שימו לב: ההרשאה הזו מעניקה גישה רחבה ליצירה, לקריאה ולשינוי של ישויות 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": "*",
   }
}

יצירת מאחזר אסימון אימות

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

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

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

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

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

ה-JavaScript Fleet Tracking Library מגדיר מראש ספק מיקום ל-Feet 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 Share, הפעילו את תצוגת המפה והוסיפו אותה לדף ה-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 באמצעות ספק המיקום. המטא-נתונים כוללים את זמן ההגעה המשוער ואת המרחק שנשאר לפני האיסוף או ההמראה הבאים של הרכב. שינויים במטא-מידע גורמים להפעלה של אירוע עדכון. הדוגמה הבאה ממחישה איך להאזין לאירועי השינוי האלה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

באופן דומה, אפשר לציין פונקציית התאמה אישית. פונקציות של התאמה אישית מאפשרות לעצב את האובייקטים באופן אינדיבידואלי על סמך נתונים שנשלחים על ידי Fleet Engine. הפונקציה יכולה לשנות את הסגנון של כל אובייקט על סמך מצב הרכב הנוכחי. לדוגמה, צבע את האובייקט Polyline בגוון עמוק יותר, או הפיכתו לעבה יותר כשהרכב נע לאט יותר. תוכלו אפילו להצטרף כנגד מקורות מחוץ ל-Feet 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 Journey Sharing, שכוללת את המעקב אחר Fleet:

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>

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