تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

متابعة شحنة

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

تهيئة خريطة وعرض الرحلة المشتركة
التحديث ومتابعة التقدم المحرز في الرحلة
إيقاف مشاركة الرحلة
معالجة الأخطاء

إعداد خريطة

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

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

لإنشاء خريطة جديدة، يجب تحميل واجهة برمجة تطبيقات 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
  });

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

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

ملاحظات:

تأكد من أن صفحتك تحتوي على عنصر <div> يتيح عرض الخريطة. في المثال التالي، تتم تسمية العنصر <div> باسم map_canvas.
يُرجى الانتباه إلى قواعد مستوى الظهور التلقائية التي تنطبق عليها 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. تؤدي التغييرات في meta information إلى تشغيل حدث update. يوفّر الكائن 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 للمستهلكين للمهام المُجدوَلة مهمة واحدة فقط لكل رقم تعريف تتبّع في الخريطة. ومع ذلك، عادةً ما تحدّد أيضًا معرّف تتبّع واحدًا لتحديد سلعة شحن معيّنة تظل مرتبطة بالسلع طوال رحلتها في نظامك. وهذا يعني أنّ معرّف تتبُّع واحدًا قد يكون مرتبطًا ب tasks متعددة، مثل مهمة استلام متبوعة بمهمة تسليم للطرِد نفسه، أو مهام شحن متعددة تعذّر إكمالها للطرِد.

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

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

تصميم خريطة