متابعة رحلة في JavaScript

اختيار النظام الأساسي: Android iOS JavaScript

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

يتناول هذا المستند الخطوات الرئيسية التالية في هذه العملية:

  1. إعداد خريطة
  2. إعداد خريطة وعرض الرحلة التي تمت مشاركتها
  3. تعديل تقدّم الرحلة ومتابعته
  4. التوقّف عن متابعة رحلة
  5. التعامل مع أخطاء الرحلة

إعداد خريطة

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

استبدال خريطة حالية

يمكنك استبدال خريطة حالية تتضمّن علامات أو تخصيصات أخرى بدون فقدان هذه التخصيصات.

على سبيل المثال، إذا كانت لديك صفحة ويب تتضمّن عنصر google.maps.Map عاديًا يظهر عليه علامة، يمكنك استبدال الخريطة والاحتفاظ بالعلامة. يوضّح هذا القسم خطوات إجراء ذلك.

لاستبدال الخريطة والاحتفاظ بالتخصيصات، أضِف ميزة مشاركة الرحلة إلى صفحة HTML باتّباع هذه الخطوات، والتي تم ترقيمها أيضًا في المثال التالي:

  1. أضِف رمزًا برمجيًا لمصنع رمز المصادقة.

  2. أعِدّ موفِّر موقع جغرافي في الدالة initMap().

  3. أعِدّ طريقة عرض الخريطة في الدالة initMap(). تحتوي طريقة العرض على الخريطة.

  4. انقُل التخصيص إلى دالة رد الاتصال لإعداد طريقة عرض الخريطة.

  5. أضِف مكتبة الموقع الجغرافي إلى أداة تحميل واجهة برمجة التطبيقات.

يوضّح المثال التالي التغييرات التي يجب إجراؤها. إذا كنت تدير رحلة باستخدام المعرّف المحدّد بالقرب من أولورو، سيتم عرضها الآن على الخريطة:

    <!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>
    let locationProvider;

    // (1) Authentication Token Fetcher
    async function authTokenFetcher(options) {
      // options is a record containing two keys called
      // serviceType and context. The developer should
      // generate the correct SERVER_TOKEN_URL and request
      // based on the values of these fields.
      const response = await fetch(SERVER_TOKEN_URL);
          if (!response.ok) {
            throw new Error(response.statusText);
          }
          const data = await response.json();
          return {
            token: data.Token,
            expiresInSeconds: data.ExpiresInSeconds
          };
    }

    // Initialize and add the map
    function initMap() {
      // (2) Initialize location provider.
      locationProvider = new google.maps.journeySharing.FleetEngineTripLocationProvider({
        projectId: "YOUR_PROVIDER_ID",
        authTokenFetcher,
      });

      // (3) Initialize map view (which contains the map).
      const mapView = new google.maps.journeySharing.JourneySharingMapView({
        element: document.getElementById('map'),
        locationProviders: [locationProvider],
        // any styling options
      });

      locationProvider.tripId = TRIP_ID;

        // (4) Add customizations like before.

        // 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 async attribute allows the browser to render the page while the API loads
          * The key parameter will contain your own API key (which is not needed for this tutorial)
          * The callback parameter executes the initMap() function
          *
          * (5) Add the SDK to the API loader.
        -->
        <script defer
        src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
        </script>
      </body>
    </html>

إعداد خريطة وعرض تقدّم الرحلة

عند بدء رحلة، يجب أن يُعدّ تطبيقك موفِّر موقع جغرافي للرحلة ثم يُعدّ خريطة لبدء مشاركة تقدّم الرحلة. يمكنك الاطّلاع على الأمثلة في الأقسام التالية.

إعداد موفِّر موقع جغرافي للرحلة

تحتوي حزمة JavaScript SDK على موفِّر موقع جغرافي محدّد مسبقًا لـ Fleet Engine Ridesharing API. استخدِم رقم تعريف مشروعك ومرجعًا إلى مصنع الرموز لإعداده.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineTripLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify a trip ID to
          // immediately start tracking.
          tripId: 'your-trip-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineTripLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify a trip ID to
          // immediately start tracking.
          tripId: 'your-trip-id',
});

إعداد طريقة عرض الخريطة

بعد تحميل حزمة JavaScript SDK، عليك إعداد طريقة عرض الخريطة وإضافتها إلى صفحة HTML. يجب أن تحتوي صفحتك على عنصر <div> يتضمّن طريقة عرض الخريطة. في المثال التالي، يُطلق على عنصر <div> اسم map_canvas.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  // Styling customizations; see below.
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // Any undefined styling options will use defaults.
});

// If you did not specify a trip ID in the location
// provider constructor, you may do so here.
// Location tracking starts as soon as this is set.
locationProvider.tripId = 'your-trip-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 choose.
mapView.map.setCenter({lat: 37.2, lng: -121.9});
mapView.map.setZoom(14);

تعديل تقدّم الرحلة ومتابعته

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

JavaScript

locationProvider.addListener('update', e => {
  // e.trip contains data that may be useful
  // to the rest of the UI.
  console.log(e.trip.dropOffTime);
});

TypeScript

locationProvider.addListener('update', (e:
    google.maps.journeySharing.FleetEngineTripLocationProviderUpdateEvent) => {
  // e.trip contains data that may be useful
  // to the rest of the UI.
  console.log(e.trip.dropOffTime);
});

التوقّف عن متابعة رحلة

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

إزالة معرّف الرحلة من موفِّر الموقع الجغرافي

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

JavaScript

locationProvider.tripId = '';

TypeScript

locationProvider.tripId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

التعامل مع أخطاء الرحلة

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

JavaScript

locationProvider.addListener('error', e => {
  // e.error contains the error that triggered the
  // event
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error contains the error that triggered the
  // event
  console.error(e.error);
});

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

تنسيق خريطة