مشاهده ناوگان

این بخش نحوه استفاده از کتابخانه ردیابی ناوگان جاوا اسکریپت را برای مشاهده ناوگان نشان می‌دهد. این رویه‌ها فرض می‌کنند که کتابخانه ردیابی ناوگان را راه‌اندازی کرده‌اید و نقشه‌ای را بار کرده‌اید. برای جزئیات، به راه‌اندازی کتابخانه ردیابی ناوگان جاوا اسکریپت مراجعه کنید.

این سند درباره کارهایی که می‌توانید هنگام مشاهده ناوگان انجام دهید بحث می‌کند:

1. ردگیری ناوگان را شروع کنید.
2. به رویدادها گوش دهید و خطاها را مدیریت کنید.
3. توقف ردیابی.
4. ردیابی یک خودرو درحین مشاهده ناوگان.

شروع ردیابی ناوگان

برای ردیابی ناوگان، باید ارائه‌دهنده مکان ناوگان را نمونه‌سازی کنید و محدودیت‌های مکان را برای نمای نقشه همان‌طور که در بخش‌های زیر شرح داده شده است تنظیم کنید.

نمونه‌سازی ارائه‌دهنده مکان ناوگان

‫JavaScript fleet tracking library شامل یک ارائه‌دهنده مکان است که چندین وسیله نقلیه را از Fleet Engine واکشی می‌کند.

برای نمونه‌سازی آن، این مراحل را دنبال کنید:

1. از شناسه پروژه خود و همچنین مرجعی برای واکشی‌کننده کدتان استفاده کنید.

2. استفاده از پُرسمان فیلتر خودرو پُرسمان فیلتر خودرو کنترل می‌کند که کدام خودروها در نقشه نمایش داده شوند. فیلتر به Fleet Engine ارسال می‌شود.

   • برای سرویس‌های درخواستی، از vehicleFilter استفاده کنید و ListVehiclesRequest.filter را مرور کنید
   • برای تکالیف زمان‌بندی‌شده، از deliveryVehicleFilter استفاده کنید و ListDeliveryVehiclesRequest.filter را مرور کنید

3. محدوده نمایشگر خودرو را تنظیم کنید. از locationRestriction برای محدود کردن منطقه‌ای که خودروها در نقشه نمایش داده می‌شوند استفاده کنید. تا زمانی که این تنظیم انجام نشود، ارائه‌دهنده مکان فعال نیست. می‌توانید مرزهای مکان را در سازنده یا بعداز سازنده تنظیم کنید.

4. مقداردهی اولیه نمای نقشه.

نمونه‌های زیر نحوه نمونه‌سازی ارائه‌دهنده مکان ناوگان را برای سناریوهای وظیفه زمان‌بندی‌شده و درخواستی نشان می‌دهد. این مثال همچنین نشان می‌دهد که چگونه از locationRestriction در سازنده استفاده کنید تا ارائه‌دهنده مکان را فعال کنید.

سفرهای درخواستی

JavaScript

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

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

TypeScript

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

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

تکالیف زمان‌بندی‌شده

JavaScript

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

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

TypeScript

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

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

برای تنظیم locationRestriction بعداز سازنده، locationProvider.locationRestriction را بعداً در کدتان اضافه کنید، همان‌طور که در مثال جاوا اسکریپت زیر نشان داده شده است.

توجه: این مثال برای تکالیف زمان‌بندی‌شده است، اما برای انجام این کار برای سفرهای درخواستی، کافی است از google.maps.journeySharing.FleetEngineFleetLocationProvider استفاده کنید.

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

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

تنظیم محدودیت مکان بااستفاده از ناحیه نمایش نقشه

همچنین می‌توانید مرزهای locationRestriction را طوری تنظیم کنید که با منطقه‌ای که درحال‌حاضر در نمای نقشه قابل‌مشاهده است مطابقت داشته باشد.

سفرهای درخواستی

JavaScript

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

TypeScript

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

تکالیف زمان‌بندی‌شده

JavaScript

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

TypeScript

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

مقداردهی اولیه نمای نقشه

پس‌از ساختن ارائه‌دهنده مکان، نمای نقشه را به همان روشی که هنگام دنبال کردن یک وسیله نقلیه انجام می‌دهید، مقداردهی اولیه کنید.

پس‌از بار کردن کتابخانه «هم‌رسانی سفر» جاوا اسکریپت، نمای نقشه را مقداردهی اولیه کنید و آن را به صفحه HTML اضافه کنید. صفحه شما باید حاوی عنصر <div> باشد که نمای نقشه را نگه می‌دارد. عنصر <div> در مثال‌های زیر map_canvas نامیده می‌شود.=

سفرهای درخواستی

JavaScript

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

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

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

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.VehicleId
                        = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

تکالیف زمان‌بندی‌شده

JavaScript

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

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

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

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

گوش دادن به رویدادها و رسیدگی به خطاها

پس‌از شروع دنبال کردن ناوگان، باید تغییرات رویداد را گوش دهید و هر خطایی را که طبق بخش‌های زیر رخ می‌دهد مدیریت کنید.

گوش دادن به رویدادهای تغییر

