Theo dõi các lô hàng bằng Thư viện theo dõi quá trình vận chuyển JavaScript

Thư viện theo dõi việc vận chuyển JavaScript cho phép bạn trực quan hoá vị trí của xe và vị trí cần theo dõi trong Fleet Engine. Thư viện này chứa thành phần bản đồ JavaScript – giải pháp thay thế cho thực thể google.maps.Map tiêu chuẩn và các thành phần dữ liệu để kết nối với Fleet Engine. Khi sử dụng Thư viện theo dõi việc vận chuyển JavaScript, bạn có thể cung cấp trải nghiệm theo dõi quá trình vận chuyển ở dạng động có thể tuỳ chỉnh từ ứng dụng web của mình.

Thành phần

Thư viện theo dõi việc vận chuyển JavaScript cung cấp các thành phần để trực quan hoá xe và tuyến đường khi xe chạy đến một điểm đến, cũng như nguồn cấp dữ liệu thô cho thời gian đến dự kiến của người lái xe hoặc quãng đường còn lại của xe.

Chế độ xem bản đồ theo dõi quá trình vận chuyển

Thành phần chế độ xem bản đồ trực quan hoá vị trí của xe và điểm đến. Nếu đã biết tuyến đường của một chiếc xe, thành phần chế độ xem bản đồ sẽ tạo ảnh động cho chiếc xe đó khi xe di chuyển dọc theo đường dẫn được dự đoán.

Nhà cung cấp địa điểm vận chuyển

Trình cung cấp vị trí vận chuyển cung cấp thông tin vị trí cho các đối tượng được theo dõi vào bản đồ theo dõi vận chuyển để theo dõi quá trình vận chuyển đầu tiên và cuối cùng.

Bạn có thể sử dụng nhà cung cấp vị trí vận chuyển để theo dõi:

  • Địa điểm đến lấy hàng hoặc giao hàng của một lô hàng.
  • Vị trí và tuyến đường của xe giao hàng.

Đối tượng vị trí được theo dõi

Trình cung cấp vị trí theo dõi vị trí của các đối tượng như xe và điểm đến.

Vị trí điểm đến

Vị trí điểm đến là điểm kết thúc của hành trình. Để theo dõi quá trình vận chuyển, đây là vị trí tác vụ theo kế hoạch.

Vị trí xe

Vị trí của xe là vị trí được theo dõi của một chiếc xe. Bạn có thể thêm tuyến đường cho xe (không bắt buộc).

Trình tìm nạp mã thông báo xác thực

Để kiểm soát quyền truy cập vào dữ liệu vị trí lưu trữ trong Fleet Engine, bạn phải triển khai dịch vụ đúc mã thông báo web JSON (JWT) cho Fleet Engine trên máy chủ của mình. Sau đó, triển khai trình tìm nạp mã thông báo xác thực trong ứng dụng web, sử dụng Thư viện chia sẻ hành trình JavaScript để xác thực quyền truy cập vào dữ liệu vị trí.

Tùy chọn tạo kiểu

Kiểu điểm đánh dấu và đường nhiều đường xác định giao diện của các đối tượng vị trí được theo dõi trên bản đồ. Bạn có thể sử dụng các tuỳ chọn định kiểu tuỳ chỉnh để thay đổi kiểu mặc định cho phù hợp với kiểu của ứng dụng web.

Kiểm soát chế độ hiển thị của vị trí được theo dõi

Phần này mô tả các chế độ kiểm soát chế độ hiển thị cho các đối tượng được theo dõi trên bản đồ. Các quy tắc này áp dụng cho 2 danh mục đối tượng:

  • Điểm đánh dấu vị trí
  • Dữ liệu việc cần làm

Chế độ hiển thị điểm đánh dấu vị trí

Tất cả các điểm đánh dấu vị trí cho điểm khởi hành và điểm đến sẽ luôn được hiển thị trên bản đồ. Ví dụ: vị trí giao hàng luôn xuất hiện trên bản đồ, bất kể trạng thái giao hàng.

Chế độ hiển thị dữ liệu công việc

