Khi bạn theo dõi một chuyến đi, ứng dụng dành cho người tiêu dùng của bạn sẽ hiển thị vị trí của phương tiện 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 khởi động theo dõi một chuyến đi, cập nhật tiến trình của chuyến đi và ngừng theo dõi một chuyến đi khi 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 rằng bạn đã thiết lập những mục sau:
Các dịch vụ phụ trợ cho ứng dụng dành cho người tiêu dùng của bạn đã sẵn sàng và các dịch vụ của bạn để tìm người tiêu dùng phù hợp với phương tiện vận chuyển đã hoạt động.
Bạn đã thiết lập một 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 so khớp người tiêu dùng với xe, hãy sử dụng
JourneySharingSession
để bắt đầu theo dõi chuyến đi bằng tính năng chia sẻ hành trình.
Mã mẫu sau đây minh hoạ cách bắt đầu chia sẻ hành trình sau lượt 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 về tiến trình của chuyến đi, chẳng hạn như quãng đường mà xe cần đi di chuyển trước khi đến và thời gian đến dự kiến, ứng dụng của bạn cần hãy đăng ký và định cấu hình trình nghe như trong các ví dụ sau.
Đăng ký một 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?, ) { // ... } // ... })
Dùng
TripModelOptions
để định cấu hình trình nghe cho chuyến đi của bạn.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)
Dừ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 cần thiết nữa, chẳng hạn như như khi chuyến đi được người lái xe đánh dấu là HOÀN TẤT ở phần phụ trợ. Đang dừng hành trình việc chia sẻ giúp tránh các yêu cầu mạng không cần thiết đến Fleet Engine và ngăn chặn bộ nhớ rò rỉ thông tin.
Sử dụng JourneySharingSession
để dừng theo dõi chuyến đi như minh hoạ trong
sau đây là mã mẫu.
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 về chuyến đi
Phương thức onTripRefreshError
cho thấy các lỗi xảy ra trong chuyến đi
giám sát. Thông báo lỗi tuân theo Tiêu chuẩn lỗi của Google Cloud. Để biết thông tin chi tiết
định nghĩa thông báo lỗi và tất cả mã lỗi, hãy tham khảo bài viết Lỗi Google Cloud
.
Dưới đây là một số lỗi phổ biến có thể xảy ra trong quá trình theo dõi chuyến đi:
HTTP | RPC | Mô tả |
---|---|---|
400 | Hàm INVALID_ARGUMENT | Khách hàng đã chỉ định tên chuyến đi không hợp lệ. Tên chuyến đi phải tuân theo
providers/{provider_id}/trips/{trip_id} . Chiến lược phát hành đĩa đơn
provider_id phải là mã nhận dạng của Dự án trên đám mây mà
nhà cung cấp dịch vụ. |
401 | KHÔNG XÁC THỰC | Bạn gặp 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 gặp lỗi này nếu ứng dụng không có đủ quyền (ví dụ: một người dùng với 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 chưa được bật cho dự án ứng dụng. Có thể thiếu mã thông báo JWT hoặc mã thông báo này đã được ký bằng mã chuyến đi không khớp với mã chuyến đi đã 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á hạn mức. |
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 | Đã vượt quá thời hạn 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 pháp (nghĩa là thời hạn thời hạn yêu cầu là 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 tiêu dùng
SDK người tiêu dùng gửi lỗi cập nhật chuyến đi cho ứng dụng dành cho người tiêu dùng bằng lệnh gọi lại
cơ chế. Tham số gọi lại là kiểu dữ liệu trả về dành riêng cho từng nền tảng (
TripUpdateError
trên Android và
NSError
trên iOS).
Trích xuất mã trạng thái
Lỗi được chuyể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ông tin bổ sung từ các URL đó dưới dạng mã trạng thái. Đối với danh sách đầy đủ các mã trạng thái, xem Mã trạng thái và cách sử dụng chú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à lỗi mạng, và 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 là 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 chúng. SDK người tiêu dùng tự động phục hồi từ họ.
Mã trạng thái | Mô tả |
---|---|
ĐÃ THANH TOÁN | Máy chủ đã ngừng gửi phản hồi. Điều này thường là do lỗi sự cố máy chủ. |
ĐÃ HỦY | Máy chủ đã chấm dứt phản hồi gửi đi. Thông thường
xảy ra khi
ứng dụng được chuyển sang chạy ở chế độ nền hoặc khi có sự thay đổi về trạng thái trong Ứng dụng dành cho người tiêu dùng. |
BỊ GIÁN ĐOẠN | |
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 khả dụng. Điều này thường là do mạng vấn đề. |
Lỗi ứng dụng
Các mã trạng thái sau đây là dành cho các lỗi ứng dụng và bạn phải hành động để hãy giải quyết chúng. SDK người tiêu dùng sẽ tiếp tục thử lại để làm mới chuyến đi cho đến khi bạn kết thúc chia sẻ hành trình, nhưng tiện ích này sẽ không khôi phục cho đến khi bạn hành động.
Mã trạng thái | Mô tả |
---|---|
Hàm INVALID_ARGUMENT | Ứng dụng Người tiêu dùng đã chỉ định tên chuyến đi không hợp lệ; Tên chuyến đi phải
sẽ 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 tiêu 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 độ. |
KHÔNG XÁC THỰC | Không xác thực được yêu cầu do mã thông báo JWT không hợp lệ. Chiến dịch này lỗi 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. |