متابعة شحنة

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

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

إعداد خريطة

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

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

لإنشاء خريطة جديدة، يجب تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google في تطبيق الويب. ويوضّح المثال التالي كيفية تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google وتفعيل حزمة تطوير البرامج (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>

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

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

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

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

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