Theo dõi đội xe của bạn bằng Thư viện theo dõi nhóm JavaScript

Thư viện theo dõi nhóm JavaScript cho phép bạn trực quan hoá vị trí của các phương tiện trong đội xe gần như theo thời gian thực. Thư viện này sử dụng API Phân phối để cho phép hình ảnh hoá phương tiện giao hàng cũng như các nhiệm vụ. Giống như Thư viện theo dõi vận chuyển JavaScript, thư viện này chứa một thành phần bản đồ JavaScript thay thế cho một 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.

Thành phần

Thư viện theo dõi nhóm JavaScript cung cấp các thành phần để trực quan hoá các phương tiện giao hàng và điểm dừng, cũng như nguồn cấp dữ liệu thô cho giờ đến dự kiến hoặc khoảng cách còn lại đến điểm giao hàng.

Chế độ xem bản đồ Theo dõi đội phương tiện vận chuyển

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

Ví dụ về chế độ xem bản đồ Theo dõi đội phương tiện vận chuyển

Nhà cung cấp vị trí

Nhà cung cấp vị trí làm việc với thông tin lưu trữ trong Fleet Engine để gửi thông tin vị trí của các đối tượng được theo dõi vào bản đồ chia sẻ hành trình.

Nhà cung cấp vị trí xe giao hàng

Nhà cung cấp vị trí của xe giao hàng sẽ hiển thị thông tin vị trí của một xe giao hàng. Ứng dụng này có thông tin về vị trí của xe, cũng như những công việc mà xe giao hàng đã hoàn thành.

Nhà cung cấp địa điểm đội giao hàng

Nhà cung cấp vị trí của nhóm xe giao hàng sẽ hiện thông tin vị trí của nhiều xe. Bạn có thể lọc tìm các loại xe hoặc vị trí cụ thể hoặc cho thấy toàn bộ nhóm xe.

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 quy tắc hiển thị đối với các đối tượng vị trí được theo dõi trên bản đồ dành cho nhà cung cấp vị trí được xác định trước của Fleet Engine. Trình cung cấp vị trí tuỳ chỉnh hoặc phái sinh có thể thay đổi các quy tắc hiển thị.

Xe giao hàng

Xe giao hàng sẽ xuất hiện ngay khi được tạo trong Fleet Engine, đồng thời cũng xuất hiện trong suốt tuyến đường bất kể nhiệm vụ của nó.

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

Trên bản đồ, các điểm dừng xe theo kế hoạch sẽ xuất hiện dưới dạng điểm đánh dấu điểm dừng xe. Điểm đánh dấu cho các nhiệm vụ đã hoàn thành được hiển thị theo một kiểu khác với điểm dừng theo kế hoạch của xe.

Vị trí của kết quả nhiệm vụ được hiển thị với các điểm đánh dấu kết quả nhiệm vụ. Các nhiệm vụ có kết quả SUCCEEDED sẽ hiển thị với điểm đánh dấu tác vụ thành công, trong khi tất cả các nhiệm vụ khác được hiển thị với điểm đánh dấu tác vụ không thành công.

Bắt đầu với Thư viện theo dõi nhóm JavaScript

Trước khi sử dụng Thư viện theo dõi nhóm JavaScript, hãy đảm bảo rằng bạn làm quen với Fleet Engine và nhận khoá API. Sau đó, hãy tạo một mã công việc và xác nhận quyền sở hữu mã xe giao hàng.

Tạo mã công việc và xác nhận quyền sở hữu mã xe giao hàng

Để theo dõi xe giao hàng bằng nhà cung cấp vị trí xe giao hàng, hãy tạo Mã thông báo web JSON (JWT) có mã tác vụ và thông báo xác nhận quyền sở hữu mã xe phân phố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 các khoá taskid và deliveryvehicleid rồi đặt giá trị của mỗi khoá thành *. Mã thông báo phải được tạo bằng vai trò Cloud IAM của Fleet Engine Service Super User (Người dùng siêu người dùng dịch vụ Fleet Engine). Xin lưu ý rằng quyền này cấp quyền truy cập rộng rãi để tạo, đọc và sửa đổi các thực thể Fleet Engine và chỉ nên chia sẻ với những người dùng đáng tin cậy.

