این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

برای ایجاد یک نقشه جدید، Google Maps JavaScript API را در برنامه وب خود بارگیری کنید. مثال زیر نحوه بارگیری Google Maps JavaScript API، فعال کردن 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>

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

همچنین می توانید نقشه موجود ایجاد شده توسط 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
  });

TypeScript

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

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

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

نکات :

اطمینان حاصل کنید که صفحه شما حاوی یک عنصر <div> است که نمای نقشه را نگه می دارد. در مثال زیر، عنصر <div> map_canvas نامگذاری شده است.
از قوانین دید پیش فرض که 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);
}

TypeScript

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 موارد زیر را ارائه می دهد:

ETA
تعداد توقف های باقی مانده
فاصله باقی مانده قبل از تحویل یا تحویل

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

جاوا اسکریپت

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

نمایش معیارها برای چندین کار

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

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

معیارهای وظیفه	نتیجه
وظایف پیکاپ را باز کنید
دقیقا یکی وجود دارد	وظیفه را نشان دهید
چندگانه وجود دارد	خطا ایجاد کنید
وظایف تحویل بسته
دقیقا یکی وجود داره	کار را نشان دهید
وجود چندگانه (برخی با زمان نتیجه)	نمایش کار با آخرین زمان نتیجه
وجود چندگانه (هیچکدام با زمان نتیجه)	خطا ایجاد کنید
باز کردن وظایف تحویل
دقیقا یکی وجود داره	وظیفه را نشان دهید
چندگانه وجود دارد	خطا ایجاد کنید
وظایف تحویل بسته
دقیقا یکی وجود داره	وظیفه را نشان دهید
وجود چندگانه (برخی با زمان نتیجه)	نمایش کار با آخرین زمان نتیجه
وجود چندگانه (هیچکدام با زمان نتیجه)	خطا ایجاد کنید

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

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

شناسه ردیابی را حذف کنید

برای جلوگیری از ردیابی محموله توسط ارائه دهنده موقعیت مکانی، شناسه ردیابی را از ارائه دهنده موقعیت مکانی حذف کنید. مثال های زیر نحوه انجام این کار را نشان می دهد.

جاوا اسکریپت

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

ارائه دهنده موقعیت مکانی را از نمای نقشه حذف کنید

مثال زیر نحوه حذف ارائه دهنده موقعیت مکانی را از نمای نقشه نشان می دهد.

جاوا اسکریپت

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

رسیدگی به خطاهای ردیابی حمل و نقل

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

جاوا اسکریپت

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 تا خطاهای پیش‌بینی نشده را مدیریت کنید.

بعدش چی

به یک نقشه سبک دهید