Trang này được dịch bởi Cloud Translation API.

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

Giờ đây, khi đã thiết lập SDK Người dùng JavaScript cho các tác vụ theo lịch, bạn đã sẵn sàng theo dõi một 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
Dừng theo dõi một lô hàng
Xử lý lỗi theo dõi lô hàng

Thiết lập bản đồ

Để theo dõi quá trình lấy hàng hoặc giao hàng trong ứng dụng web, bạn cần tải bản đồ và tạo bản sao SDK dành cho người dùng để bắt đầu theo dõi lô hàng. Bạn có thể tải một bản đồ mới hoặc sử dụng một bản đồ hiện có. Sau đó, bạn sử dụng hàm khởi chạy để tạo bản sao SDK Người dùng để chế độ xem bản đồ tương ứng với vị trí của mục đ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 trong ứng dụng web. Ví dụ sau đây cho biết 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 bản sao SDK dành cho người dùng. 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ó do API JavaScript của Google Maps tạo, chẳng hạn như bản đồ bạn đang sử dụng.

Ví dụ: giả sử bạn có một trang web có thực thể google.maps.Map tiêu chuẩn trên đó có một điểm đánh dấu hiển thị 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 bản sao của 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ừ Công cụ xe.

Các ví dụ này cho biết cách tạo bản sao của trình cung cấp vị trí.

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

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

Để hiển thị tiến trình của một tác vụ được lên lịch, hãy khởi chạy chế độ xem của tác vụ đó. Chế độ xem 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 đó, tiến trình sẽ do SDK tiêu dùng cung cấp sau khi nhận được thông tin từ Công cụ của đội xe.

Mẹo:

Đảm bảo trang của bạn chứa phần tử <div> chứa chế độ xem bản đồ. Trong ví dụ sau, phần tử <div> được đặt tên là map_canvas.
Hãy lưu ý đến các quy tắc hiển thị mặc định mà Công cụ theo dõi xe áp dụng cho các chuyến đi được theo dõi. Bạn cũng có thể định cấu hình các quy tắc hiển thị cho lô hàng xe đang hoạt động và các nhiệm vụ dừng theo lịch. 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 tạo chế độ xem bản đồ.

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

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 siêu dữ liệu từ đối tượng taskTrackingInfo. Các thay đổi đối với thông tin siêu dữ liệu sẽ kích hoạt sự kiện 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
Khoảng cách còn lại trước khi đến lấy hoặc giao hàng

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

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

Hiển thị tiêu chí cho nhiều tác vụ

SDK dành cho người dùng cho các tác vụ được lên lịch sẽ hiển thị chỉ một tác 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ã vận đơn cho một hàng hoá trong lô hàng cụ thể. Mã này vẫn 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. Điều này có nghĩa là một mã vận đơn có thể được liên kết với nhiều tác vụ, chẳng hạn như một tác vụ lấy hàng, theo sau là một tác vụ giao hàng cho cùng một gói hàng hoặc nhiều tác vụ vận chuyển không thành công cho một gói hàng.

Để xử lý trường hợp này, Công cụ của đội xe áp dụng các tiêu chí để hiển thị tác vụ, như trong bảng sau.

Tiêu chí về việc cần làm	Kết quả
Mở việc cần làm là lấy hàng
Chỉ có một	Hiện tác vụ
Có nhiều	Lỗi tạo
Việc cần làm đã hoàn tất về việc đến lấy hàng
Chỉ có một	Hiện tác vụ
Có nhiều kết quả (một số kết quả có thời gian kết quả)	Hiển thị tác vụ có thời gian kết quả gần đây nhất
Có nhiều kết quả (không có kết quả nào có thời gian kết quả)	Lỗi tạo
Mở tác vụ phân phối
Chỉ có một	Hiện tác vụ
Có nhiều	Lỗi tạo
Nhiệm vụ phân phối đã đóng
Chỉ có một	Hiện tác vụ
Có nhiều kết quả (một số kết quả có thời gian kết quả)	Hiển thị tác vụ có thời gian kết quả gần đây nhất
Có nhiều kết quả (không có kết quả nào có thời gian kết quả)	Lỗi tạo

Dừng theo dõi một lô hàng

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

Xoá mã theo dõi

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

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

Bước tiếp theo

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