Ví dụ sau đây cho thấy cách tạo mã thông báo để theo dõi bằng xe và nhiệm vụ:

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

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ã xác thực để truy xuất mã thông báo được tạo bằng các thông báo xác nhận thích hợp trên máy chủ của mình bằng cách sử dụng chứng chỉ tài khoản dịch vụ cho dự án. Điều quan trọng là bạn chỉ nên đúc mã thông báo trên máy chủ của mình 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 với 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 khi tìm nạp.

Thư viện theo dõi nhóm 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:

  • Phương thức này không có mã thông báo hợp lệ, chẳng hạn như khi không gọi trình tìm nạp khi tải trang mới hoặc khi trình tìm nạp chưa trả về bằng 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 đã phát hành trước đó, vẫn hợp lệ 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 của mã thông báo; trong ví dụ trên, thời gian này được gán là data.ExpiresInSeconds.
  • Trình tìm nạp mã 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) vào 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 biết cách tải thư viện Chia sẻ hành trình 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 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 xe giao hàng

Phần này cho biết cách sử dụng Thư viện theo dõi đội tàu JavaScript để theo dõi xe 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í xe giao hàng

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

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher,

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

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, you may specify
          // deliveryVehicleId to immediately start
          // tracking.
          deliveryVehicleId: 'your-delivery-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 nên 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ụ bên dưới.

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 delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-vehicle-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('Times Square, New York, NY');
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 delivery vehicle ID in the 
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId 
                        = 'your-delivery-vehicle-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('Times Square, New York, NY');
mapView.map.setZoom(14);

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 tác vụ từ đối tượng deliveryVehicle 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 lần đến lấy hoặc trả xe tiếp theo. 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 những sự kiện thay đổi này.

JavaScript

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

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  // e.deliveryVehicle contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicle) {
    console.log(e.deliveryVehicle.remainingDuration);
  }
});

Nghe lỗi

Lỗi phát sinh không đồng bộ khi yêu cầu sự kiện lỗi kích hoạt thông tin về xe giao hàng. 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 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);
});

Dừng theo dõi

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

JavaScript

locationProvider.deliveryVehicleId = '';

TypeScript

locationProvider.deliveryVehicleId = '';

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

Xem hệ thống giao hàng

Phần này cho biết cách sử dụng thư viện Chia sẻ hành trình JavaScript để xem nhóm phân phối. 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í hệ thống giao hàng

Thư viện theo dõi nhóm JavaScript xác định sẵn một trình cung cấp vị trí có chức năng tìm nạp nhiều xe từ FleetEngine Deliveries API. Sử dụng mã dự án cũng như tham chiếu đến trình tìm nạp mã thông báo để tạo thực thể.

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleFilter chỉ định một truy vấn dùng để lọc các phương tiện hiển thị trên bản đồ. Bộ lọc này được chuyển trực tiếp đến Fleet Engine. Hãy xem ListDeliveryVehiclesRequest.filter để biết các định dạng được hỗ trợ.

locationRestriction giới hạn khu vực hiển thị phương tiện trên bản đồ. Chính sách này cũng kiểm soát việc tính năng theo dõi vị trí có đang hoạt động hay không. Theo dõi vị trí sẽ không bắt đầu cho đến khi bạn đặt giá trị này.

Sau khi xây dựng trình cung cấp vị trí, hãy khởi động chế độ xem bản đồ.

Đặt hạn chế vị trí bằng cách sử dụng chế độ xem bản đồ