Phần này mô tả các quy tắc hiển thị mặc định áp dụng cho dữ liệu tác vụ, chẳng hạn như vị trí của xe và tuyến đường còn lại. Bạn có thể tuỳ chỉnh nhiều thao tác, nhưng không phải tất cả:

  • Tác vụ không khả dụng -- Bạn không thể tùy chỉnh chế độ hiển thị cho những tác vụ này.
  • Các nhiệm vụ đang hoạt động trên xe -- Bạn có thể tùy chỉnh các loại công việc này.
  • Các nhiệm vụ không hoạt động trên xe -- Bạn không thể tuỳ chỉnh chế độ hiển thị cho các nhiệm vụ này.

Tác vụ không có sẵn

Nếu có ít nhất một nhiệm vụ không hoạt động (ví dụ: nếu người lái xe đang nghỉ giải lao hoặc xe đang được tiếp nhiên liệu) trên tuyến đường đến nhiệm vụ đang được theo dõi, thì chiếc xe này sẽ không hiển thị. Bạn vẫn có thể xem thời gian đến dự kiến và thời gian hoàn thành việc cần làm ước tính.

Nhiệm vụ xe đang hoạt động

Đối tượng TaskTrackingInfo cung cấp một số phần tử dữ liệu có thể hiển thị trong Thư viện theo dõi lô hàng. Theo mặc định, các trường này sẽ hiển thị khi nhiệm vụ được giao cho xe và khi xe đi được 5 điểm dừng của nhiệm vụ đó. Chế độ hiển thị kết thúc khi hoàn thành hoặc huỷ tác vụ. Các trường đó có dạng như sau:

  • Hình nhiều đường của tuyến đường
  • Thời gian đến dự kiến
  • Thời gian hoàn thành việc cần làm ước tính
  • Quãng đường lái xe còn lại đến nhiệm vụ
  • Số lượng điểm dừng còn lại
  • Vị trí xe

Bạn có thể tuỳ chỉnh cấu hình chế độ hiển thị cho từng tác vụ bằng cách đặt TaskTrackingViewConfig cho một tác vụ khi tạo hoặc cập nhật tác vụ trong Fleet Engine. Thao tác này tạo ra các quy tắc về thời điểm có phần tử dữ liệu riêng lẻ. Các quy tắc này có thể dựa trên các tiêu chí sau (được gọi là tuỳ chọn chế độ hiển thị bên dưới):

  • Số lượng điểm dừng còn lại
  • Thời gian cho đến thời gian đến dự kiến
  • Quãng đường lái xe còn lại
  • Luôn hiển thị
  • Không bao giờ hiển thị

Lưu ý rằng mỗi phần tử dữ liệu chỉ có thể được liên kết với một tuỳ chọn chế độ hiển thị. Không thể kết hợp các tiêu chí bằng cách sử dụng OR hoặc AND.

Sau đây là ví dụ về cách tuỳ chỉnh. Quy tắc tuỳ chỉnh đó là:

  • Hiển thị nhiều đường kẻ trên tuyến đường nếu xe còn ở trong phạm vi 3 trạm dừng.
  • Hiển thị ETA nếu quãng đường lái xe còn lại ngắn hơn 5.000 mét.
  • Không bao giờ hiển thị số lượng điểm dừng còn lại.
  • Mỗi trường khác vẫn duy trì chế độ hiển thị mặc định khi xe đi được trong phạm vi 5 điểm dừng.
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "estimatedArrivalTimeVisibility": {
    "remainingDrivingDistanceMetersThreshold": 5000
  },
  "remainingStopCountVisibility": {
    "never": true
  }
}

Bạn cũng có thể tuỳ chỉnh cấu hình chế độ hiển thị mặc định cho dự án của mình bằng cách liên hệ với nhóm hỗ trợ.

Hình nhiều đường và quy tắc hiển thị vị trí của xe:

Khi nhìn thấy nhiều đường kẻ, vị trí của xe cũng phải hiển thị, nếu không, vị trí của xe có thể được biểu thị ở cuối hình nhiều đường. Điều đó có nghĩa là các tuyến nhiều đường không thể có tuỳ chọn chế độ hiển thị ít hạn chế hơn.

