隨選乘車和外送解決方案目前僅供特定合作夥伴使用。

本頁面由 Cloud Translation API 翻譯而成。

建立及顯示共用集區行程

共用集區行程是指多位消費者同時共用車輛的共用行程。也就是說，行程為並行，而非獨立。運作方式與機場接駁服務類似，但司機也可以在路線上讓消費者一起下車。

共用集區和單一目的地行程的主要差異，在於共用集區行程時，行程業者可能會同時載運多位乘客。

本教學課程將逐步引導您建立共用集區行程。此外，應用程式也會說明如何將行程與消費者應用程式整合，讓客戶能透過手機查看行程進度。您可使用 Consumer SDK 進行這項整合。

步驟 1：在 Fleet Engine 中建立車輛

車輛是一種物件，代表車隊中的車輛。您必須在 Fleet Engine 中建立它們，才能在消費者應用程式中追蹤。

你可以透過下列兩種方法建立車輛：

gRPC: 使用 CreateVehicleRequest 要求訊息呼叫 CreateVehicle() 方法。您必須具備 Fleet Engine 超級使用者權限才能呼叫 CreateVehicle()。
REST: 呼叫 https://fleetengine.googleapis.com/v1/providers.vehicles.create。

注意事項

建立車輛時請留意下列注意事項。

請務必將初始車輛狀態設為 OFFLINE。確保 Fleet Engine 可以找到你的車輛，以便進行行程比對。
這輛車的 provider_id 必須與包含用來呼叫機群引擎的服務帳戶的 Google Cloud 專案 ID 相同。雖然多個服務帳戶可以存取同一個共乘供應商的 Fleet Engine，但 Fleet Engine 目前不支援來自存取相同車輛的不同 Google Cloud 專案的服務帳戶。
CreateVehicle() 傳回的回應包含 Vehicle 例項。如果執行個體未使用 UpdateVehicle() 更新，則系統會在七天後刪除該執行個體。您應先呼叫 GetVehicle() 再呼叫 CreateVehicle()，藉此確認車輛不存在。如果 GetVehicle() 傳回 NOT_FOUND 錯誤，則應繼續呼叫 CreateVehicle()。詳情請參閱「車輛及其生命週期」一文。

範例

以下供應商程式碼範例示範如何在 Fleet Engine 中建立車輛。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .build();

CreateVehicleRequest createVehicleRequest = CreateVehicleRequest.newBuilder()
    .setParent(parent)
    .setVehicleId("8241890")  // Vehicle ID assigned by solution provider.
    .setVehicle(vehicle)      // Initial state.
    .build();

// The Vehicle is created in the OFFLINE state, and no initial position is
// provided.  When the driver app calls the rideshare provider, the state can be
// set to ONLINE, and the driver app updates the vehicle location.
try {
  Vehicle createdVehicle = vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

如要建立支援共用集區行程的 Vehicle，您必須在傳遞至 CreateVehicleRequest 的 Vehicle 物件中，將 TripType.SHARED 加入支援的行程類型清單。

Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)
    .addSupportedTripTypes(TripType.SHARED)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .build();

步驟 2：啟用位置追蹤功能

位置追蹤是指在行程期間追蹤車輛位置，駕駛應用程式將遙測資料傳送至 Fleet Engine，其中包含車輛目前位置。系統會使用這類持續更新的位置資訊串流，傳送沿途的車輛進度。位置追蹤功能啟用後，驅動程式應用程式會開始傳送此遙測資料，預設頻率為每五秒一次。

您可依下列方式啟用 Android 和 iOS 的位置追蹤功能：

呼叫適用於 Android 的 Driver SDK 方法 enableLocationTracking()。
將 iOS 適用的 Driver 布林值屬性 locationTrackingEnabled 設為 true。

範例

以下程式碼範例示範如何啟用位置追蹤功能。

Java

RidesharingVehicleReporter vehicleReporter = ...;

vehicleReporter.enableLocationTracking();

Kotlin

val vehicleReporter = ...

vehicleReporter.enableLocationTracking()

Swift

vehicleReporter.locationTrackingEnabled = true

Objective-C

_vehicleReporter.locationTrackingEnabled = YES;

步驟 3：將車輛的狀態設為「線上」

您可以將車輛的狀態設為 online，藉此讓車輛進入服務 (也就是讓車輛可以使用)，但必須先啟用位置追蹤功能，才能執行這項操作。

