متابعة شحنة

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

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

إعداد خريطة

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

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

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