Bạn phải tuân thủ các quy tắc sau để cung cấp tổ hợp hình nhiều đường hợp lệ cho tuyến đường / chế độ hiển thị vị trí xe:

  • Khi hình nhiều đường và vị trí của xe có cùng kiểu lựa chọn chế độ hiển thị:

    • Nếu lựa chọn chế độ hiển thị là số điểm dừng còn lại, thời gian cho đến ETA hoặc quãng đường lái xe còn lại, thì hình nhiều đường của tuyến đường phải cung cấp một giá trị nhỏ hơn hoặc bằng giá trị được đặt cho chế độ hiển thị này đối với vị trí của xe. Sau đây là ví dụ:
    "taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
    • Nếu hình nhiều đường của tuyến đường có tuỳ chọn chế độ hiển thị luôn nhìn thấy được, thì vị trí của xe cũng phải cung cấp một tuỳ chọn chế độ hiển thị luôn nhìn thấy được.
    • Nếu vị trí của xe không có lựa chọn chế độ hiển thị không bao giờ nhìn thấy, thì hình nhiều đường của tuyến đường cũng phải cung cấp một tuỳ chọn chế độ hiển thị không bao giờ nhìn thấy.

  • Khi hình nhiều đường và vị trí của xe có các kiểu chế độ hiển thị khác nhau, vị trí của xe chỉ hiển thị khi cả hai lựa chọn chế độ hiển thị đều được đáp ứng.

    Sau đây là ví dụ:

    "taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingDrivingDistanceMetersThreshold": 3000
  },
}

    Trong ví dụ này, vị trí của xe chỉ hiển thị nếu số điểm dừng còn lại ít nhất là 3 VÀ quãng đường lái xe còn lại ít nhất là 3000 mét.

Làm quen với Thư viện chia sẻ hành trình JavaScript

Trước khi sử dụng Thư viện chia sẻ hành trình JavaScript, hãy đảm bảo bạn đã quen với Fleet Engine và cách tải khoá API.

Để theo dõi quá trình giao hàng, trước tiên, hãy tạo một thông báo xác nhận quyền sở hữu bằng mã theo dõi.

Tạo thông báo xác nhận quyền sở hữu mã theo dõi

Để theo dõi quá trình vận chuyển bằng trình cung cấp vị trí vận chuyển, hãy tạo Mã thông báo web JSON (JWT) có xác nhận quyền sở hữu mã theo dõi.

Để tạo tải trọng JWT, hãy thêm một thông báo xác nhận quyền sở hữu bổ sung trong phần uỷ quyền bằng khoá trackingid. Đặt giá trị của thuộc tính này thành mã theo dõi vận chuyển.

Ví dụ sau đây trình bày cách tạo mã thông báo để theo dõi bằng mã theo dõi:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "scope": "https://www.googleapis.com/auth/xapi",
  "authorization": {
     "trackingid": "tid_54321",
   }
}

Tạo trình tìm nạp mã thông báo xác thực

Bạn có thể tạo trình tìm nạp mã thông báo xác thực để truy xuất mã thông báo được tạo cùng với các thông báo xác nhận quyền sở hữu phù hợp trên máy chủ bằng cách sử dụng chứng chỉ tài khoản dịch vụ cho dự án của bạn. Điều quan trọng là chỉ đúc mã thông báo trên máy chủ của bạn và không bao giờ chia sẻ chứng chỉ của bạn trên bất kỳ ứng dụng nào. Nếu không, tính bảo mật của hệ thống sẽ bị xâm phạm.

Trình tìm nạp phải trả về một cấu trúc dữ liệu với hai trường, được gói trong một Promise:

  • Một chuỗi token.
  • Số expiresInSeconds. Mã thông báo sẽ hết hạn trong khoảng thời gian này sau khi tìm nạp.

Thư viện theo dõi việc vận chuyển JavaScript yêu cầu một mã thông báo thông qua trình tìm nạp mã thông báo xác thực khi bất kỳ trường hợp nào sau đây xảy ra:

  • Giao diện này không có mã thông báo hợp lệ, chẳng hạn như khi chưa gọi trình tìm nạp trong một lần tải trang mới hoặc khi trình tìm nạp không trả về mã thông báo.
  • Mã thông báo mà tính năng này tìm nạp trước đó đã hết hạn.
  • Mã thông báo mà nó tìm nạp trước đó sẽ hết hạn trong vòng một phút.

Nếu không, thư viện sẽ sử dụng mã thông báo vẫn hợp lệ và đã phát hành trước đó và không gọi trình tìm nạp.

Ví dụ sau đây cho thấy cách tạo trình tìm nạp mã thông báo xác thực:

JavaScript

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

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  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.expiration_timestamp_ms - Date.now(),
  };
}