您可以針對 Android 和 iOS 裝置將車輛狀態設為線上狀態，方法如下：

呼叫適用於 Android 的 Driver SDK 方法 setVehicleState(VehicleState.ONLINE)。
呼叫 iOS 版 Driver SDK 方法 vehicleReporter.update(.online)。

範例

以下程式碼範例說明如何將車輛的狀態設為 ONLINE。

Java

vehicleReporter.setVehicleState(VehicleState.ONLINE);

Kotlin

vehicleReporter.setVehicleState(VehicleState.ONLINE)

Swift

vehicleReporter.update(.online)

Objective-C

[_vehicleReporter updateVehicleState:GMTDVehicleStateOnline];

步驟 4：在 Fleet Engine 中建立行程

如要建立共用集區行程，請按照使用單一目的地行程的方式，建立 Trip 物件。

行程是一個代表旅程的物件，為集合地理座標點，包括起點、路線控點和下車點。您必須為每個行程要求建立一個 Trip 物件，這樣系統才能比對要求和車輛，然後追蹤要求。

您可以使用 CreateTripRequest 要求訊息呼叫 CreateTrip() 方法來建立行程。

提供必要屬性

如要建立共用集區行程，您必須填寫下列欄位。

parent: 包含提供者 ID 的字串。此 ID 必須與包含用於呼叫 Fleet Engine 的服務帳戶的 Google Cloud 專案 ID 相同
trip_id: 你建立的字串，專門用來識別這個行程。
trip: 要建立的 Trip 個物件。

您必須在傳遞至 CreateTripRequest 的 Trip 物件中設定下列欄位：

trip_type: TripType.SHARED
pickup_point: 行程的起點，
dropoff_point: 行程的下車地點，建立行程時不需要這個欄位，之後可透過呼叫 UpdateTrip 進行設定。

範例

