پیگیری مرسوله

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

• مقداردهی اولیه نقشه و نمایش سفر هم‌رسانی‌شده
• به‌روزرسانی و دنبال کردن پیشرفت مسیر
• توقف دنبال کردن مرسوله
• رسیدگی به خطاهای پیگیری مرسوله

راه‌اندازی نقشه

برای دنبال کردن تحویل یا دریافت محموله در برنامه وب، باید نقشه‌ای را بار کنید و «کیت توسعه نرم‌افزار مصرف‌کننده» را نمونه‌سازی کنید تا ردیابی محموله شروع شود. می‌توانید نقشه جدیدی بار کنید یا از نقشه موجود استفاده کنید. سپس از تابع مقداردهی اولیه برای نمونه‌سازی Consumer SDK استفاده می‌کنید تا نمای نقشه با مکان موردی که ردیابی می‌شود مطابقت داشته باشد.

بار کردن نقشه جدید بااستفاده از Google Maps JavaScript API

برای ایجاد نقشه جدید، Google Maps JavaScript API را در برنامه وب خود بار کنید. مثال زیر نشان می‌دهد که چگونه Google Maps JavaScript API را بار کنید، کیت توسعه نرم‌افزار را فعال کنید، و بررسی مقداردهی اولیه را راه‌اندازی کنید.

• پارامتر callback تابع initMap را پس‌از بار شدن API اجرا می‌کند.
• مشخصه defer به مرورگر اجازه می‌دهد تا درحین بار شدن میانای برنامه‌سازی کاربردی، به رندر کردن بقیه صفحه ادامه دهد.

از تابع initMap برای نمونه‌سازی Consumer SDK استفاده کنید. برای مثال:

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

بار کردن نقشه موجود

همچنین می‌توانید نقشه موجودی را که توسط Google Maps JavaScript API ایجاد شده است بار کنید، مثلاً نقشه‌ای که قبلاً استفاده کرده‌اید.

برای مثال، فرض کنید صفحه وبی با موجودیت استاندارد google.maps.Map دارید که در آن نشانگری مطابق با تعریف کد HTML زیر نشان داده شده است. این نقشه شما را بااستفاده از همان تابع initMap در فراخوانی در پایان نشان می‌دهد:

    <!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 Pier 39 in San Francisco
          var pier39 = {lat: 37.809326, lng: -122.409981};
          // 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 Pier 39
          var marker = new google.maps.Marker({position: pier39, map: map});
        }
        </script>
        <!-- Load the API from the specified URL.
           * The defer attribute allows the browser to render the page while the API loads.
           * The key parameter contains your own API key.
           * 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>

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

از ارائه‌دهنده مکان محموله، همراه با واکِشنده توکن مجوز که قبلاً تعریف کرده‌اید، برای شروع دریافت داده از Fleet Engine استفاده کنید.

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

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

نمایش سفر هم‌رسانی‌شده

برای نمایش پیشرفت تکلیف زمان‌بندی‌شده، نمای آن را مقداردهی اولیه کنید که قاب نقشه را برای مطابقت با مکان سفر ردیابی‌شده تنظیم می‌کند. سپس «کیت توسعه نرم‌افزار مصرف‌کننده» پس‌از دریافت اطلاعات از «موتور ناوگان»، پیشرفت را ارائه می‌دهد.

نکات:

1. مطمئن شوید صفحه‌تان حاوی عنصر <div> باشد که نمای نقشه را نگه می‌دارد. در مثال زیر، عنصر <div> با نام map_canvas مشخص شده است.

2. از قوانین رؤیت‌پذیری پیش‌فرضی که Fleet Engine برای سفرهای ردیابی‌شده اعمال می‌کند آگاه باشید. همچنین می‌توانید قوانین رؤیت‌پذیری را برای ارسال فعال خودرو و تکالیف توقف زمان‌بندی‌شده پیکربندی کنید. به سفارشی‌سازی رؤیت‌پذیری تکلیف در راهنمای پیکربندی تکالیف مراجعه کنید.

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

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
    // Any undefined styling options use defaults.
  });

  // If you did not specify a tracking ID in the location
  // provider constructor, you may do so here.
  // Location tracking starts 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);
}

function initMap() {
  const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
    element: document.getElementById('map_canvas'),
   // 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 starts 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);
}

به‌روزرسانی پیشرفت ارسال کالا

می‌توانید رویدادها را گوش دهید و پیشرفت محموله را با پیشرفت سفر به‌روز کنید. از ارائه‌دهنده مکان برای بازیابی اطلاعات متا از شیء taskTrackingInfo استفاده کنید. تغییرات در اطلاعات متا باعث راه‌اندازی رویداد به‌روزرسانی می‌شود. شیء taskTrackingInfo موارد زیر را ارائه می‌دهد:

• زمان تقریبی ورود
• تعداد توقف‌های باقی‌مانده
• مسافت باقی‌مانده تا تحویل یا ارسال

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

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

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

نمایش معیارهای چند تکلیف

«کیت توسعه نرم‌افزار مصرف‌کننده» برای کارهای زمان‌بندی‌شده فقط یک کار به‌ازای هر شناسه پیگیری را روی نقشه نشان می‌دهد. بااین‌حال، معمولاً یک شناسه رهگیری را به یک کالای ارسالی خاص اختصاص می‌دهید که درطول سفرش در سیستم شما با آن کالا مرتبط می‌ماند. این یعنی یک شناسه ردگیری ممکن است با چندین تکلیف مرتبط باشد، مثلاً تکلیف تحویل گرفتن و به‌دنبال آن تکلیف تحویل دادن برای یک بسته، یا چندین تکلیف ارسال ناموفق برای یک بسته.

برای مدیریت این وضعیت، Fleet Engine معیارهایی را برای نمایش تکالیف اعمال می‌کند، که در جدول زیر نشان داده شده است.

توقف دنبال کردن مرسوله

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

برداشتن شناسه ردیابی

برای اینکه ارائه‌دهنده مکان دیگر محموله را ردیابی نکند، شناسه ردیابی را از ارائه‌دهنده مکان بردارید. مثال‌های زیر نحوه انجام این کار را نشان می‌دهد.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

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

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

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

رسیدگی به خطاهای پیگیری مرسوله

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

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

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

توجه: حتماً فراخوانی‌های کتابخانه را در بلوک‌های try...catch قرار دهید تا خطاهای پیش‌بینی‌نشده را مدیریت کنید.

قدم بعدی چیست

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