Khi triển khai điểm cuối phía máy chủ để đúc mã thông báo, hãy lưu ý những điều sau:

  • Điểm cuối phải trả về thời gian hết hạn cho mã thông báo; trong ví dụ trên, điểm cuối được cung cấp là data.ExpiresInSeconds.
  • Trình tìm nạp mã thông báo xác thực phải chuyển thời gian hết hạn (tính bằng giây, kể từ thời điểm tìm nạp) cho thư viện, như minh hoạ trong ví dụ.
  • SERVER_TOKEN_URL phụ thuộc vào cách triển khai phần phụ trợ của bạn, sau đây là các URL cho phần phụ trợ ứng dụng mẫu:
    • https://SERVER_URL/token/delivery_driver/DELIVERY_VEHICLE_ID
    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID
    • https://SERVER_URL/token/fleet_reader

Tải bản đồ từ HTML

Ví dụ sau cho thấy cách tải Thư viện theo dõi vận chuyển JavaScript từ một URL đã chỉ định. Tham số callback thực thi hàm initMap sau khi API tải. Thuộc tính defer (trì hoãn) 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.

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

Theo dõi quá trình vận chuyển

Phần này cho biết cách sử dụng Thư viện theo dõi vận chuyển JavaScript để theo dõi quá trình lấy hàng hoặc giao hàng. Hãy nhớ tải thư viện từ hàm callback được chỉ định trong thẻ tập lệnh trước khi chạy mã.

Tạo thực thể cho trình cung cấp vị trí vận chuyển

Thư viện theo dõi việc vận chuyển JavaScript xác định sẵn trình cung cấp vị trí cho Fleet Engine Deliveries API. Sử dụng mã dự án và thông tin tham chiếu đến nhà máy mã thông báo để tạo bản sao của dự án đó.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineShipmentLocationProvider({
          projectId: 'your-project-id',
          authTokenFetcher: authTokenFetcher, // the token fetcher defined in the previous step

          // Optionally, you may specify tracking ID to
          // immediately start tracking.
          trackingId: 'your-tracking-id',
});

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

Sau khi tải thư viện Chia sẻ hành trình 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 đồ. Trong ví dụ sau, phần tử <div> được đặt tên là map_canvas.

Để tránh điều kiện tranh đấu, hãy đặt mã theo dõi cho trình cung cấp vị trí trong lệnh gọi lại được gọi sau khi bản đồ được khởi chạy.

JavaScript

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'), 
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
  // 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 will start 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

const mapView = new 
    google.maps.journeySharing.JourneySharingMapView({
  document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  vehicleMarkerSetup: vehicleMarkerSetup,
  anticipatedRoutePolylineSetup:
      anticipatedRoutePolylineSetup,
 // 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 will start 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);

Mã theo dõi

Mã theo dõi được cung cấp cho nhà cung cấp vị trí có thể tương ứng với nhiều nhiệm vụ; ví dụ: một nhiệm vụ đến lấy hàng và một nhiệm vụ giao hàng cho cùng một gói hàng hoặc một vài lần giao hàng không thành công. Một nhiệm vụ được chọn để xuất hiện trên bản đồ theo dõi giao hàng. Việc cần làm sẽ xuất hiện được xác định như sau:

  1. Nếu có chính xác một nhiệm vụ đến lấy hàng đang chờ xử lý, thì nhiệm vụ đó sẽ xuất hiện. Hệ thống sẽ tạo lỗi nếu có nhiều tác vụ đến lấy hàng đang được xử lý.
  2. Nếu có chính xác một nhiệm vụ phân phối đang mở, thì nhiệm vụ đó sẽ xuất hiện. Lỗi sẽ được tạo ra nếu có nhiều tác vụ phân phối đang mở.
  3. Nếu có các nhiệm vụ phân phối đã đóng:
    • Nếu có chính xác một tác vụ phân phối đã đóng, tác vụ đó sẽ xuất hiện.
    • Nếu có nhiều tác vụ phân phối đã đóng, thì tác vụ có thời gian kết quả gần đây nhất sẽ hiển thị.
    • Nếu có nhiều tác vụ phân phối đã đóng mà không tác vụ nào có thời gian kết quả, thì hệ thống sẽ tạo lỗi.
  4. Nếu có nhiệm vụ đến lấy hàng đã đóng:
    • Nếu có chính xác một nhiệm vụ đến lấy hàng đã đóng, thì tác vụ đó sẽ xuất hiện.
    • Nếu có nhiều tác vụ đến lấy hàng đã đóng, thì tác vụ có thời gian kết quả gần đây nhất sẽ hiển thị.
    • Nếu có nhiều tác vụ đến lấy hàng đã đóng, mà không tác vụ nào có thời gian kết quả, thì hệ thống sẽ tạo lỗi.
  5. Nếu không, việc cần làm sẽ không xuất hiện.

Theo dõi các sự kiện thay đổi

Bạn có thể truy xuất thông tin meta về công việc từ đối tượng thông tin theo dõi công việc bằng cách sử dụng trình cung cấp vị trí. Thông tin meta bao gồm giờ đến dự kiến, số điểm dừng còn lại và quãng đường còn lại trước khi đến lấy hàng hoặc giao hàng. Các thay đổi đối với thông tin meta sẽ kích hoạt sự kiện update. Ví dụ sau cho thấy cách theo dõi 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);
});

