Отслеживание доставки

Теперь, когда вы настроили JavaScript Consumer SDK для запланированных задач, вы можете отслеживать доставку в приложении для пользователей. В этом документе описаны следующие основные шаги:

  • Инициализация карты и отображение совместной поездки
  • Обновление и отслеживание хода поездки
  • Как отменить отслеживание отправления
  • Как устранять ошибки отслеживания доставки

Как настроить карту

Чтобы отслеживать доставку или получение груза в веб-приложении, загрузите карту и создайте экземпляр Consumer SDK. Вы можете загрузить новую карту или использовать существующую. Затем вы используете функцию инициализации, чтобы создать экземпляр Consumer SDK, чтобы представление карты соответствовало местоположению отслеживаемого объекта.

Загрузите новую карту с помощью Google Maps JavaScript API.

Чтобы создать карту, загрузите Google Maps JavaScript API в веб-приложение. В примере ниже показано, как загрузить Google Maps JavaScript API, включить SDK и запустить проверку инициализации.

  • Параметр callback выполняет функцию initMap после загрузки API.
  • Атрибут defer разрешает браузеру обрабатывать остальную часть страницы во время загрузки API.

Используйте функцию 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>

Создание экземпляра поставщика местоположения отправления

Чтобы начать получать данные от 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. Изменения метаданных вызывают событие 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);
});

Показать критерии для нескольких задач

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

Дальнейшие действия