می‌توانید اطلاعات متا درباره ناوگان را از شیء خودرو بااستفاده از ارائه‌دهنده مکان بازیابی کنید. تغییرات در اطلاعات متا باعث راه‌اندازی رویداد به‌روزرسانی می‌شود. اطلاعات متا شامل ویژگی‌های خودرو مانند وضعیت ناوبری، مسافت باقی‌مانده، و مشخصه‌های سفارشی است.

برای جزئیات، به موارد زیر مراجعه کنید:

• مرجع گزینه‌های خودرو سفرهای درخواستی
• مرجع گزینه‌های خودرو برای کارهای زمان‌بندی‌شده

مثال‌های زیر نشان می‌دهد که چگونه به این رویدادهای تغییر گوش دهید.

سفرهای درخواستی

JavaScript

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

TypeScript

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

تکالیف زمان‌بندی‌شده

JavaScript

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

TypeScript

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

گوش دادن به خطاها

همچنین باید به خطاهایی که هنگام دنبال کردن خودرو رخ می‌دهد گوش دهید و آن‌ها را مدیریت کنید. خطاهایی که به‌صورت ناهمگام از درخواست اطلاعات خودرو به‌وجود می‌آیند، رویدادهای خطا را راه‌اندازی می‌کنند.

مثال زیر نشان می‌دهد که چگونه به این رویدادها گوش دهید تا بتوانید خطاها را مدیریت کنید.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

توقف ردیابی ناوگان

برای توقف ردیابی ناوگان، حدود ارائه‌دهنده مکان را روی null تنظیم می‌کنید، و سپس ارائه‌دهنده مکان را از نمای نقشه برمی‌دارید، همان‌طور که در بخش‌های زیر شرح داده شده است.

تنظیم کردن مرزهای ارائه‌دهنده مکان روی null

برای متوقف کردن ردیابی ناوگان توسط ارائه‌دهنده مکان، مرزهای ارائه‌دهنده مکان را روی null تنظیم کنید.

سفرهای درخواستی

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

تکالیف زمان‌بندی‌شده

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

برداشتن ارائه‌دهنده مکان از نمای نقشه

مثال زیر نحوه برداشتن ارائه‌دهنده مکان را از نمای نقشه نشان می‌دهد.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

ردیابی خودرو تحویل هنگام مشاهده ناوگان تحویل

اگر از سرویس‌های Mobility برای کارهای زمان‌بندی‌شده استفاده می‌کنید، می‌توانید هم ناوگان را مشاهده کنید و هم مسیر و کارهای آتی را برای خودرو تحویل خاصی در همان نمای نقشه نمایش دهید. برای انجام این کار، هم «ارائه‌دهنده مکان ناوگان تحویل» و هم «ارائه‌دهنده مکان خودرو تحویل» را نمونه‌سازی کنید و هر دو را به نمای نقشه اضافه کنید. پس‌از نمونه‌سازی، ارائه‌دهنده مکان ناوگان تحویل شروع به نمایش وسایل نقلیه تحویل روی نقشه می‌کند. مثال‌های زیر نحوه نمونه‌سازی هر دو ارائه‌دهنده مکان را نشان می‌دهد:

JavaScript

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

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

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

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

TypeScript

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

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

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

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

استفاده از سفارشی‌سازی نشانگر برای ردگیری وسیله نقلیه تحویل

برای فعال کردن ارائه‌دهنده مکان خودرو تحویل کالا برای ردیابی خودرو تحویل کالا وقتی روی نشانگر ناوگان آن کلیک می‌کنید، این مراحل را دنبال کنید:

1. نشانگری را سفارشی‌سازی کنید و کنش کلیک اضافه کنید.

2. برای جلوگیری از نشانگرهای تکراری، نشانگر را پنهان کنید.

   توجه: ارائه‌دهنده مکان ناوگان تحویل مجموعه‌ای از نشانگرها را ارائه می‌دهد، یکی برای هر خودرو ردیابی‌شده. اگر می‌خواهید جزئیات یک وسیله نقلیه را وقتی کاربر روی آن وسیله نقلیه کلیک می‌کند نشان دهید، یک ارائه‌دهنده مکان وسیله نقلیه تحویل را نمونه‌سازی می‌کنید و شناسه وسیله نقلیه را روی همان شناسه‌ای که کاربر روی آن کلیک کرده است تنظیم می‌کنید، همان‌طور که در مثال زیر نشان داده شده است. اما وقتی این کار را انجام می‌دهید، ارائه‌دهنده مکان خودرو تحویل نیز نشانگری برای این خودرو ارائه می‌دهد (همان‌طور که برای این کار طراحی شده است). بنابراین یکی از آن‌ها را پنهان می‌کنید تا دو نشانگر برای یک خودرو وجود نداشته باشد.

نمونه‌های این مراحل در بخش‌های زیر آمده است.

سفارشی‌سازی نشانگر و افزودن کنش کلیک

JavaScript

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

TypeScript

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

برای جلوگیری از نشانگرهای تکراری، نشانگر را پنهان کنید

نشانگر را از ارائه‌دهنده مکان خودرو تحویل پنهان کنید تا از ارائه دو نشانگر برای یک خودرو جلوگیری شود:

JavaScript

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

TypeScript

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

قدم بعدی چیست

• سبک‌دار کردن نقشه