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 vận chuyển JavaScript cho phép bạn trực quan hoá vị trí xe và vị trí quan tâm được theo dõi trong Fleet Engine. Thư viện chứa thành phần bản đồ JavaScript là một thành phần thay thế để một thực thể google.maps.Map chuẩn và các thành phần dữ liệu kết nối nhờ Fleet Engine. Dùng Thư viện theo dõi vận chuyển JavaScript, bạn có thể cung cấp trải nghiệm theo dõi vận chuyển có ảnh độ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 lô hàng JavaScript cung cấp các thành phần để trực quan hoá của phương tiện và tuyến đường khi phương tiện di chuyển đến một điểm đến, cũng như dữ liệu thô nguồn cấp dữ liệu cho giờ đến dự kiến của người lái xe hoặc quãng đường còn lại để lái xe.

Chế độ xem bản đồ theo dõi lô hàng

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

Nhà cung cấp địa điểm gửi hàng

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 lô hàng để theo dõi lô hàng đầu tiên và dặm cuối.

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

  • Vị trí đến lấy hàng hoặc giao hàng của 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 vật thể như xe cộ và đích đến.

Vị trí điểm đến

Vị trí đến là vị trí kết thúc một hành trình. Để vận chuyển theo dõi, đó là địa điểm tác vụ đã lên 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. Có thể tuỳ ý thêm một tuyến đường cho xe.

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 bạn. Sau đó, triển khai trình tìm nạp mã thông báo xác thực dưới dạng một phần của ứng dụng web bằ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í.

Lựa chọn tạo kiểu

Kiểu điểm đánh dấu và hình nhiều đường xác định giao diện của đối tượng vị trí đã theo dõi trên bản đồ. Bạn có thể sử dụng các tuỳ chọn tạo 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 khả năng hiển thị của các vị trí được theo dõi

Phần này mô tả các biện pháp 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

Khả năng 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 luôn hiển thị trên bản đồ. Ví dụ: một vị trí giao hàng vận chuyển luôn hiển thị trên bản đồ, bất kể trạng thái phân phối.

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 công việc, 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 việc cần làm nhưng không phải tất cả:

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

Tác vụ về tình trạng không có sẵn

Nếu có ít nhất một nhiệm vụ về tình trạng không có mặt (ví dụ: nếu người lái xe đang nghỉ ngơi hoặc xe đang được đổ xăng) trên tuyến đường vào nhiệm vụ đang được theo dõi, chiếc xe sẽ không nhìn thấy được. Thời gian đến dự kiến bạn vẫn có thể xem thời gian thực hiện và thời gian hoàn thành công việc ước tính.

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

Chiến lược phát hành đĩa đơn 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 vận chuyển. Theo mặc định, các trường này sẽ xuất hiện khi tác vụ được được chỉ định cho xe và khi xe cách nhiệm vụ được 5 điểm dừng. Chiến lược phát hành đĩa đơn chế độ hiển thị kết thúc khi việc cần làm được hoàn thành hoặc bị huỷ. Các trường có dạng sau:

  • Hình nhiều đườ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ố đ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ị theo từng nhiệm vụ bằng cách đặt thời gian TaskTrackingViewConfig thực hiện một nhiệm vụ khi tạo hoặc cập nhật nhiệm vụ đó trong Fleet Engine. Việc này tạo các quy tắc về thời điểm các phần tử dữ liệu riêng lẻ xuất hiện, có thể dựa trên tiêu chí sau (được gọi là tùy chọn chế độ hiển thị bên dưới):

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

Xin lưu ý rằng mỗi phần tử dữ liệu chỉ có thể liên kết với một 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ị hình nhiều đường nếu xe ở trong phạm vi 3 điểm dừng.
  • Hiển thị giờ đến dự kiến 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ố điểm dừng còn lại.
  • Mỗi trường khác vẫn giữ nguyên chế độ hiển thị mặc định khi được hiển thị khi xe cách nhiệm vụ 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 bằng cách liên hệ với nhóm hỗ trợ.

Quy tắc về chế độ hiển thị hình nhiều đường và vị trí của xe:

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

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

  • Khi hình nhiều tuyến đường và vị trí của xe có cùng một chế độ hiển thị loại:

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

  • Khi hình nhiều tuyến đường và vị trí của xe có chế độ hiển thị khác loại xe, vị trí của xe chỉ hiển thị khi cả hai xe đều có chế độ hiển thị đã thoả mãn.

    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 điểm dừng còn lại số lượng tối thiểu là 3 VÀ quãng đường lái xe còn lại tối thiểu 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 thuộc với Fleet Engine và bằng cách lấy khoá API.

Để theo dõi quá trình phân phối, trước tiên hãy tạo thông báo xác nhận quyền sở hữu 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 nhà cung cấp địa điểm giao hàng, tạo Mã thông báo web JSON (JWT) có thông báo 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 khác vào phần uỷ quyền bằng khoá trackingid. Đặt giá trị của thông số này thành mã theo dõi lô hàng.