Bạn có thể định cấu hình ranh giới locationRestriction để khớp với khu vực hiện có trong chế độ xem bản đồ.

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

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ề nhóm thiết bị từ đối tượng deliveryVehicles bằng trình cung cấp vị trí. Thông tin meta bao gồm các thuộc tính của xe như trạng thái chỉ đường, khoảng cách còn lại và thuộc tính tuỳ chỉnh; hãy xem tài liệu tham khảo để biết thêm thông tin chi tiết. Việc thay đổi đối với thông tin meta sẽ kích hoạt sự kiện update. Ví dụ sau cho biết cách theo dõi những sự kiện thay đổi này.

JavaScript

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

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryFleetLocationProviderUpdateEvent) => {
  // e.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

Nghe lỗi

Lỗi phát sinh không đồng bộ khi yêu cầu sự kiện lỗi kích hoạt thông tin về nhóm phân phối. Để xem các ví dụ minh hoạ cách theo dõi những sự kiện này, hãy tham khảo bài viết Nghe lỗi.

Dừng theo dõi

Để ngăn trình cung cấp vị trí theo dõi nhóm phân phối, hãy đặt giới hạn của trình cung cấp vị trí thành rỗng.

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

Theo dõi xe giao hàng trong khi xem đội xe giao hàng

Trong khi xem một đội xe, bạn có thể cho biết tuyến đường và các nhiệm vụ sắp tới của một chiếc xe giao hàng cụ thể. Để thực hiện việc này, hãy tạo thực thể cho cả Nhà cung cấp vị trí của nhóm giao hàng và Nhà cung cấp vị trí cho xe giao hàng, sau đó thêm cả hai vào chế độ xem bản đồ:

JavaScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

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

TypeScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

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

Nhà cung cấp vị trí của đội xe giao hàng bắt đầu hiển thị các xe giao hàng trên bản đồ. Sử dụng tính năng tuỳ chỉnh điểm đánh dấu để cho phép nhà cung cấp vị trí xe giao hàng theo dõi xe giao hàng khi có người nhấp vào điểm đánh dấu của nhóm xe:

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params: google.maps.journeySharing.DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

Ẩn điểm đánh dấu khỏi nhà cung cấp vị trí xe giao hàng để ngăn hiển thị hai điểm đánh dấu cho cùng một chiếc xe:

JavaScript

// Specify the customization function either separately, or as a field in 
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params: deliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

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 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ã. 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 một kiểu cho bản đồ Theo dõi nhóm 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 đây bằng mã nhận dạng bản đồ.

JavaScript

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

TypeScript

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

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 nhóm JavaScript, bạn có thể tuỳ chỉnh giao diện 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 các cách tuỳ chỉnh điểm đánh dấu mà sau đó Thư viện theo dõi đội phương tiện sẽ áp dụng trước khi thêm điểm đánh dấu vào bản đồ và với 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ẽ được áp dụng cho tất cả các điểm đánh dấu thuộc cùng một loại. Các thay đổi được chỉ định trong đối tượng sẽ được áp dụng sau khi mỗi điểm đánh dấu được tạo, ghi đè mọi tuỳ chọn mặc định.

Lựa chọn nâng cao hơn là chỉ định một hàm tuỳ chỉnh. Các hàm 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í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 đội phương tiện di chuyển sẽ truyền dữ liệu đến hàm tuỳ chỉnh về loại đối tượng mà điểm đánh dấu đại diện: xe cộ, điểm dừng hoặc nhiệm vụ. Sau đó, việc định kiểu cho điểm đánh dấu sẽ 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 hoặc loại tác vụ còn lại. 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 đó.

Ngoài ra, bạn có thể sử dụng các chức năng tuỳ chỉnh để lọc chế độ hiển thị của điểm đánh dấu. Để thực hiện việc này, hãy gọi hàm setVisible(false) trên điểm đánh dấu.

Tuy nhiên, vì lý do về hiệu suất, bạn nên lọc bằng bộ lọc gốc trong trình cung cấp vị trí, chẳng hạn như FleetEngineDeliveryFleetLocationProvider.deliveryVehicleFilter. Tuy nhiên, khi cần thêm chức năng lọc, bạn có thể áp dụng tính năng lọc bằng cách sử dụng chức năng tuỳ chỉnh.

Thư viện Theo dõi nhóm cung cấp các thông số tuỳ chỉnh sau:

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ỳ tham số tuỳ chỉnh điểm đánh dấu nào nêu 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. 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ỳ tham số tuỳ chỉnh điểm đánh dấu nào nêu trên.

JavaScript

deliveryVehicleMarkerCustomization =
  (params) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    params.marker.setLabel(`${stopsLeft}`);
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    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ý 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ỳ thông 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: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // Perform desired action.
      });
    }
  };