以下後端整合範例示範如何建立行程，以及如何自動指派給車輛做為共用集區。

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don’t specify an order, then the Fleet Engine adds Trip B’s
        // waypoints to the end of Trip A’s.
        ImmutableList.of(
            // Trip B’s pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A’s drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B’s drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

步驟 5：使用車輛 ID 和路線控點更新行程

您必須使用車輛 ID 設定行程，Fleet Engine 才能沿路線追蹤車輛。

您可以使用 UpdateTripRequest 呼叫 UpdateTrip 端點，使用車輛 ID 更新行程。請使用 update_mask 欄位指定您要更新車輛 ID。

您必須在行程的車輛路線控點集合 (Trip.vehicle_waypoints) 中，向未造訪的路線控點導入訂單。Fleet Engine 會使用這份清單，自動更新共用集區中所有行程的行程路線控點。

舉例來說，假設有兩趟共用集區行程：行程 A 和行程 B。行程 A 會轉送到其下車地點。然後，系統就會將「Trip B」加到同一輛車。在行程 B 的一個 UpdateTripRequest 中，您需要設定 vehicleId，並將 Trip.vehicle_waypoints 設為最佳路線點順序：B _取貨 → _下車地點 → B _下車地點。

呼叫 getVehicle() 會傳回其他路線控點 (remainingWaypoints) 清單，其中包含
B _取貨 → _下車地點 → B _下車地點。
行程 A 的 getTrip() 或 onTripRemainingWaypointsUpdated 回呼會傳回包含其他路線控點 (remainingWaypoints) 的清單，這份清單包含 B _取貨 → _下車地點。
行程 B 的 getTrip() 或 onTripRemainingWaypointsUpdated 回呼會傳回包含 B 取貨 → _下車地點 → B _下車地點的剩餘路線控點清單 (remainingWaypoints)。

範例

以下後端整合範例示範如何使用兩個共用集區行程的車輛 ID 和路線控點更新行程。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don’t specify an order, then the Fleet Engine adds Trip B’s
        // waypoints to the end of Trip A’s.
        ImmutableList.of(
            // Trip B’s pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A’s drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B’s drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

步驟 6：在消費者應用程式中監聽行程更新

針對 Android，您可以從 TripModelManager 取得 TripModel 物件，並註冊 TripModelCallback 事件監聽器，藉此監聽行程的資料更新。
針對 iOS，您可以從 GMTCTripService 取得 GMTCTripModel 物件，並註冊 GMTCTripModelSubscriber 訂閱者，藉此監聽行程中的資料更新。

TripModelCallback 事件監聽器和 GMTCTripModelSubscriber 訂閱者可讓應用程式根據自動重新整理時間間隔，定期接收行程進度更新。只有變更的值才能觸發回呼。否則回呼會保持靜音。

無論資料變更為何，系統一律會呼叫 TripModelCallback.onTripUpdated() 和 tripModel(_:didUpdate:updatedPropertyFields:) 方法。

範例 1

下列程式碼範例示範如何從 TripModelManager/GMTCTripService 取得 TripModel，並為其設定事件監聽器。

Java

// Start journey sharing after a trip has been created via Fleet Engine.
TripModelManager tripModelManager = consumerApi.getTripModelManager();

// Get a TripModel object.
TripModel tripModel = tripModelManager.getTripModel(tripName);

// Register a listener on the trip.
TripModelCallback tripCallback = new TripModelCallback() {
  ...
};
tripModel.registerTripCallback(tripCallback);

// Set the refresh interval.
TripModelOptions tripModelOptions = TripModelOptions.builder()
    .setRefreshInterval(5000) // interval in milliseconds, so 5 seconds
    .build();
tripModel.setTripModelOptions(tripModelOptions);

// The trip stops auto-refreshing when all listeners are unregistered.
tripModel.unregisterTripCallback(tripCallback);

Kotlin

// Start journey sharing after a trip has been created via Fleet Engine.
val tripModelManager = consumerApi.getTripModelManager()

// Get a TripModel object.
val tripModel = tripModelManager.getTripModel(tripName)

// Register a listener on the trip.
val tripCallback = TripModelCallback() {
  ...
}

tripModel.registerTripCallback(tripCallback)

// Set the refresh interval.
val tripModelOptions =
  TripModelOptions.builder()
    .setRefreshInterval(5000) // interval in milliseconds, so 5 seconds
    .build()

tripModel.setTripModelOptions(tripModelOptions)

// The trip stops auto-refreshing when all listeners are unregistered.
tripModel.unregisterTripCallback(tripCallback)

Swift

let tripService = GMTCServices.shared().tripService

// Create a tripModel instance for listening for updates from the trip
// specified by the trip name.
let tripModel = tripService.tripModel(forTripName: tripName)

// Register for the trip update events.
tripModel.register(self)

// Set the refresh interval (in seconds).
tripModel.options.autoRefreshTimeInterval = 5

// Unregister for the trip update events.
tripModel.unregisterSubscriber(self)

Objective-C

GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening for updates from the trip
// specified by the trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// Set the refresh interval (in seconds).
tripModel.options.autoRefreshTimeInterval = 5;

// Unregister for the trip update events.
[tripModel unregisterSubscriber:self];

範例 2

下列程式碼範例示範如何設定 TripModelCallback 事件監聽器和 GMTCTripModelSubscriber 訂閱者。

Java

// Implements a callback for the trip model so your app can listen for trip
// updates from Fleet Engine.
TripModelCallback subscriber =
  new TripModelCallback() {

    @Override
    public void onTripStatusUpdated(TripInfo tripInfo, @TripStatus int status) {
      // ...
    }

    @Override
    public void onTripActiveRouteUpdated(TripInfo tripInfo, List<LatLng> route) {
      // ...
    }

    @Override
    public void onTripVehicleLocationUpdated(
        TripInfo tripInfo, @Nullable VehicleLocation vehicleLocation) {
      // ...
    }

    @Override
    public void onTripPickupLocationUpdated(
        TripInfo tripInfo, @Nullable TerminalLocation pickup) {
      // ...
    }

    @Override
    public void onTripPickupTimeUpdated(TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripDropoffLocationUpdated(
        TripInfo tripInfo, @Nullable TerminalLocation dropoff) {
      // ...
    }

    @Override
    public void onTripDropoffTimeUpdated(TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripETAToNextWaypointUpdated(
        TripInfo tripInfo, @Nullable Long timestampMillis) {
      // ...
    }

    @Override
    public void onTripActiveRouteRemainingDistanceUpdated(
        TripInfo tripInfo, @Nullable Integer distanceMeters) {
      // ...
    }

    @Override
    public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
      // ...
    }

    @Override
    public void onTripUpdated(TripInfo tripInfo) {
      // ...
    }

    @Override
    public void onTripRemainingWaypointsUpdated(
        TripInfo tripInfo, List<TripWaypoint> waypointList) {
      // ...
    }

    @Override
    public void onTripIntermediateDestinationsUpdated(
        TripInfo tripInfo, List<TerminalLocation> intermediateDestinations) {
      // ...
    }

    @Override
    public void onTripRemainingRouteDistanceUpdated(
        TripInfo tripInfo, @Nullable Integer distanceMeters) {
      // ...
    }

    @Override
    public void onTripRemainingRouteUpdated(TripInfo tripInfo, List<LatLng> route) {
      // ...
    }
  };

Kotlin

// Implements a callback for the trip model so your app can listen for trip
// updates from Fleet Engine.
val subscriber =
  object : TripModelCallback() {
    override fun onTripStatusUpdated(tripInfo: TripInfo, status: @TripStatus Int) {
      // ...
    }

    override fun onTripActiveRouteUpdated(tripInfo: TripInfo, route: List<LatLng>) {
      // ...
    }

    override fun onTripVehicleLocationUpdated(
      tripInfo: TripInfo,
      vehicleLocation: VehicleLocation?
    ) {
      // ...
    }

    override fun onTripPickupLocationUpdated(tripInfo: TripInfo, pickup: TerminalLocation?) {
      // ...
    }

    override fun onTripPickupTimeUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripDropoffLocationUpdated(tripInfo: TripInfo, dropoff: TerminalLocation?) {
      // ...
    }

    override fun onTripDropoffTimeUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripETAToNextWaypointUpdated(tripInfo: TripInfo, timestampMillis: Long?) {
      // ...
    }

    override fun onTripActiveRouteRemainingDistanceUpdated(
      tripInfo: TripInfo,
      distanceMeters: Int?
    ) {
      // ...
    }

    override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
      // ...
    }

    override fun onTripUpdated(tripInfo: TripInfo) {
      // ...
    }

    override fun onTripRemainingWaypointsUpdated(
      tripInfo: TripInfo,
      waypointList: List<TripWaypoint>
    ) {
      // ...
    }

    override fun onTripIntermediateDestinationsUpdated(
      tripInfo: TripInfo,
      intermediateDestinations: List<TerminalLocation>
    ) {
      // ...
    }

    override fun onTripRemainingRouteDistanceUpdated(tripInfo: TripInfo, distanceMeters: Int?) {
      // ...
    }

    override fun onTripRemainingRouteUpdated(tripInfo: TripInfo, route: List<LatLng>) {
      // ...
    }
  }

Swift

class TripModelSubscriber: NSObject, GMTCTripModelSubscriber {

  func tripModel(_: GMTCTripModel, didUpdate trip: GMTSTrip?, updatedPropertyFields: GMTSTripPropertyFields) {
    // Update the UI with the new `trip` data.
    updateUI(with: trip)
    ...
  }

  func tripModel(_: GMTCTripModel, didUpdate tripStatus: GMTSTripStatus) {
    // Handle trip status did change.
  }

  func tripModel(_: GMTCTripModel, didUpdateActiveRoute activeRoute: [GMTSLatLng]?) {
    // Handle trip active route did update.
  }

  func tripModel(_: GMTCTripModel, didUpdate vehicleLocation: GMTSVehicleLocation?) {
    // Handle vehicle location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdatePickupLocation pickupLocation: GMTSTerminalLocation?) {
    // Handle pickup location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateDropoffLocation dropoffLocation: GMTSTerminalLocation?) {
    // Handle drop off location did update.
  }

  func tripModel(_: GMTCTripModel, didUpdatePickupETA pickupETA: TimeInterval) {
    // Handle the pickup ETA did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateDropoffETA dropoffETA: TimeInterval) {
    // Handle the drop off ETA did update.
  }

  func tripModel(_: GMTCTripModel, didUpdateRemaining remainingWaypoints: [GMTSTripWaypoint]?) {
    // Handle updates to the pickup, dropoff or intermediate destinations of the trip.
  }

  func tripModel(_: GMTCTripModel, didFailUpdateTripWithError error: Error?) {
    // Handle the error.
  }

  func tripModel(_: GMTCTripModel, didUpdateIntermediateDestinations intermediateDestinations: [GMTSTerminalLocation]?) {
    // Handle the intermediate destinations being updated.
  }

  ...
}

Objective-C

@interface TripModelSubscriber : NSObject <GMTCTripModelSubscriber>
@end

@implementation TripModelSubscriber

- (void)tripModel:(GMTCTripModel *)tripModel
            didUpdateTrip:(nullable GMTSTrip *)trip
    updatedPropertyFields:(GMTSTripPropertyFields)updatedPropertyFields {
  // Update the UI with the new `trip` data.
  [self updateUIWithTrip:trip];
  ...
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdateTripStatus:(enum GMTSTripStatus)tripStatus {
  // Handle trip status did change.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateActiveRoute:(nullable NSArray<GMTSLatLng *> *)activeRoute {
  // Handle trip route did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateVehicleLocation:(nullable GMTSVehicleLocation *)vehicleLocation {
  // Handle vehicle location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdatePickupLocation:(nullable GMTSTerminalLocation *)pickupLocation {
  // Handle pickup location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateDropoffLocation:(nullable GMTSTerminalLocation *)dropoffLocation {
  // Handle drop off location did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdatePickupETA:(NSTimeInterval)pickupETA {
  // Handle the pickup ETA did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateRemainingWaypoints:(nullable NSArray<GMTSTripWaypoint *> *)remainingWaypoints {
  // Handle updates to the pickup, dropoff or intermediate destinations of the trip.
}

- (void)tripModel:(GMTCTripModel *)tripModel didUpdateDropoffETA:(NSTimeInterval)dropoffETA {
  // Handle the drop off ETA did update.
}

- (void)tripModel:(GMTCTripModel *)tripModel didFailUpdateTripWithError:(nullable NSError *)error {
  // Handle the error.
}

- (void)tripModel:(GMTCTripModel *)tripModel
    didUpdateIntermediateDestinations:
        (nullable NSArray<GMTSTerminalLocation *> *)intermediateDestinations {
  // Handle the intermediate destinations being updated.
}
…
@end

你隨時可以按照下列方式查看行程資訊：

呼叫 Android 版 Consumer SDK 方法 TripModel.getTripInfo()。呼叫這個方法並不會強制重新整理資料，但資料仍會以重新整理頻率重新整理。
取得 iOS 版 Consumer SDK 資源 GMTCTripModel.currentTrip。

步驟 7：在消費者應用程式中顯示歷程

您可以透過下列方式存取「共乘」和「外送」使用者介面元素 API：

取得 Consumer SDK for Android ConsumerController 物件。詳情請參閱「使用使用者介面元素 API」。
取得 Consumer SDK for iOS GMTCMapView 物件。詳情請參閱「使用使用者介面元素 API」。

範例

以下程式碼範例示範如何啟動旅程共用使用者介面。

Java

JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
consumerController.showSession(session);

Kotlin

val session = JourneySharingSession.createInstance(tripModel)
consumerController.showSession(session)

Swift

let journeySharingSession = GMTCJourneySharingSession(tripModel: tripModel)
mapView.show(journeySharingSession)

Objective-C

GMTCJourneySharingSession *journeySharingSession =
    [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
[self.mapView showMapViewSession:journeySharingSession];

根據預設，Consumer SDK 只會顯示路線中的可用路段，但您可以選擇顯示其餘的路段，包括目的地。

如要顯示其他行程的路線控點資訊，可以使用以下方式存取與行程相關的所有路線控點：

呼叫 Android 版 Consumer SDK 方法 TripModel.getTripInfo()。接著呼叫 TripInfo.getRemainingWaypoints() 取得 TripWaypoint。每個 TripWaypoint 物件都包含行程 ID、路線控點位置和路線控點類型。
取得 iOS 版 Consumer SDK 資源 GMTCTripModel.currentTrip。然後取得 GMTSTrip.remainingWaypoints 陣列，以存取 GMTSTripWaypoint。每個 GMTSTripWaypoint 物件都包含行程 ID、路線控點位置和路線控點類型。

步驟 8：在機群引擎中管理行程狀態

您可以使用其中一個 TripStatus 列舉值指定行程狀態。當行程狀態變更 (例如從 ENROUTE_TO_PICKUP 變更為 ARRIVED_AT_PICKUP) 時，您必須透過 Fleet Engine 更新行程狀態。行程狀態一律以 NEW 的值開頭，結尾則是 COMPLETE 或 CANCELED。詳情請參閱trip_status。

範例

以下後端整合範例示範如何在 Fleet Engine 中更新行程狀態。

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

// Error handling.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}