دنبال کردن سفر در جاوا اسکریپت

انتخاب پلاتفرم: Android iOS JavaScript

وقتی سفری را دنبال می‌کنید، برنامه مصرف‌کننده شما مکان خودرو مناسب را به مصرف‌کننده نشان می‌دهد. برای انجام این کار، برنامه شما باید سفر را دنبال کند، پیشرفت سفر را درطول سفر به‌روز کند، و پس‌از تکمیل سفر، دنبال کردن آن را متوقف کند.

این سند مراحل کلیدی زیر را در این فرایند پوشش می‌دهد:

  1. راه‌اندازی نقشه
  2. مقداردهی اولیه نقشه و نمایش سفر هم‌رسانی‌شده
  3. به‌روزرسانی و دنبال کردن پیشرفت سفر
  4. توقف دنبال کردن سفر
  5. رسیدگی به خطاهای سفر

راه‌اندازی نقشه

برای دنبال کردن تحویل یا دریافت محموله در برنامه وب، باید نقشه‌ای را بار کنید و «کیت توسعه نرم‌افزار مصرف‌کننده» را نمونه‌سازی کنید تا ردیابی سفرتان شروع شود. می‌توانید نقشه جدیدی بار کنید یا از نقشه موجود استفاده کنید. سپس از تابع مقداردهی اولیه برای نمونه‌سازی Consumer SDK استفاده می‌کنید تا نمای نقشه با مکان موردی که ردیابی می‌شود مطابقت داشته باشد.

بار کردن نقشه جدید بااستفاده از Google Maps JavaScript API

برای ایجاد نقشه جدید، Google Maps JavaScript API را در برنامه وب خود بار کنید. مثال زیر نحوه بار کردن Google Maps JavaScript API، فعال کردن SDK، و راه‌اندازی بررسی مقداردهی اولیه را نشان می‌دهد.

  • پارامتر callback تابع initMap را پس‌از بار شدن API اجرا می‌کند.
  • ویژگی defer به مرورگر اجازه می‌دهد تا درحالی‌که API بارگیری می‌شود، بقیه صفحه را پرداز کند.

از تابع initMap برای نمونه‌سازی «کیت توسعه نرم‌افزار مصرف‌کننده» استفاده کنید. برای مثال:

    <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>

مقداردهی اولیه نقشه و نمایش پیشرفت سفر

وقتی سفری شروع می‌شود، برنامه شما باید ارائه‌دهنده مکان سفر را نمونه‌سازی کند و سپس نقشه را برای شروع هم‌رسانی پیشرفت سفر مقداردهی اولیه کند. برای مشاهده مثال‌ها، بخش‌های زیر را ببینید.

نمونه‌سازی ارائه‌دهنده مکان سفر

کیت توسعه نرم‌افزار جاوا اسکریپت دارای یک ارائه‌دهنده مکان ازپیش تعریف‌شده برای 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',
});

مقداردهی اولیه نمای نقشه

پس‌از بار کردن «کیت توسعه نرم‌افزار جاوا اسکریپت»، نمای نقشه را مقداردهی اولیه کنید و آن را به صفحه 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);
});

قدم بعدی چیست

سبک‌دار کردن نقشه