Theo dõi chuyến đi trong JavaScript

Chọn nền tảng: Android iOS JavaScript

Khi bạn theo dõi một chuyến đi, ứng dụng dành cho người dùng sẽ hiển thị vị trí của xe phù hợp cho người dùng. Để thực hiện việc này, ứng dụng của bạn cần bắt đầu theo dõi chuyến đi, cập nhật tiến trình trong suốt chuyến đi và ngừng theo dõi chuyến đi khi hoàn tất.

Tài liệu này trình bày các bước chính sau đây trong quy trình này:

  1. Thiết lập bản đồ
  2. Khởi chạy bản đồ và hiển thị hành trình được chia sẻ
  3. Cập nhật và theo dõi tiến trình chuyến đi
  4. Ngừng theo dõi một chuyến đi
  5. Xử lý lỗi về chuyến đi

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 hành trình của mình. 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 SDK tiêu dùng sao cho 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 một bản đồ mới, hãy tải API JavaScript của Google Maps trong ứng dụng web của bạn. 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 quá trình kiểm tra việc 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 bản đồ hiện có do API JavaScript của Google Maps tạo, chẳng hạn như bản đồ bạn đã 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 cho thấy 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>

Thay thế bản đồ hiện có

Bạn có thể thay thế một bản đồ hiện có có chứa điểm đánh dấu hoặc các tuỳ chỉnh khác mà không làm mất các tuỳ chỉnh đó.

Ví dụ: nếu có một trang web có thực thể google.maps.Map tiêu chuẩn trên đó hiển thị một điểm đánh dấu, bạn có thể thay thế bản đồ và giữ lại điểm đánh dấu. Phần này mô tả các bước thực hiện việc đó.

Để thay thế bản đồ và duy trì các tuỳ chỉnh, hãy thêm tính năng chia sẻ hành trình vào trang HTML bằng các bước sau (các bước này cũng được đánh số trong ví dụ sau):

  1. Thêm mã cho nhà máy mã thông báo xác thực.

  2. Khởi chạy trình cung cấp vị trí trong hàm initMap().

  3. Khởi chạy chế độ xem bản đồ trong hàm initMap(). Khung hiển thị chứa bản đồ.

  4. Chuyển chế độ tuỳ chỉnh của bạn vào hàm callback để khởi chạy chế độ xem bản đồ.

  5. Thêm thư viện vị trí vào trình tải API.

Ví dụ sau đây cho thấy các thay đổi sẽ được thực hiện. Nếu bạn điều hành một chuyến đi có mã nhận dạng được chỉ định gần Uluru, thì chuyến đi đó hiện sẽ hiển thị trên bản đồ:

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

Khởi chạy bản đồ và hiển thị tiến trình chuyến đi

Khi một chuyến đi bắt đầu, ứng dụng của bạn cần tạo thực thể cho một nhà cung cấp vị trí chuyến đi, sau đó khởi chạy một bản đồ để bắt đầu chia sẻ tiến trình của chuyến đi. Hãy xem các phần sau để biết ví dụ.

Tạo thực thể cho nhà cung cấp vị trí chuyến đi

SDK JavaScript có một nhà cung cấp vị trí được xác định trước cho API đi chung xe của Công cụ của đội xe. Sử dụng mã dự án và tệp tham chiếu đến nhà máy mã thông báo để tạo thực thể.

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

Khởi chạy chế độ xem bản đồ

Sau khi tải SDK JavaScript, hãy khởi chạy chế độ xem bản đồ và thêm chế độ xem đó vào trang HTML. Trang của bạn phải chứa một phần tử <div> chứa chế độ xem bản đồ. Phần tử <div> có tên là map_canvas trong ví dụ sau.

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

Cập nhật và theo dõi tiến trình chuyến đi

Ứng dụng của bạn phải theo dõi các sự kiện và cập nhật tiến trình chuyến đi khi hành trình diễn ra. Bạn có thể truy xuất thông tin siêu dữ liệu về một chuyến đi từ đối tượng tác vụ bằng cách sử dụng trình cung cấp vị trí. Thông tin meta bao gồm thời gian đến dự kiến và khoảng cách còn lại trước khi đến lấy hàng hoặc trả xe. Các thay đổi đối với thông tin meta sẽ kích hoạt sự kiện cập nhật. 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.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);
});

Ngừng theo dõi một chuyến đi

Khi chuyến đi kết thúc, bạn cần dừng nhà cung cấp vị trí theo dõi chuyến đi. Để làm điều này, hãy xoá mã chuyến đi và nhà cung cấp vị trí. Xem các phần sau để biết ví dụ.

Hãy xoá mã chuyến đi khỏi nhà cung cấp vị trí

Ví dụ sau đây cho biết cách xoá mã chuyến đi khỏi trình cung cấp vị trí.

JavaScript

locationProvider.tripId = '';

TypeScript

locationProvider.tripId = '';

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 chuyến đi

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

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

Bước tiếp theo

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