Lọc các điểm đánh dấu có thể nhìn thấy

Ví dụ sau đây cho thấy cách lọc các điểm đánh dấu xe hiển thị. Hãy làm theo mẫu này để lọc mọi điểm đánh dấu 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.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

TypeScript

deliveryVehicleMarkerCustomization =
  (params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
    var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
    if (stopsLeft > 10) {
      params.marker.setVisible(false);
    }
  };

Dùng cách tuỳ chỉnh hình nhiều đường khi đi theo xe giao hàng

Với Thư viện theo dõi nhóm JavaScript, bạn cũng có thể tuỳ chỉnh giao diện của tuyến đường của phương tiện bị theo dõi 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 xe. 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. Sau đó, thư viện sẽ áp dụng các cách 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 để áp dụng cho mọi đối tượng Polyline trùng khớp khi các đối tượng này đượ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 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 xe; ví dụ: tô màu đối tượng Polyline với sắc thái sâu hơn hoặc làm cho đối tượng dày hơn khi xe đang di chuyển chậm hơn. Bạn thậm chí có thể tham gia 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 thông tin đó.

Bạn có thể chỉ định các chế độ tuỳ chỉnh bằng cách sử dụng các tham số được cung cấp trong FleetEngineDeliveryVehicleLocationProviderOptions. Bạn có thể thiết lập chế độ tuỳ chỉnh cho các trạng thái lộ trình khác nhau trong hành trình của xe – đã đi, đang đi du lịch hoặc chưa đi. Các tham số như sau:

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

Ví dụ sau cho biết cách định cấu hình định kiểu cho đối tượng Polyline bằng PolylineOptions. Hãy 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 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 cho thấy cách định cấu hình kiểu cho đối tượng Polyline đang hoạt động bằng hàm tuỳ chỉnh. Hãy 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 các tham 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.deliveryVehicle.remainingDistanceMeters;
    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: DeliveryVehiclePolylineCustomizationFunctionParams) => {
    const distance = params.deliveryVehicle.remainingDistanceMeters;
    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ị. Để ẩ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 thị InfoWindow cho điểm đánh dấu xe hoặc vị trí

Bạn có thể dùng InfoWindow để hiện thêm thông tin về điểm đánh dấu xe 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 một điểm đánh dấu xe.

JavaScript

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

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

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

// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
  if (e.deliveryVehicle) {
    const distance = 
           e.deliveryVehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next task.`);

    // 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 cho phù hợp 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 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

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

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

Bạn có thể 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 làm mất các 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ị một đ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 JavaScript, trong đó có tính năng Theo dõi nhóm thiết bị:

  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. Use FleetEngineDeliveryVehicleLocationProvider
  // as appropriate.
  locationProvider = new google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProvider({
    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
  });

mapView.addListener('ready', () => {
  locationProvider.deliveryVehicleId = DELIVERY_VEHICLE_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, which includes Fleet Tracking functionality.
    -->
    <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 vận hành một phương tiện giao hàng với mã nhận dạng được chỉ định ở gần Uluru, thì giờ đây, mã đó sẽ xuất hiện trên bản đồ.