متابعة شحنة

بعد إعداد حزمة تطوير البرامج (SDK) للمستهلكين في JavaScript للمهام المُجدوَلة، يمكنك تتبُّع شحنة باستخدام تطبيق المستهلك. يتناول هذا المستند الخطوات الرئيسية التالية في هذه العملية:

• بدء خريطة وعرض الرحلة المشتركة
• تعديل مستوى التقدّم في الرحلة ومتابعته
• إيقاف تتبُّع شحنة
• التعامل مع أخطاء تتبُّع الشحنات

إعداد خريطة

لمتابعة استلام شحنة أو تسليمها في تطبيق الويب، عليك تحميل خريطة وإنشاء مثيل لحزمة تطوير البرامج (SDK) للمستهلك لبدء تتبُّع شحنتك. يمكنك تحميل خريطة جديدة أو استخدام خريطة حالية. بعد ذلك، يمكنك استخدام دالة الإعداد لإنشاء مثيل من حزمة تطوير البرامج (SDK) للمستهلك لكي يتوافق عرض الخريطة مع الموقع الجغرافي للعنصر الذي يتم تتبُّعه.

تحميل خريطة جديدة باستخدام Google Maps JavaScript API

لإنشاء خريطة جديدة، حمِّل Google Maps JavaScript API في تطبيق الويب. يوضّح المثال التالي كيفية تحميل Google Maps JavaScript API وتفعيل حزمة تطوير البرامج (SDK) وتشغيل عملية التحقّق من الإعداد.

• تُشغّل المَعلمة callback الدالة initMap بعد تحميل واجهة برمجة التطبيقات.
• تتيح السمة defer للمتصفّح مواصلة عرض بقية صفحتك أثناء تحميل واجهة برمجة التطبيقات.

استخدِم الدالة initMap لإنشاء مثيل من حزمة 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
  });

عرض الرحلة المشترَكة

لعرض مستوى تقدّم مهمة مجدوَلة، عليك إعداد طريقة عرضها، ما يضبط إطار الخريطة ليتوافق مع الموقع الجغرافي للرحلة التي يتم تتبّعها. بعد ذلك، تقدّم حزمة تطوير البرامج (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);
});

معايير العرض لمهام متعددة

تعرض حزمة تطوير البرامج (SDK) للمستهلك للمهام المُجدوَلة مهمة واحدة فقط لكل رقم تعريف تتبُّع على الخريطة. ومع ذلك، يمكنك أيضًا عادةً تعيين رقم تعريف تتبّع واحد لسلع شحن معيّنة يظل مرتبطًا بالسلعة طوال رحلتها في نظامك. وهذا يعني أنّ رقم تعريف تتبُّع واحدًا قد يكون مرتبطًا بمهام متعددة، مثل مهمة استلام تليها مهمة تسليم للطرد نفسه، أو مهام شحن متعددة غير ناجحة لطرد معيّن.

للتعامل مع هذا الموقف، يطبّق Fleet Engine معايير لعرض المهام، كما هو موضّح في الجدول التالي.

إيقاف تتبُّع شحنة

عند اكتمال رحلة الشحنة أو إلغائها، يجب أن يتوقف تطبيق المستهلك عن تتبُّع الشحنة من خلال إزالة رقم تعريف التتبُّع ومقدّم خدمة الموقع الجغرافي من عرض الخريطة. لمعرفة التفاصيل، يُرجى الاطّلاع على الأقسام التالية.

إزالة رقم تعريف التتبُّع

لإيقاف موفّر خدمة الموقع الجغرافي عن تتبُّع الشحنة، عليك إزالة رقم تعريف التتبُّع من موفّر خدمة الموقع الجغرافي. توضّح الأمثلة التالية كيفية إجراء ذلك.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

إزالة موفّر الموقع الجغرافي من عرض الخريطة

يوضّح المثال التالي كيفية إزالة موفّر موقع جغرافي من عرض الخريطة.

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

التعامل مع أخطاء تتبُّع الشحنات

تؤدي الأخطاء التي تحدث بشكل غير متزامن من طلب معلومات الشحن إلى ظهور أحداث error. يوضّح المثال التالي كيفية الاستماع إلى هذه الأحداث لمعالجة الأخطاء.

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 لمعالجة الأخطاء غير المتوقعة.

الخطوات التالية

• تخصيص مظهر خريطة