Theo dõi chuyến đi trong Android

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

Tài liệu này trình bày cách hoạt động của quy trình đó.

Trước khi bắt đầu

Hãy đảm bảo bạn đã thiết lập những điều sau:

• Các dịch vụ phụ trợ cho ứng dụng dành cho người tiêu dùng đã được thiết lập và các dịch vụ của bạn để kết hợp người tiêu dùng với xe đang hoạt động.

• Bạn đã thiết lập bản đồ cho ứng dụng của mình.

Bắt đầu theo dõi một chuyến đi

Khi máy chủ phụ trợ của bạn kết hợp một người tiêu dùng với một chiếc xe, hãy sử dụng JourneySharingSession để bắt đầu theo dõi chuyến đi.

Mã mẫu sau đây minh hoạ cách bắt đầu theo dõi một chuyến đi sau khi chế độ xem tải.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    String tripName = ...;
    TripModelManager tripModelManager = consumerApi.getTripModelManager();
    TripModel tripModel = tripModelManager.getTripModel(tripName);

    // Create a JourneySharingSession instance based on the TripModel.
    JourneySharingSession session = JourneySharingSession.createInstance(tripModel);

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session);

    // Register for trip update events.
    tripModel.registerTripCallback(new TripModelCallback() {
      @Override
      public void onTripETAToNextWaypointUpdated(
          TripInfo tripInfo, @Nullable Long timestampMillis) {
        // ...
      }

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

      // ...
    });
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create a TripModel instance to listen for updates to the trip specified by this trip name.
    val tripName = "tripName"
    val tripModelManager = consumerApi.getTripModelManager()
    val tripModel = tripModelManager.getTripModel(tripName)

    // Create a JourneySharingSession instance based on the TripModel.
    val session = JourneySharingSession.createInstance(tripModel)

    // Add the JourneySharingSession instance on the map for updating the UI.
    consumerController.showSession(session)

    // Register for trip update events.
    tripModel.registerTripCallback(
      object : TripModelCallback() {
        override fun onTripETAToNextWaypointUpdated(
          tripInfo: TripInfo,
          timestampMillis: Long?,
        ) {
          // ...
        }

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

      // ...
    })
  }

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Cập nhật tiến trình chuyến đi

Để cập nhật thông tin chi tiết về tiến trình chuyến đi, chẳng hạn như khoảng cách mà xe cần di chuyển trước khi đến và thời gian đến dự kiến, ứng dụng của bạn cần đăng ký và định cấu hình trình nghe như trong các ví dụ sau.

1. Đăng ký trình nghe trên đối tượng TripModel.

   Java

   // Create a TripModel instance for listening to updates to the trip specified by this trip name.
   String tripName = ...;
   TripModelManager tripModelManager = consumerApi.getTripModelManager();
   TripModel tripModel = tripModelManager.getTripModel(tripName);
   
   // Create a JourneySharingSession instance based on the TripModel.
   JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
   
   // Add the JourneySharingSession instance on the map for updating the UI.
   consumerController.showSession(session);
   
   // Register for trip update events.
   tripModel.registerTripCallback(new TripModelCallback() {
   @Override
   public void onTripETAToNextWaypointUpdated(
           TripInfo tripInfo, @Nullable Long timestampMillis) {
         // ...
   }
   
   @Override
   public void onTripActiveRouteRemainingDistanceUpdated(
           TripInfo tripInfo, @Nullable Integer distanceMeters) {
         // ...
   }
   
   // ...
   });
   

   Kotlin

   // Create a TripModel instance for listening to updates to the trip specified by this trip name.
   val tripName = "tripName"
   val tripModelManager = consumerApi.getTripModelManager()
   val tripModel = tripModelManager.getTripModel(tripName)
   
   // Create a JourneySharingSession instance based on the TripModel.
   val session = JourneySharingSession.createInstance(tripModel)
   
   // Add the JourneySharingSession instance on the map for updating the UI.
   consumerController.showSession(session)
   
   // Register for trip update events.
   tripModel.registerTripCallback(
     object : TripModelCallback() {
       override fun onTripETAToNextWaypointUpdated(
         tripInfo: TripInfo,
         timestampMillis: Long?,
       ) {
         // ...
       }
   
       override fun onTripActiveRouteRemainingDistanceUpdated(
         tripInfo: TripInfo,
         distanceMeters: Int?,
       ) {
         // ...
       }
   
     // ...
   })
   

2. Định cấu hình trình nghe cho chuyến đi bằng TripModelOptions.

   Java

   // Set refresh interval to 2 seconds.
   TripModelOptions tripOptions =
         TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
   tripModel.setTripModelOptions(tripOptions);
   

   Kotlin

   // Set refresh interval to 2 seconds.
   val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
   tripModel.setTripModelOptions(tripOptions)
   

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

Hãy đảm bảo rằng ứng dụng của bạn ngừng theo dõi một chuyến đi khi không còn cần thiết nữa, chẳng hạn như khi chuyến đi được đánh dấu là HOÀN TẤT ở phần phụ trợ của tài xế. Việc ngừng chia sẻ hành trình giúp tránh các yêu cầu mạng không cần thiết đối với Fleet Engine và ngăn chặn tình trạng rò rỉ bộ nhớ.

Sử dụng JourneySharingSession để ngừng theo dõi chuyến đi như trong mã mẫu sau.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Xử lý lỗi chuyến đi

Phương thức onTripRefreshError hiển thị các lỗi xảy ra trong quá trình giám sát chuyến đi. Thông báo lỗi tuân theo tiêu chuẩn Lỗi của Google Cloud. Để biết định nghĩa chi tiết về thông báo lỗi và tất cả mã lỗi, hãy tham khảo tài liệu Lỗi của Google Cloud.

Dưới đây là một số lỗi thường gặp có thể xảy ra trong quá trình giám sát chuyến đi:

Xử lý lỗi SDK dành cho người tiêu dùng

SDK dành cho người tiêu dùng gửi lỗi cập nhật chuyến đi đến ứng dụng dành cho người tiêu dùng bằng cơ chế gọi lại. Tham số gọi lại là kiểu dữ liệu trả về dành riêng cho nền tảng (TripUpdateError trên Android và NSError trên iOS).

Trích xuất mã trạng thái

Các lỗi được truyền đến lệnh gọi lại thường là lỗi gRPC và bạn cũng có thể trích xuất thêm thông tin từ các lỗi đó dưới dạng mã trạng thái. Để xem danh sách đầy đủ các mã trạng thái, hãy xem bài viết Mã trạng thái và cách sử dụng trong gRPC.

// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
  Status.Code code = error.getStatusCode();
}

// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
  val code = error.getStatusCode()
}

Diễn giải mã trạng thái

Mã trạng thái bao gồm 2 loại lỗi: lỗi liên quan đến máy chủ và mạng, cũng như lỗi phía máy khách.

Lỗi máy chủ và mạng

Các mã trạng thái sau đây dành cho lỗi mạng hoặc lỗi máy chủ và bạn không cần thực hiện bất kỳ hành động nào để giải quyết các lỗi này. SDK dành cho người tiêu dùng sẽ tự động khôi phục các lỗi này.

Lỗi ứng dụng

Các mã trạng thái sau đây dành cho lỗi ứng dụng và bạn phải thực hiện hành động để giải quyết các lỗi này. SDK dành cho người tiêu dùng tiếp tục thử lại để làm mới chuyến đi cho đến khi bạn kết thúc việc chia sẻ hành trình, nhưng SDK này sẽ không khôi phục cho đến khi bạn thực hiện hành động.