Xử lý lỗi

Các 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 các sự kiện lỗi. Ví dụ sau cho biết cách theo dõi những 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.

Dừng theo dõi

Để ngăn trình cung cấp vị trí theo dõi quá trình vận chuyển, hãy xoá mã theo dõi khỏi trình cung cấp vị trí.

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

Xóa trì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 đồ.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

Tuỳ chỉnh giao diện của bản đồ cơ sở

Để tuỳ chỉnh giao diện của thành phần bản đồ, hãy tạo kiểu cho bản đồ bằng công cụ trên đám mây hoặc bằng cách thiết lập các tuỳ chọn ngay trong mã.

Sử dụng kiểu bản đồ dựa trên đám mây

Định kiểu bản đồ dựa trên đám mây cho phép bạn tạo và chỉnh sửa kiểu bản đồ cho bất kỳ ứng dụng nào sử dụng Google Maps từ bảng điều khiển Google Cloud mà không yêu cầu thay đổi mã của bạn. Các kiểu bản đồ được lưu dưới dạng mã bản đồ trong dự án Cloud của bạn. Để áp dụng một kiểu cho bản đồ Theo dõi vận chuyển JavaScript, hãy chỉ định mapId khi bạn tạo JourneySharingMapView. Bạn không thể thay đổi hoặc thêm trường mapId sau khi tạo thực thể cho JourneySharingMapView. Ví dụ sau đây cho thấy cách bật kiểu bản đồ đã tạo trước đó bằng mã bản đồ.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    mapId: 'YOUR_MAP_ID'
  }
  // Any other styling options.
});

Sử dụng kiểu bản đồ dựa trên mã

Một cách khác để tuỳ chỉnh kiểu bản đồ là đặt mapOptions khi bạn tạo JourneySharingMapView.

JavaScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

TypeScript

const mapView = new google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  mapOptions: {
    styles: [
      {
        "featureType": "road.arterial",
        "elementType": "geometry",
        "stylers": [
          { "color": "#CCFFFF" }
        ]
      }
    ]
  }
});

Sử dụng các tuỳ chỉnh điểm đánh dấu

Với Thư viện theo dõi việc vận chuyển JavaScript, bạn có thể tuỳ chỉnh giao diện và cảm quan của điểm đánh dấu được thêm vào bản đồ. Bạn thực hiện việc này bằng cách chỉ định tuỳ chỉnh điểm đánh dấu. Sau đó, Thư viện theo dõi vận chuyển sẽ áp dụng điểm đánh dấu trước khi thêm điểm đánh dấu vào bản đồ và trong mỗi lần cập nhật điểm đánh dấu.

Cách tuỳ chỉnh đơn giản nhất là chỉ định một đối tượng MarkerOptions sẽ áp dụng cho tất cả các điểm đánh dấu cùng loại. Các thay đổi đã chỉ định trong đối tượng sẽ được áp dụng sau khi tạo từng điểm đánh dấu, ghi đè mọi tuỳ chọn mặc định.