Ví dụ sau cho biết cách tạo mã thông báo để theo dõi theo 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 đã tạo bằng các khiếu nại thích hợp trên máy chủ của bạn thông qua một dịch vụ chứng chỉ tài khoản cho dự án của bạn. Bạn chỉ nên đú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, bạn sẽ xâm phạm tính bảo mật của hệ thống.

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

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

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

  • Phương thức 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 trên tải trang mới hoặc khi trình tìm nạp chưa trả về kèm theo mã thông báo.
  • Mã thông báo mà mã này tìm nạp trước đó đã hết hạn.
  • Mã thông báo mà mã này đã 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 được phát hành trước đó, vẫn hợp lệ và có 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 giữ lại những lư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, nó được gán là data.ExpiresInSeconds.
  • Trình tìm nạp mã thông báo xác thực phải vượt qua thời gian hết hạn (tính bằng giây, từ thời điểm tìm nạp) vào thư viện, như được thể hiện trong ví dụ.
  • SERVER_TOKEN_URL phụ thuộc vào triển khai 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 đây trình bày cách tải tính năng Theo dõi lô hàng của JavaScript Thư viện từ một URL đã chỉ định. Tham số callback thực thi 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.

<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 thực hiện theo quy trình đến 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 nhà cung cấp vị trí vận chuyển

Thư viện theo dõi vận chuyển JavaScript xác định trước 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 thực thể.

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 đồ rồi thêm vào trang HTML. Trang của bạn nên có phần tử &lt;div&gt; lưu chế độ xem bản đồ. Trong ví dụ sau đây: phần tử &lt;div&gt; được đặt tên là &lt;div&gt;.

Để tránh điều kiện tranh đấu, hãy đặt mã theo dõi cho 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

ID theo dõi được cung cấp cho nhà cung cấp vị trí có thể tương ứng với một số công việc; ví dụ: nhiệm vụ đến lấy hàng và giao hàng cho cùng một gói hàng, hoặc nhiều lần thử phân phối không thành công. Một việc cần làm được chọn để hiển thị trên bản đồ theo dõi lô hàng. Tác vụ sẽ hiển thị đượ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 mở thì nhiệm vụ đó sẽ xuất hiện. Đã tạo lỗi nếu có nhiều nhiệm vụ đến lấy hàng chưa được xử lý.
  2. Nếu có chính xác một tác vụ phân phối chưa xử lý, thì tác vụ đó sẽ xuất hiện. Có lỗi được tạo nếu có nhiều nhiệm vụ phân phối chưa xử lý.
  3. Nếu có nhiệm vụ phân phối khép kín:
    • Nếu có đúng một nhiệm vụ phân phối đã kết thúc thì nhiệm vụ đó sẽ xuất hiện.
    • Nếu có nhiều nhiệm vụ phân phối khép kín, thì nhiệm vụ được thực hiện gần đây nhất thời gian kết quả được hiển thị.
    • Nếu có nhiều tác vụ phân phối khép kín nhưng không có tác vụ nào trong số đó có kết quả thì sẽ có lỗi xảy ra.
  4. Nếu có nhiệm vụ đến lấy hàng đã đóng:
    • Nếu có đúng một nhiệm vụ đến lấy hàng đã đóng thì nhiệm vụ đó sẽ xuất hiện.
    • Nếu có nhiều nhiệm vụ đến lấy hàng đã khép kín thì nhiệm vụ cần thực hiện gần đây nhất thời gian kết quả được hiển thị.
    • Nếu có nhiều nhiệm vụ đến lấy hàng khép kín nhưng không có nhiệm vụ nào có kết quả thì sẽ có lỗi xảy ra.
  5. Nếu không, sẽ không có công việc nào xuất hiện.

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

Bạn có thể truy xuất thông tin siêu dữ liệu về một công việc trong phần 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 thời gian đế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 đây cho biết cách theo dõi những 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

Lỗi phát sinh không đồng bộ khi yêu cầu điều kiện kích hoạt thông tin vận chuyển lỗi. Ví dụ sau đây minh hoạ 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 khối try...catch để xử lý các lỗi ngoài dự kiến.

Dừng theo dõi

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

JavaScript

locationProvider.trackingId = '';

TypeScript

locationProvider.trackingId = '';

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

Ví dụ sau đây minh hoạ cách xoá 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 đồ, 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 trực tiếp trong mã.

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

Định kiểu bản đồ 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. Kiểu bản đồ được lưu dưới dạng mã bản đồ trong dự án trên Google Cloud của bạn. Để áp dụng kiểu cho bản đồ Theo dõi gửi hàng bằng JavaScript của bạn, hãy chỉ định mapId khi bạn tạo JourneySharingMapView. Không thể thay đổi trường mapId hoặc thêm vào sau khi JourneySharingMapView được tạo thực thể. Nội dung sau đây ví dụ cho thấy cách kích hoạt kiểu bản đồ đã tạo trước đó bằng ID 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 chế độ tuỳ chỉnh điểm đánh dấu

