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

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

רכיבים

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

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

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

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

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

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

  • היעד לאיסוף או למשלוח של המשלוח.
  • המיקום והמסלול של רכב המשלוחים.

אובייקטים של מיקום במעקב

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

מיקום היעד

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

מיקום הרכב

מיקום הרכב הוא המיקום של הרכב במעקב. אם תרצו, כוללים מסלול לרכב.

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

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

אפשרויות עיצוב

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

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

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

  • סמן מיקום
  • נתוני המשימה

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

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

הרשאות גישה לנתונים של המשימה

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

  • משימות של חוסר זמינות -- לא ניתן להתאים אישית את הרשאות הגישה למשימות האלו.
  • משימות רכב פעילות – אפשר להתאים אישית את המשימות האלה.
  • משימות רכב לא פעילות – אי אפשר להתאים אישית את הרשאות הגישה למשימות האלה.

משימות של חוסר זמינות

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

משימות רכב פעילות

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

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

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

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

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

בהמשך מוצגת דוגמה להתאמה אישית. הכללים לביצוע התאמה אישית הם:

  • הצגת קווים פוליגוניים של המסלול אם הרכב נמצא בטווח של 3 עצירות ביניים.
  • הצגת זמן ההגעה המשוער אם מרחק הנסיעה הנותר קצר מ-5,000 מטרים.
  • אף פעם לא להציג את ספירת העצירות הנותרת.
  • כל אחד מהשדות שומר על ברירת המחדל של החשיפה, כלומר, כאשר הרכב נמצא ב-5 עצירות ביניים מהמשימה.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

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

קווים פוליגוניים וכללי חשיפת מיקום של רכבים:

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

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

  • לקווים פוליגוניים של נתיבים ולמיקום רכב יש אפשרות חשיפה זהה :type

    • אם אפשרות החשיפה נשארת ספירת העצירה, משך הזמן עד זמן ההגעה המשוער, או מרחק הנסיעה שנותר, קווים פוליגוניים של מסלולים חייבים לספק ערך נמוך יותר שווה לערך שהוגדר לאפשרות החשיפה הזו של הרכב או שווה לו המיקום. כך לדוגמה:
    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingStopCountThreshold": 5
      },
    }
    
    • אם לקווים פוליגוניים יש אפשרות חשיפה תמידית, מיקום הרכב חייבת גם לספק אפשרות חשיפה גלויה תמיד.
    • אם למיקום הרכב אין אפשרות חשיפה אף פעם, לנתב קווים פוליגוניים חייב לספק גם אפשרות חשיפה אף פעם.
  • כשיש אפשרות חשיפה שונה לקווים פוליגוניים ולמיקום הרכב שונים, מיקום הרכב גלוי רק כאשר שני החשיפה שלו כמה אפשרויות.

    כך לדוגמה:

    "taskTrackingViewConfig": {
      "routePolylinePointsVisibility": {
        "remainingStopCountThreshold": 3
      },
      "vehicleLocationVisibility": {
        "remainingDrivingDistanceMetersThreshold": 3000
      },
    }
    

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

תחילת העבודה עם ספריית השיתוף של התהליך ב-JavaScript

לפני השימוש ב-JavaScript Journey Share Library, יש לוודא להכיר את Fleet Engine באמצעות קבלת מפתח API.

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

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

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

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

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

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "trackingid": "tid_54321",
   }
}

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

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

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

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

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

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

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

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

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

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

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

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

אחרי שטוענים את ספריית Journey Sharing ב-JavaScript, מאתחלים את תצוגת המפה ומוסיפים אותה לדף ה-HTML. הדף צריך לכלול רכיב &lt;div&gt; ששומר את תצוגת המפה. בדוגמה הבאה, הרכיב &lt;div&gt; נקרא &lt;div&gt;.

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

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // 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 will start 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

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // 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 will start 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);

מזהה לצורכי מעקב

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

  1. אם יש רק משימה אחת של איסוף עצמי, היא תוצג. נוצרת שגיאה אם יש כמה משימות פתוחות לאיסוף.
  2. אם יש בדיוק משימה אחת של שליחה פתוחה, היא תוצג. שגיאה היא שנוצר אם יש כמה משימות של שליחה פתוחה.
  3. אם יש משימות של מסירה סגורה:
    • אם יש בדיוק משימה אחת של מסירה סגורה, היא תופיע.
    • אם יש כמה משימות של מסירה סגורה, זו המשימה האחרונה מוצגת התוצאה.
    • אם יש כמה משימות של מסירה שנסגרה, לאף אחת מהן אין תוצאה בזמן, נוצרת שגיאה.
  4. אם יש משימות שקשורות לאיסוף עצמי:
    • אם יש רק משימה אחת לאיסוף שנסגרה, היא תוצג.
    • אם יש כמה משימות שקשורות לאיסוף שנסגרו, זו המשימה האחרונה מוצגת התוצאה.
    • אם יש כמה משימות איסוף שנסגרו, לאף אחת מהן אין תוצאה בזמן, נוצרת שגיאה.
  5. אחרת, לא תוצג אף משימה.

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

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

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

טיפול בשגיאות

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

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

הפסקת מעקב

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

עיצוב מפות מבוסס-ענן מאפשר ליצור ולערוך סגנונות מפה לכל אחת מהאפליקציות שלך שמשתמשות במפות 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'
  }
  // Any other styling options.
});

TypeScript

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

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

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

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

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

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

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

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

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

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

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

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

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

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

JavaScript

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

TypeScript

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

שימוש בהתאמה אישית של קו פוליגוני

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

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

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

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

שינוי העיצוב של 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.taskTrackingInfo.remainingDrivingDistanceMeters;
    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: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    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});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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

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

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 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 כדי להחליף את העמודה מפה קיימת שכוללת סמנים או התאמות אישיות אחרות בלי לאבד את ההתאמות האישיות האלה.

לדוגמה, נניח שיש לך דף אינטרנט עם פרמטר 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 Share:

  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.
  locationProvider = new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
    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
  });

  locationProvider.trackingId = TRACKING_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.
    -->
    <script defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
    </script>
  </body>
</html>

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