هنگامی که یک سفر را دنبال می کنید، برنامه مصرف کننده شما مکان وسیله نقلیه مناسب را به مصرف کننده نشان می دهد. برای انجام این کار، برنامه شما باید شروع به دنبال کردن یک سفر کند، پیشرفت سفر را بهروزرسانی کند و پس از اتمام آن سفر را دنبال نکند.
این سند نحوه عملکرد آن فرآیند را پوشش می دهد.
قبل از شروع
مطمئن شوید که موارد زیر را تنظیم کرده اید:
خدمات پشتیبان برای برنامه مصرف کننده شما وجود دارد و خدمات شما برای تطبیق مصرف کنندگان با وسایل نقلیه عملیاتی است.
شما یک نقشه برای برنامه خود تنظیم کرده اید.
دنبال کردن یک سفر را شروع کنید
وقتی سرور باطن شما یک مصرف کننده را با یک وسیله نقلیه مطابقت می دهد، از JourneySharingSession
استفاده کنید تا سفر را با استفاده از اشتراک گذاری سفر دنبال کنید.
کد نمونه زیر نحوه شروع به اشتراک گذاری سفر را پس از بارگیری نمایش نشان می دهد.
جاوا
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()
}
}
به روز رسانی پیشرفت سفر
برای بهروزرسانی جزئیات پیشرفت سفر، مانند مسافتی که وسیله نقلیه باید قبل از رسیدن طی کند و زمان تخمینی رسیدن، برنامه شما باید مانند مثالهای زیر شنونده را ثبت و پیکربندی کند.
یک شنونده در یک شی
TripModel
ثبت کنید.جاوا
// 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) { // ... } // ... });
کاتلین
// 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?, ) { // ... } // ... })
با استفاده از
TripModelOptions
شنونده را برای سفر خود پیکربندی کنید.جاوا
// Set refresh interval to 2 seconds. TripModelOptions tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build(); tripModel.setTripModelOptions(tripOptions);
کاتلین
// Set refresh interval to 2 seconds. val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build() tripModel.setTripModelOptions(tripOptions)
یک سفر را دنبال نکنید
مطمئن شوید که برنامه شما در زمانی که دیگر به آن سفر نیازی نیست، مانند زمانی که سفر توسط راننده علامتگذاری شده است به عنوان COMPLETE در قسمت پشتیبان، آن را دنبال نمیکند. توقف اشتراکگذاری سفر از درخواستهای غیرضروری شبکه به Fleet Engine جلوگیری میکند و از نشت حافظه جلوگیری میکند.
همانطور که در کد نمونه زیر نشان داده شده است، از JourneySharingSession
برای توقف دنبال کردن سفر استفاده کنید.
جاوا
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()
}
}
خطاهای سفر را مدیریت کنید
روش onTripRefreshError
خطاهایی را که در حین نظارت بر سفر رخ می دهد را نشان می دهد. پیام های خطا از استاندارد Google Cloud Error پیروی می کنند. برای تعاریف دقیق پیام خطا و همه کدهای خطا، به مستندات Google Cloud Errors مراجعه کنید.
در اینجا برخی از خطاهای رایجی که ممکن است در هنگام نظارت بر سفر رخ دهد آورده شده است:
HTTP | RPC | توضیحات |
---|---|---|
400 | INVALID_ARGUMENT | مشتری یک نام سفر نامعتبر مشخص کرده است. نام سفر باید از فرمت providers/{provider_id}/trips/{trip_id} پیروی کند. Provider_id باید شناسه پروژه Cloud متعلق به ارائه دهنده خدمات باشد. |
401 | بدون احراز هویت | اگر اعتبارنامه معتبری برای احراز هویت وجود نداشته باشد، این خطا را دریافت می کنید. برای مثال، اگر توکن JWT بدون شناسه سفر امضا شده باشد یا ژتون JWT منقضی شده باشد. |
403 | PERMISSION_DENIED | اگر کلاینت مجوز کافی نداشته باشد (به عنوان مثال، کاربری با نقش مصرف کننده سعی می کند updateTrip را فراخوانی کند)، اگر توکن JWT نامعتبر باشد یا API برای پروژه مشتری فعال نباشد، این خطا را دریافت می کنید. رمز JWT ممکن است وجود نداشته باشد یا رمز با شناسه سفری امضا شده باشد که با شناسه سفر درخواستی مطابقت ندارد. |
429 | RESOURCE_EXHAUSTED | سهمیه منابع صفر است یا میزان ترافیک از حد مجاز فراتر می رود. |
503 | در دسترس نیست | سرویس در دسترس نیست. به طور معمول سرور از کار افتاده است. |
504 | DEADLINE_EXCEEDED | مهلت درخواست فراتر رفت. این خطا تنها زمانی رخ میدهد که تماسگیرنده ضربالاجلی کوتاهتر از مهلت پیشفرض متد تعیین کند (یعنی مهلت درخواستی برای پردازش درخواست توسط سرور کافی نباشد) و درخواست در مهلت تعیین شده به پایان نرسد. |
خطاهای SDK مصرف کننده را مدیریت کنید
Consumer SDK خطاهای بهروزرسانی سفر را با استفاده از مکانیزم بازگشت به تماس به برنامه مصرفکننده ارسال میکند. پارامتر برگشت به تماس یک نوع بازگشتی خاص پلتفرم است ( TripUpdateError
در Android و NSError
در iOS).
استخراج کدهای وضعیت
خطاهای ارسال شده به callback معمولاً خطاهای gRPC هستند و همچنین می توانید اطلاعات اضافی را در قالب یک کد وضعیت از آنها استخراج کنید. برای فهرست کامل کدهای وضعیت، کدهای وضعیت و استفاده از آنها در gRPC را ببینید.
جاوا
شما می توانید یک کد وضعیت gRPC را استخراج کنید که جزئیات مربوط به خطا را از TripUpdateError
برگردانده شده از onTripUpdateError()
ارائه می دهد.
// Called when there is a trip update error.
@Override
public void onTripUpdateError(TripInfo tripInfo, TripUpdateError error) {
Status.Code code = error.getStatusCode();
}
کاتلین
شما می توانید یک کد وضعیت gRPC را استخراج کنید که جزئیات مربوط به خطا را از TripUpdateError
برگردانده شده از onTripUpdateError()
ارائه می دهد.
// Called when there is a trip update error.
override fun onTripUpdateError(tripInfo: TripInfo, error: TripUpdateError) {
val code = error.getStatusCode()
}
کدهای وضعیت را تفسیر کنید
کدهای وضعیت دو نوع خطا را پوشش می دهند: خطاهای مربوط به سرور و شبکه و خطاهای سمت سرویس گیرنده.
خطاهای سرور و شبکه
کدهای وضعیت زیر مربوط به خطاهای شبکه یا سرور هستند و برای رفع آنها نیازی به اقدامی ندارید. Consumer SDK به طور خودکار از آنها بازیابی می شود.
کد وضعیت | توضیحات |
---|---|
سقط شد | سرور ارسال پاسخ را متوقف کرد. این معمولاً به دلیل مشکل سرور ایجاد می شود. |
لغو شد | سرور پاسخ خروجی را خاتمه داد. این معمولا زمانی اتفاق می افتد که برنامه به پسزمینه ارسال میشود، یا زمانی که تغییر حالتی در آن وجود دارد اپلیکیشن مصرف کننده |
قطع شد | |
DEADLINE_EXCEEDED | پاسخ سرور خیلی طول کشید. |
در دسترس نیست | سرور در دسترس نبود این معمولاً به دلیل یک مشکل شبکه ایجاد می شود. |
خطاهای مشتری
کدهای وضعیت زیر مربوط به خطاهای کلاینت هستند و شما باید برای رفع آنها اقدام کنید. Consumer SDK همچنان به تلاش مجدد برای بازخوانی سفر تا پایان اشتراکگذاری سفر ادامه میدهد، اما تا زمانی که اقدامی انجام ندهید، بازیابی نمیشود.
کد وضعیت | توضیحات |
---|---|
INVALID_ARGUMENT | برنامه مصرف کننده یک نام سفر نامعتبر را مشخص کرده است. نام سفر باید از فرمت providers/{provider_id}/trips/{trip_id} پیروی کند. |
NOT_FOUND | سفر هرگز ایجاد نشد. |
PERMISSION_DENIED | برنامه مصرف کننده مجوزهای کافی ندارد. این خطا زمانی رخ می دهد که:
|
RESOURCE_EXHAUSTED | سهمیه منابع صفر است، یا سرعت جریان ترافیک از حد مجاز بیشتر است. |
بدون احراز هویت | این درخواست به دلیل یک توکن JWT نامعتبر احراز هویت نشد. این خطا یا زمانی رخ می دهد که توکن JWT بدون شناسه سفر امضا شده باشد یا زمانی که توکن JWT منقضی شده باشد. |