Tuỳ chọn nâng cao hơn là chỉ định hàm tuỳ chỉnh. Các hàm tuỳ chỉnh cho phép tạo kiểu cho điểm đánh dấu dựa trên dữ liệu, cũng như thêm tính tương tác vào điểm đánh dấu, chẳng hạn như xử lý lượt nhấp. Cụ thể, tính năng Theo dõi quá trình vận chuyển truyền dữ liệu sang chức năng tuỳ chỉnh về loại đối tượng mà điểm đánh dấu đại diện: xe hoặc điểm đến. Nhờ vậy, kiểu điểm đánh dấu có thể thay đổi dựa trên trạng thái hiện tại của chính phần tử điểm đánh dấu đó; ví dụ: số điểm dừng theo kế hoạch còn lại cho đến đích đến. Bạn thậm chí có thể kết hợp dựa trên dữ liệu từ các nguồn bên ngoài Fleet Engine và tạo kiểu cho điểm đánh dấu dựa trên thông tin đó.

Thư viện Theo dõi việc vận chuyển cung cấp các tham số tuỳ chỉnh sau trong FleetEngineShipmentLocationProviderOptions:

Thay đổi kiểu của điểm đánh dấu bằng MarkerOptions

Ví dụ sau đây cho thấy cách định cấu hình kiểu của điểm đánh dấu xe bằng đối tượng MarkerOptions. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của mọi điểm đánh dấu bằng cách sử dụng bất kỳ chế độ tuỳ chỉnh điểm đánh dấu nào nêu trên.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Sử dụng các hàm tuỳ chỉnh để thay đổi kiểu của điểm đánh dấu

Ví dụ sau đây cho thấy cách định cấu hình kiểu của điểm đánh dấu xe. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của một điểm đánh dấu bất kỳ bằng cách sử dụng bất kỳ thông số tuỳ chỉnh điểm đánh dấu nào nêu trên.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    const stopsLeft = params.taskTrackingInfo.remainingStopCount;
    params.marker.setLabel(`${stopsLeft}`);
  };

Thêm hoạt động xử lý lượt nhấp vào điểm đánh dấu

Ví dụ sau đây cho thấy cách thêm thao tác nhấp vào điểm đánh dấu xe. Hãy làm theo mẫu này để thêm thao tác xử lý lượt nhấp vào bất kỳ điểm đánh dấu nào bằng cách sử dụng bất kỳ tham số tuỳ chỉnh điểm đánh dấu nào nêu trên.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: ShipmentMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

Sử dụng tính năng tuỳ chỉnh nhiều đường

Với Thư viện Theo dõi Lô hàng, bạn cũng có thể tuỳ chỉnh giao diện về tuyến đường của lô hàng trên bản đồ. Thư viện sẽ tạo một đối tượng google.maps.Polyline cho từng cặp toạ độ trong đường dẫn đang hoạt động hoặc còn lại của lô hàng. Bạn có thể tạo kiểu cho các đối tượng Polyline bằng cách chỉ định tuỳ chỉnh nhiều đường. Sau đó, thư viện sẽ áp dụng các phần tuỳ chỉnh này trong 2 trường hợp: trước khi thêm đối tượng vào bản đồ và khi dữ liệu dùng cho các đối tượng đã thay đổi.

Tương tự như việc tuỳ chỉnh điểm đánh dấu, bạn có thể chỉ định một tập hợp PolylineOptions sẽ áp dụng cho mọi đối tượng Polyline trùng khớp khi chúng được tạo hoặc cập nhật.

Tương tự, bạn có thể chỉ định một hàm tuỳ chỉnh. Các hàm tuỳ chỉnh cho phép tạo kiểu riêng cho đối tượng dựa trên dữ liệu do Fleet Engine gửi. Hàm này có thể thay đổi kiểu của từng đối tượng dựa trên trạng thái hiện tại của lô hàng; ví dụ: tô màu đối tượng Polyline sang màu đậm hơn hoặc làm cho đối tượng dày hơn khi xe di chuyển chậm hơn. Bạn thậm chí có thể kết hợp với các nguồn bên ngoài Fleet Engine và tạo kiểu cho đối tượng Polyline dựa trên thông tin đó.

Bạn có thể chỉ định các thành phần tuỳ chỉnh bằng cách sử dụng các tham số được cung cấp trong FleetEngineShipmentLocationProviderOptions. Bạn có thể đặt tuỳ chỉnh cho các trạng thái đường dẫn khác nhau trong hành trình của xe – đã đi, đang di chuyển hoặc chưa đi. Các tham số như sau:

Thay đổi kiểu của đối tượng Polyline bằng PolylineOptions

