Theo dõi một lô hàng

Giờ đây, khi đã thiết lập SDK JavaScript cho người dùng cho các nhiệm vụ theo lịch, bạn đã sẵn sàng theo dõi lô hàng bằng ứng dụng dành cho người dùng. Tài liệu này trình bày các bước chính sau đây trong quy trình này:

• Khởi chạy bản đồ và hiển thị hành trình được chia sẻ
• Cập nhật và theo dõi tiến trình của hành trình
• Ngừng theo dõi lô hàng
• Xử lý lỗi theo dõi lô hàng

Thiết lập bản đồ

Để theo dõi một chuyến lấy hàng hoặc giao hàng trong ứng dụng web, bạn cần tải một bản đồ và tạo thực thể cho SDK Người tiêu dùng để bắt đầu theo dõi lô hàng. Bạn có thể tải bản đồ mới hoặc sử dụng bản đồ hiện có. Sau đó, bạn sử dụng hàm khởi chạy để tạo thực thể cho SDK Người tiêu dùng sao cho chế độ xem bản đồ tương ứng với vị trí của mặt hàng đang được theo dõi.

Tải bản đồ mới bằng API JavaScript của Google Maps

Để tạo bản đồ mới, hãy tải API JavaScript của Google Maps vào ứng dụng web của bạn. Ví dụ sau đây cho thấy cách tải API JavaScript của Google Maps, bật SDK và kích hoạt quy trình kiểm tra khởi chạy.

• Tham số callback chạy hàm initMap sau khi API tải.
• Thuộc tính defer cho phép trình duyệt tiếp tục hiển thị phần còn lại của trang trong khi API tải.

Sử dụng hàm initMap để tạo thực thể cho Consumer SDK. Ví dụ:

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>

Tải bản đồ hiện có

Bạn cũng có thể tải một bản đồ hiện có được tạo bằng API JavaScript của Google Maps, chẳng hạn như bản đồ mà bạn đang sử dụng.

Ví dụ: giả sử bạn có một trang web có thực thể google.maps.Map chuẩn, trên đó có một điểm đánh dấu như được xác định trong mã HTML sau. Thao tác này sẽ hiển thị bản đồ của bạn bằng cách sử dụng cùng một hàm initMap trong lệnh gọi lại ở cuối:

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

Tạo thực thể cho trình cung cấp vị trí lô hàng

Sử dụng trình cung cấp vị trí lô hàng cùng với trình tìm nạp mã thông báo uỷ quyền mà bạn đã xác định trước đó để bắt đầu nhận dữ liệu từ Fleet Engine.

Các ví dụ sau đây cho thấy cách tạo thực thể cho trình cung cấp vị trí.

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

const locationProvider =
  new google.maps.journeySharing.FleetEngineShipmentLocationProvider({
      projectId: 'your-project-id',
      authTokenFetcher: authTokenFetcher,  // the fetcher defined previously
  });

Hiển thị hành trình được chia sẻ

Để hiển thị tiến trình của một nhiệm vụ theo lịch biểu, hãy khởi động chế độ xem của nhiệm vụ đó. Thao tác này sẽ đặt khung cho bản đồ tương ứng với vị trí của hành trình được theo dõi. Sau đó, SDK Người tiêu dùng sẽ cung cấp tiến trình sau khi nhận được thông tin từ Fleet Engine.

Mẹo:

1. Đảm bảo trang của bạn chứa một phần tử <div> chứa chế độ xem bản đồ. Trong ví dụ sau, phần tử <div> có tên là map_canvas.

2. Hãy lưu ý các quy tắc hiển thị mặc định mà Fleet Engine áp dụng cho các hành trình được theo dõi. Bạn cũng có thể định cấu hình quy tắc hiển thị cho các nhiệm vụ vận chuyển và điểm dừng theo lịch trình của xe đang hoạt động. Xem phần Tuỳ chỉnh chế độ hiển thị việc cần làm trong hướng dẫn Định cấu hình việc cần làm.

Các ví dụ này cho thấy cách khởi chạy chế độ xem bản đồ.

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);
}

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);
}

Cập nhật tiến trình vận chuyển

Bạn có thể theo dõi các sự kiện và cập nhật tiến trình vận chuyển khi hành trình diễn ra. Sử dụng trình cung cấp vị trí để truy xuất thông tin meta từ đối tượng taskTrackingInfo. Những thay đổi đối với thông tin meta sẽ kích hoạt sự kiện update (cập nhật). Đối tượng taskTrackingInfo cung cấp những thông tin sau:

• ETA
• Số điểm dừng còn lại
• Quãng đường còn lại trước khi đến lấy hàng hoặc giao hàng

Ví dụ sau đây cho thấy cách theo dõi các sự kiện thay đổi này.

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

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);
});

Tiêu chí hiển thị cho nhiều nhiệm vụ

SDK Người tiêu dùng cho các nhiệm vụ theo lịch chỉ hiển thị một nhiệm vụ cho mỗi mã theo dõi trên bản đồ. Tuy nhiên, bạn cũng thường chỉ định một mã theo dõi cho một hàng hoá vận chuyển cụ thể. Mã này sẽ được liên kết với hàng hoá đó trong suốt hành trình của hàng hoá trong hệ thống của bạn. Điều này có nghĩa là một mã theo dõi có thể liên kết với nhiều nhiệm vụ, chẳng hạn như nhiệm vụ lấy hàng, sau đó là nhiệm vụ giao hàng cho cùng một gói hàng hoặc nhiều nhiệm vụ giao hàng không thành công cho một gói hàng.

Để xử lý tình huống này, Fleet Engine áp dụng các tiêu chí để hiển thị nhiệm vụ, được trình bày trong bảng sau.

Ngừng theo dõi lô hàng

Khi hành trình của lô hàng hoàn tất hoặc bị huỷ, ứng dụng dành cho người tiêu dùng của bạn sẽ ngừng theo dõi lô hàng bằng cách xoá mã theo dõi và nhà cung cấp thông tin vị trí khỏi chế độ xem bản đồ. Để biết chi tiết, hãy xem các phần sau đây.

Xoá mã theo dõi

Để ngăn nhà cung cấp dịch vụ vị trí theo dõi lô hàng, hãy xoá mã theo dõi khỏi nhà cung cấp dịch vụ vị trí. Các ví dụ sau đây cho thấy cách thực hiện việc này.

locationProvider.trackingId = '';

locationProvider.trackingId = '';

Xoá nhà cung cấp vị trí khỏi chế độ xem bản đồ

Ví dụ sau đây cho thấy cách xoá một nhà cung cấp vị trí khỏi chế độ xem bản đồ.

mapView.removeLocationProvider(locationProvider);

mapView.removeLocationProvider(locationProvider);

Xử lý lỗi theo dõi lô hàng

Lỗi phát sinh không đồng bộ khi yêu cầu thông tin vận chuyển sẽ kích hoạt sự kiện error. Ví dụ sau đây cho thấy cách theo dõi các sự kiện này để xử lý lỗi.

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

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

Lưu ý: Hãy nhớ gói các lệnh gọi thư viện trong khối try...catch để xử lý các lỗi không lường trước được.

Bước tiếp theo

• Tạo kiểu cho bản đồ