Với Thư viện theo dõi vận chuyển JavaScript, bạn có thể tuỳ chỉnh giao diện và cảm giác của các đ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 điểm đánh dấu mà sau đó Thư viện theo dõi vận chuyển sẽ áp dụng trước khi thêm vào các điểm đánh dấu lên bản đồ và với mỗi cập nhật điểm đánh dấu.

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

Lựa chọn nâng cao hơn là chỉ định một hàm tuỳ chỉnh. Tuỳ chỉnh cho phép định kiểu điểm đánh dấu dựa trên dữ liệu, cũng như thêm tương tác với các điểm đánh dấu, chẳng hạn như xử lý nhấp chuột. Cụ thể, Lô hàng Tính năng theo dõi truyền dữ liệu sang hàm tuỳ chỉnh về loại đối tượng mà điểm đánh dấu biểu thị: xe cộ hoặc điểm đến. Sau đó, thao tác này cho phép định kiểu điểm đánh dấu thay đổi dựa trên trạng thái hiện tại của chính phần tử đánh dấu; Ví dụ: số điểm dừng theo kế hoạch còn lại cho đến đích. Bạn thậm chí có thể tham gia so với 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 vận chuyển cung cấp các thông 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 thiết lập kiểu của điểm đánh dấu xe bằng đối tượng MarkerOptions. Làm theo mẫu này để tuỳ chỉnh kiểu của bất kỳ bằng cách sử dụng bất kỳ tuỳ chỉnh điểm đánh dấu nào được liệt kê ở trên.

JavaScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

TypeScript

deliveryVehicleMarkerCustomization = {
  cursor: 'grab'
};

Thay đổi kiểu điểm đánh dấu bằng cách sử dụng các hàm tuỳ chỉnh

Ví dụ sau đây cho thấy cách thiết lập kiểu của điểm đánh dấu xe. Theo dõi mẫu này để tuỳ chỉnh kiểu của điểm đánh dấu bằng cách sử dụng điểm đánh dấu bất kỳ tham số tuỳ chỉnh được liệt kê ở 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 thao tác nhấp chuột vào điểm đánh dấu

Ví dụ sau đây trình bày cách thêm thao tác nhấp vào điểm đánh dấu xe. Thực hiện theo mẫu này để thêm xử lý nhấp chuột vào bất kỳ điểm đánh dấu nào bằng cách sử dụng bất kỳ điểm đánh dấu nào tham số tuỳ chỉnh được liệt kê ở 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 chế độ tuỳ chỉnh hình nhiều đường

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

Tương tự như tuỳ chỉnh điểm đánh dấu, bạn có thể chỉ định một tập hợp PolylineOptions được áp dụng cho tất cả đối tượng Polyline phù hợ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. Chức năng tuỳ chỉnh cho phép tạo kiểu riêng cho các đố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 cho đối tượng Polyline thành bóng đậm hơn hoặc làm cho lớp phủ dày hơn khi xe di chuyển chậm hơn. Bạn thậm chí có thể tham gia với từ các nguồn bên ngoài Fleet Engine và tạo kiểu cho đối tượng Polyline dựa trên đó của bạn.

Bạn có thể chỉ định các tuỳ chỉnh bằng cách sử dụng các thông số được cung cấp trong FleetEngineShipmentLocationProviderOptions. Bạn có thể thiết lập chế độ tuỳ chỉnh cho nhiều trạng thái lộ trình trong hành trình--đã đi du lịch, đang chủ động đi du lịch hoặc chưa đi du lịch. Chiến lược phát hành đĩa đơn các thông số như sau:

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

Ví dụ sau đây cho biết cách định cấu hình định kiểu cho một đối tượng Polyline thông qua tính năng PolylineOptions. Làm theo mẫu này để tuỳ chỉnh kiểu của mọi đối tượng Polyline bằng cách sử dụng bất kỳ trong số các cách tuỳ chỉnh hình nhiều đường được liệt kê trước đó.

JavaScript

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

TypeScript

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

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

Ví dụ sau đây trình bày cách định cấu hình một đối tượng Polyline đang hoạt động tạo kiểu. Làm theo mẫu này để tuỳ chỉnh kiểu của mọi đối tượng Polyline bằng cách sử dụng bất kỳ thông số tuỳ chỉnh hình nhiều đường được liệt kê trước đó.

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, tất cả đối tượng Polyline đều hiển thị. Cách tạo đối tượng Polyline ẩn, đặt visible thuộc tính:

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

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

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

Ví dụ sau đây cho biết cách tạo và đính kèm InfoWindow 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 điều chỉnh tự động

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

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 có

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

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

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

  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 động chế độ xem bản đồ trong hàm initMap(). Chế độ xem 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:

<!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 hàng theo dõi ID được chỉ định gần Uluru, giờ đây URL này sẽ được hiển thị trên bản đồ.