متابعة شحنة

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

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

إعداد خريطة

لتتبُّع عملية استلام شحنة أو تسليمها في تطبيق الويب، عليك تحميل خريطة وإنشاء مثيل من Consumer SDK لبدء تتبُّع شحنتك. يمكنك تحميل خريطة جديدة أو استخدام خريطة حالية. بعد ذلك، يمكنك استخدام دالة التهيئة لإنشاء مثيل من Consumer 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.

توضّح هذه الأمثلة كيفية إنشاء مثيل لموفّر الموقع الجغرافي.

JavaScript

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

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

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

ملاحظات:

  1. تأكَّد من أنّ صفحتك تتضمّن العنصر <div> الذي يتضمّن عرض الخريطة. في المثال التالي، تمّت تسمية عنصر <div> باسم map_canvas.

  2. يجب التعرّف على قواعد مستوى العرض التلقائية التي تطبّقها Fleet Engine على الرحلات التي يتم تتبُّعها. يمكنك أيضًا ضبط قواعد مستوى العرض لمهام شحن المركبات النشطة ومهام التوقف المُجدوَلة. راجِع تخصيص إذن الوصول إلى المهام في دليل إعداد المهام.

توضّح هذه الأمثلة كيفية إعداد عرض الخريطة.

JavaScript

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 ما يلي:

  • الوصول
  • عدد المحطات المتبقية
  • المسافة المتبقية قبل استلام الطلب أو تسليمه

يوضّح المثال التالي كيفية الاستماع إلى أحداث التغيير هذه.

JavaScript

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

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

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

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

معايير المهام النتيجة
فتح مهام الاستلام
يجب أن يكون هناك عنصر واحد بالضبط عرض المهمة
تتوفّر عدة بطاقات خطأ في الإنشاء
مهام الاستلام المغلقة
يجب أن يكون هناك عنصر واحد بالضبط عرض المهمة
تتوفّر عدة نتائج (بعضها يتضمّن أوقات النتائج) عرض المهمة التي تم تسجيل آخر نتيجة لها
تتوفّر عدة نتائج (لا تتضمّن أيّ منها أوقات النتائج) خطأ في الإنشاء
فتح مهام التسليم
يجب أن يكون هناك عنصر واحد بالضبط عرض المهمة
تتوفّر عدة بطاقات خطأ في الإنشاء
مهام التسليم المغلقة
يجب أن يكون هناك عنصر واحد بالضبط عرض المهمة
تتوفّر عدة نتائج (بعضها يتضمّن أوقات النتائج) عرض المهمة التي تم تسجيل آخر نتيجة لها
تتوفّر عدة نتائج (لا تتضمّن أيّ منها أوقات النتائج) خطأ في الإنشاء

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

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

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

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

ملاحظة: احرص على تضمين استدعاءات المكتبة في حِزم try...catch للتعامل مع الأخطاء غير المتوقّعة.

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