متابعة شحنة

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

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

إعداد خريطة

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

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

يمكنك أيضًا تحميل خريطة حالية تم إنشاؤها باستخدام 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
  });

عرض الرحلة التي تمّت مشاركتها

لعرض مستوى تقدّم مهمة مجدولة، عليك إعداد طريقة عرضها، ما يضبط إطار الخريطة ليتطابق مع موقع الرحلة التي يتم تتبُّعها. بعد ذلك، تقدّم حزمة 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 للمهام المجدولة سوى مهمة واحدة لكل رقم تعريف تتبُّع على الخريطة. ومع ذلك، يمكنك أيضًا عادةً تعيين رقم تعريف تتبُّع واحد إلى سلعة شحن معيّنة تظل مرتبطة بالسلعة طوال رحلتها في نظامك. وهذا يعني أنّه قد يتم ربط رقم تعريف تتبُّع واحد بمهام متعدّدة، مثل مهمة استلام تليها مهمة تسليم للطرد نفسه، أو مهام شحن متعدّدة غير ناجحة لطرد.

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

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