Khi bạn theo dõi một chuyến đi, ứng dụng dành cho người dùng sẽ hiển thị vị trí của xe phù hợp cho người 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 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 thông tin sau:
Các dịch vụ phụ trợ cho ứng dụng dành cho người dùng đã được triển khai và các dịch vụ của bạn để so khớp người dùng với xe đang hoạt động.
Bạn đã thiết lập bản đồ cho ứng dụng.
Bắt đầu theo dõi một chuyến đi
Khi máy chủ phụ trợ của bạn so khớp người dùng với một 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.
Java
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();
}
}
}
Kotlin
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ư quãng đường mà xe cần đi trước khi đến nơi 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.
Đă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?, ) { // ... } // ... })Định cấu hình trình nghe cho chuyến đi của bạn 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
Đả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 thiết nữa, chẳng hạn như khi tài xế đánh dấu chuyến đi là ĐẦY ĐỦ ở phần phụ trợ. Việc dừng chia sẻ hành trình sẽ tránh các yêu cầu mạng không cần thiết đến Công cụ của đội xe và ngăn rò rỉ bộ nhớ.
Sử dụng JourneySharingSession để ngừng theo dõi chuyến đi như trong mã mẫu sau.
Java
public class MainActivity extends AppCompatActivity
implements ConsumerViewModel.JourneySharingListener {
// Class implementation
@Override
protected void onDestroy() {
super.onDestroy();
if (journeySharingSession != null) {
journeySharingSession.stop();
}
}
}
Kotlin
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 về Lỗi Google Cloud.
Sau đây là một số lỗi thường gặp có thể xảy ra trong quá trình theo dõi chuyến đi:
| HTTP | RPC | Mô tả |
|---|---|---|
| 400 | INVALID_ARGUMENT | Ứng dụng khách chỉ định tên chuyến đi không hợp lệ. Tên chuyến đi phải tuân theo định dạng providers/{provider_id}/trips/{trip_id}. provider_id phải là mã nhận dạng của Dự án trên Google Cloud do nhà cung cấp dịch vụ sở hữu. |
| 401 | UNAUTHENTICATED | Bạn sẽ nhận được lỗi này nếu không có thông tin xác thực hợp lệ. Ví dụ: nếu mã thông báo JWT được ký mà không có mã chuyến đi hoặc mã thông báo JWT đã hết hạn. |
| 403 | PERMISSION_DENIED | Bạn sẽ gặp lỗi này nếu ứng dụng khách không có đủ quyền (ví dụ: người dùng có vai trò người tiêu dùng cố gắng gọi updateTrip), nếu mã thông báo JWT không hợp lệ hoặc API không được bật cho dự án ứng dụng khách. Có thể thiếu mã thông báo JWT hoặc mã thông báo được ký bằng mã chuyến đi không khớp với mã chuyến đi được yêu cầu. |
| 429 | RESOURCE_EXHAUSTED | Hạn mức tài nguyên bằng 0 hoặc tốc độ lưu lượng truy cập vượt quá giới hạn. |
| 503 | KHÔNG CÓ | Dịch vụ hiện không hoạt động. Thông thường, máy chủ không hoạt động. |
| 504 | DEADLINE_EXCEEDED | Đã quá hạn chót cho yêu cầu. Lỗi này chỉ xảy ra nếu phương thức gọi đặt thời hạn ngắn hơn thời hạn mặc định của phương thức (tức là thời hạn yêu cầu không đủ để máy chủ xử lý yêu cầu) và yêu cầu không hoàn tất trong thời hạn. |
Xử lý lỗi SDK của người dùng
SDK dành cho người dùng gửi lỗi cập nhật chuyến đi đến ứng dụng dành cho người dùng bằng cơ chế gọi lại. Tham số gọi lại là một loại 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ạng mã trạng thái. Để xem danh sách đầy đủ các mã trạng thái, hãy xem phần Mã trạng thái và cách sử dụng trong gRPC.
Java
Bạn có thể trích xuất mã trạng thái gRPC cung cấp thông tin chi tiết về lỗi từ TripUpdateError được trả về từ onTripUpdateError().
// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
Status.Code code = error.getStatusCode();
}
Kotlin
Bạn có thể trích xuất mã trạng thái gRPC cung cấp thông tin chi tiết về lỗi từ TripUpdateError được trả về từ onTripUpdateError().
// 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 hai loại lỗi: lỗi liên quan đến máy chủ và mạng, và lỗi phía máy khách.
Lỗi máy chủ và lỗi mạng
Các mã trạng thái sau đây là dành cho lỗi mạng hoặc lỗi máy chủ và bạn không cần làm gì để giải quyết các lỗi này. SDK Người dùng sẽ tự động phục hồi từ các lỗi đó.
| Mã trạng thái | Mô tả |
|---|---|
| ĐÃ HUỶ | Máy chủ đã ngừng gửi phản hồi. Điều này thường là do sự cố máy chủ. |
| ĐÃ HỦY | Máy chủ đã chấm dứt phản hồi gửi đi. Điều này thường xảy ra khi ứng dụng được gửi vào chế độ nền hoặc khi có thay đổi trạng thái trong ứng dụng Người dùng . |
| BỊ GIÁN ĐỨNG | |
| DEADLINE_EXCEEDED | Máy chủ mất quá nhiều thời gian để phản hồi. |
| KHÔNG CÓ | Máy chủ không hoạt động. Điều này thường là do sự cố mạng. |
Lỗi máy khách
Các mã trạng thái sau đây là lỗi ứng dụng và bạn phải hành động để giải quyết các lỗi đó. SDK dành cho người dùng sẽ tiếp tục thử lại để làm mới chuyến đi cho đến khi bạn ngừng chia sẻ chuyến đi. Tuy nhiên, SDK này sẽ không khôi phục cho đến khi bạn thực hiện hành động.
| Mã trạng thái | Mô tả |
|---|---|
| INVALID_ARGUMENT | Ứng dụng dành cho người dùng đã chỉ định tên chuyến đi không hợp lệ; Tên chuyến đi phải tuân theo định dạng providers/{provider_id}/trips/{trip_id}.
|
| NOT_FOUND | Chuyến đi chưa được tạo. |
| PERMISSION_DENIED | Ứng dụng Người dùng không có đủ quyền. Lỗi này xảy ra khi:
|
| RESOURCE_EXHAUSTED | Hạn mức tài nguyên bằng 0 hoặc tốc độ lưu lượng truy cập vượt quá giới hạn tốc độ. |
| UNAUTHENTICATED | Yêu cầu không xác thực được do mã thông báo JWT không hợp lệ. Lỗi này xảy ra khi mã thông báo JWT được ký mà không có mã chuyến đi hoặc khi mã thông báo JWT đã hết hạn. |