متابعة شحنة

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

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

إعداد خريطة

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

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

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

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

استخدِم الدالة initMap لإنشاء مثيل حِزمة تطوير البرامج Consumer SDK. على سبيل المثال:

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

تحميل خريطة حالية

يمكنك أيضًا تحميل خريطة حالية تم إنشاؤها باستخدام واجهة برمجة التطبيقات JavaScript لخرائط Google، مثل خريطة تستخدمها حاليًا.

على سبيل المثال، لنفترض أنّ لديك صفحة ويب تتضمّن عنصرًا 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
  });

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

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

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

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

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

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

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

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

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

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

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