Ví dụ sau cho thấy cách định cấu hình định kiểu cho đối tượng Polyline bằng PolylineOptions. Hãy tuân theo mẫu này để tuỳ chỉnh kiểu của bất kỳ đối tượng Polyline nào bằng cách sử dụng bất kỳ tuỳ chỉnh nhiều đường nào nêu trên.

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

Thay đổi kiểu của đối tượng Polyline bằng các hàm tuỳ chỉnh

Ví dụ sau đây cho biết cách định cấu hình kiểu của một đối tượng Polyline đang hoạt động. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của bất kỳ đối tượng Polyline nào bằng cách sử dụng bất kỳ tham số tuỳ chỉnh hình nhiều đường nào nêu trên.

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params: ShipmentPolylineCustomizationFunctionParams) => {
    const distance = params.taskTrackingInfo.remainingDrivingDistanceMeters;
    if (distance < 1000) {

      // params.polylines contains an ordered list of Polyline objects for
      // the path.
      for (const polylineObject of params.polylines) {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

Kiểm soát chế độ hiển thị của các đối tượng Polyline

Theo mặc định, mọi đối tượng Polyline đều xuất hiện. Để ẩn một đối tượng Polyline, hãy đặt thuộc tính visible của đối tượng đó:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Hiện InfoWindow cho xe hoặc điểm đánh dấu vị trí

Bạn có thể sử dụng InfoWindow để hiện thêm thông tin về xe hoặc điểm đánh dấu vị trí.

Ví dụ sau đây cho biết cách tạo InfoWindow và đính kèm mã này vào điểm đánh dấu xe:

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', e => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Tắt tính năng tự động điều chỉnh

Bạn có thể dừng chế độ tự động điều chỉnh khung nhìn với xe và tuyến đường dự kiến để bản đồ không cho khớp vào khung nhìn bằng cách tắt tính năng tự động điều chỉnh. Ví dụ sau cho thấy cách tắt tính năng tự động điều chỉnh khi bạn định cấu hình chế độ xem bản đồ chia sẻ hành trình.

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
  automaticViewportMode:
      google.maps.journeySharing
          .AutomaticViewportMode.NONE,
  ...
});

TypeScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineShipmentLocationProviderUpdateEvent) => {
  const stopsCount =
      e.taskTrackingInfo.remainingStopCount;
  infoWindow.setContent(
      `Your vehicle is ${stopsCount} stops away.`);

  // 2. Attach the info window to a vehicle marker.   
  // This property can return multiple markers.
  const marker = mapView.vehicleMarkers[0];
  infoWindow.open(mapView.map, marker);
});

// 3. Close the info window.
infoWindow.close();

Thay thế bản đồ hiện tại

Bạn có thể sử dụng Thư viện theo dõi việc vận chuyển JavaScript để thay thế bản đồ hiện tại có điểm đánh dấu hoặc các cách tuỳ chỉnh khác mà không làm mất các yếu tố tuỳ chỉnh đó.

Ví dụ: giả sử bạn có một trang web có thực thể google.maps.Map chuẩn hiển thị điểm đánh dấu:

<!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 Uluru
  var uluru = {lat: -25.344, lng: 131.036};
  // 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 Uluru
  var marker = new google.maps.Marker({position: uluru, 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.
    -->
    <script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>
  </body>
</html>

Cách thêm thư viện Chia sẻ hành trình bằng JavaScript:

  1. Thêm mã cho nhà máy mã thông báo xác thực.
  2. Khởi động trình cung cấp vị trí trong hàm initMap().
  3. Khởi động chế độ xem bản đồ trong hàm initMap(). Chế độ xem này có chứa bản đồ.
  4. Di chuyển nội dung 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 cần thực hiệ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
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.FleetEngineShipmentLocationProvider({
    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.trackingId = TRACKING_ID;

    // (4) Add customizations like before.

    // The location of Uluru
    var uluru = {lat: -25.344, lng: 131.036};
    // The map, initially centered at Mountain View, CA.
    var map = mapView.map;
    map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
    // The marker, now positioned at Uluru
    var marker = new google.maps.Marker({position: uluru, 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 journey sharing library 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>

Nếu bạn có một gói được theo dõi có mã nhận dạng được chỉ định ở gần Uluru, thì gói đó giờ đây sẽ hiển thị trên bản đồ.