یک محموله را دنبال کنید

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

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

نقشه تنظیم کنید

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

بارگذاری نقشه جدید با استفاده از API جاوا اسکریپت نقشه‌های گوگل

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

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

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

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

بارگذاری نقشه موجود

همچنین می‌توانید یک نقشه موجود که توسط API جاوا اسکریپت Google Maps ایجاد شده است، مانند نقشه‌ای که قبلاً از آن استفاده کرده‌اید، را بارگذاری کنید.

برای مثال، فرض کنید یک صفحه وب با موجودیت استاندارد 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
  });

نمایش سفر مشترک

برای نمایش پیشرفت یک وظیفه زمان‌بندی‌شده، نمای آن را مقداردهی اولیه کنید، که چارچوب نقشه را مطابق با موقعیت مکانی برای سفر ردیابی‌شده تنظیم می‌کند. سپس پیشرفت توسط Consumer SDK پس از دریافت اطلاعات از Fleet Engine ارائه می‌شود.

نکات :

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

نمایش معیارها برای چندین وظیفه

کیت توسعه نرم‌افزار مصرف‌کننده (CSDK) برای وظایف زمان‌بندی‌شده ، فقط یک وظیفه را به ازای هر شناسه ردیابی روی نقشه نشان می‌دهد. با این حال، شما معمولاً یک شناسه ردیابی را نیز به یک کالای حمل‌ونقل خاص اختصاص می‌دهید که در طول سفرش در سیستم شما با کالا مرتبط باقی می‌ماند. این بدان معناست که یک شناسه ردیابی واحد ممکن است با چندین وظیفه مرتبط باشد، مانند یک وظیفه برداشت و به دنبال آن یک وظیفه تحویل برای همان بسته، یا چندین وظیفه حمل‌ونقل ناموفق برای یک بسته.

برای مدیریت این وضعیت، 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 قرار دهید.

قدم بعدی چیست؟