وقتی سفری را دنبال میکنید، برنامه مصرفکننده شما مکان خودرو مناسب را به مصرفکننده نمایش میدهد. برای انجام این کار، برنامهتان باید دنبال کردن سفر را شروع کند، پیشرفت سفر را بهروز کند، و وقتی سفر تکمیل شد، دنبال کردن سفر را متوقف کند.
این سند نحوه عملکرد این فرایند را پوشش میدهد.
شروع دنبال کردن سفر
نحوه دنبال کردن سفر در اینجا آمده است:
همه ورودیهای کاربر مثل مکانهای سوار کردن و پیاده کردن را از
ViewControllerجمعآوری کنید.برای شروع دنبال کردن مستقیم سفر،
ViewControllerجدیدی ایجاد کنید.
مثال زیر نشان میدهد که چگونه بلافاصله پساز بار شدن نما، دنبال کردن سفر را شروع کنید.
Swift
/*
* MapViewController.swift
*/
override func viewDidLoad() {
super.viewDidLoad()
...
self.mapView = GMTCMapView(frame: UIScreen.main.bounds)
self.mapView.delegate = self
self.view.addSubview(self.mapView)
}
func mapViewDidInitializeCustomerState(_: GMTCMapView) {
self.mapView.pickupLocation = self.selectedPickupLocation
self.mapView.dropoffLocation = self.selectedDropoffLocation
self.startConsumerMatchWithLocations(
pickupLocation: self.mapView.pickupLocation!,
dropoffLocation: self.mapView.dropoffLocation!
) { [weak self] (tripName, error) in
guard let strongSelf = self else { return }
if error != nil {
// print error message.
return
}
let tripService = GMTCServices.shared().tripService
// Create a tripModel instance for listening the update of the trip
// specified by this trip name.
let tripModel = tripService.tripModel(forTripName: tripName)
// Create a journeySharingSession instance based on the tripModel
let journeySharingSession = GMTCJourneySharingSession(tripModel: tripModel)
// Add the journeySharingSession instance on the mapView for UI updating.
strongSelf.mapView.show(journeySharingSession)
// Register for the trip update events.
tripModel.register(strongSelf)
strongSelf.currentTripModel = tripModel
strongSelf.currentJourneySharingSession = journeySharingSession
strongSelf.hideLoadingView()
}
self.showLoadingView()
}
آبجکتیو-سی
/*
* MapViewController.m
*/
- (void)viewDidLoad {
[super viewDidLoad];
...
self.mapView = [[GMTCMapView alloc] initWithFrame:CGRectZero];
self.mapView.delegate = self;
[self.view addSubview:self.mapView];
}
// Handle the callback when the GMTCMapView did initialized.
- (void)mapViewDidInitializeCustomerState:(GMTCMapView *)mapview {
self.mapView.pickupLocation = self.selectedPickupLocation;
self.mapView.dropoffLocation = self.selectedDropoffLocation;
__weak __typeof(self) weakSelf = self;
[self startTripBookingWithPickupLocation:self.selectedPickupLocation
dropoffLocation:self.selectedDropoffLocation
completion:^(NSString *tripName, NSError *error) {
__typeof(self) strongSelf = weakSelf;
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;
// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
// Create a journeySharingSession instance based on the tripModel.
GMTCJourneySharingSession *journeySharingSession =
[[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
// Add the journeySharingSession instance on the mapView for updating the UI.
[strongSelf.mapView showMapViewSession:journeySharingSession];
// Register for trip update events.
[tripModel registerSubscriber:self];
strongSelf.currentTripModel = tripModel;
strongSelf.currentJourneySharingSession = journeySharingSession;
[strongSelf hideLoadingView];
}];
[self showLoadingView];
}
توقف دنبال کردن سفر
وقتی سفر تکمیل یا لغو شود، دنبال کردن آن را متوقف میکنید. مثال زیر نحوه توقف همرسانی سفر فعال را نشان میدهد.
Swift
/*
* MapViewController.swift
*/
func cancelCurrentActiveTrip() {
// Stop the tripModel
self.currentTripModel.unregisterSubscriber(self)
// Remove the journey sharing session from the mapView's UI stack.
self.mapView.hide(journeySharingSession)
}
آبجکتیو-سی
/*
* MapViewController.m
*/
- (void)cancelCurrentActiveTrip {
// Stop the tripModel
[self.currentTripModel unregisterSubscriber:self];
// Remove the journey sharing session from the mapView's UI stack.
[self.mapView hideMapViewSession:journeySharingSession];
}
بهروزرسانی پیشرفت سفر
درطول سفر، پیشرفت سفر را بهصورت زیر مدیریت میکنید:
شروع به گوش دادن برای بهروزرسانیها کنید. برای مثال، نمونه شروع گوش دادن به بهروزرسانیها را ببینید.
بهروزرسانیهای سفر را مدیریت کنید. برای نمونه، نمونه مدیریت بهروزرسانیهای سفر را ببینید
وقتی سفر تکمیل یا لغو شد، گوش دادن به بهروزرسانیها را متوقف کنید. برای مثال، مثال توقف گوش دادن به بهروزرسانیها را ببینید.
نمونه شروع گوش دادن به بهروزرسانیها
مثال زیر نحوه ثبت callback tripModel را نشان میدهد.
Swift
/*
* MapViewController.swift
*/
override func viewDidLoad() {
super.viewDidLoad()
// Register for trip update events.
self.currentTripModel.register(self)
}
آبجکتیو-سی
/*
* MapViewController.m
*/
- (void)viewDidLoad {
[super viewDidLoad];
// Register for trip update events.
[self.currentTripModel registerSubscriber:self];
...
}
مثال توقف گوش دادن به بهروزرسانیها
مثال زیر نحوه لغو ثبت tripModel
callback را نشان میدهد.
Swift
/*
* MapViewController.swift
*/
deinit {
self.currentTripModel.unregisterSubscriber(self)
}
آبجکتیو-سی
/*
* MapViewController.m
*/
- (void)dealloc {
[self.currentTripModel unregisterSubscriber:self];
...
}
نمونه مدیریت بهروزرسانیهای سفر
مثال زیر نحوه پیادهسازی پروتکل GMTCTripModelSubscriber را برای مدیریت تماسهای برگشتی هنگام بهروزرسانی وضعیت سفر نشان میدهد.
Swift
/*
* MapViewController.swift
*/
func tripModel(_: GMTCTripModel, didUpdate trip: GMTSTrip?, updatedPropertyFields: GMTSTripPropertyFields) {
// Update the UI with the new `trip` data.
self.updateUI(with: trip)
}
func tripModel(_: GMTCTripModel, didUpdate tripStatus: GMTSTripStatus) {
// Handle trip status did change.
}
func tripModel(_: GMTCTripModel, didUpdateActiveRouteRemainingDistance activeRouteRemainingDistance: Int32) {
// Handle remaining distance of active route did update.
}
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.
}
func tripModel(_: GMTCTripModel, didUpdateActiveRouteTraffic activeRouteTraffic: GMTSTrafficData?) {
// Handle trip active route traffic being updated.
}
آبجکتیو-سی
/*
* MapViewController.m
*/
#pragma mark - GMTCTripModelSubscriber implementation
- (void)tripModel:(GMTCTripModel *)tripModel
didUpdateTrip:(nullable GMTSTrip *)trip
updatedPropertyFields:(enum 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
didUpdateActiveRouteRemainingDistance:(int32_t)activeRouteRemainingDistance {
// Handle remaining distance of active route did update.
}
- (void)tripModel:(GMTCTripModel *)tripModel
didUpdateActiveRoute:(nullable NSArray<GMTSLatLng *> *)activeRoute {
// Handle trip active 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.
}
- (void)tripModel:(GMTCTripModel *)tripModel
didUpdateActiveRouteTraffic:(nullable GMTSTrafficData *)activeRouteTraffic {
// Handle trip active route traffic being updated.
}
رسیدگی به خطاهای سفر
اگر در tripModel مشترک شدهاید و خطایی رخ میدهد، میتوانید با پیادهسازی روش نماینده tripModel(_:didFailUpdateTripWithError:)، فراخوانی برگشتی tripModel را دریافت کنید. پیامهای خطا از استاندارد «خطای Google Cloud» پیروی میکنند. برای مشاهده تعاریف دقیق پیام خطا و همه کدهای خطا، به اسناد خطاهای Google Cloud مراجعه کنید.
در اینجا برخیاز خطاهای رایجی که ممکن است درطول پایش سفر رخ دهد آورده شده است:
| HTTP | فراخوانی رویهای دوردست | شرح |
|---|---|---|
| ۴۰۰ | INVALID_ARGUMENT | نام سفر مشخصشده توسط مشتری نامعتبر است. نام سفر باید از
قالب providers/{provider_id}/trips/{trip_id} پیروی کند. provider_id باید شناسه «پروژه ابری» متعلق به ارائهدهنده خدمات باشد. |
| 401 | اصالتسنجینشده | اگر اعتبارنامه اصالتسنجی معتبری وجود نداشته باشد، این خطا را دریافت میکنید. برای مثال، اگر کد JWT بدون شناسه سفر امضا شده باشد یا کد JWT منقضی شده باشد. |
| 403 | PERMISSION_DENIED | اگر مشتری اجازه کافی نداشته باشد (برای مثال، کاربری با نقش مصرفکننده سعی کند updateTrip را فراخوانی کند)، اگر توکن JWT نامعتبر باشد، یا اگر API برای پروژه مشتری فعال نشده باشد، این خطا را دریافت میکنید. ممکن است کد JWT وجود نداشته باشد یا کد با شناسه سفری امضا شده باشد که با شناسه سفر درخواستشده مطابقت ندارد. |
| 429 | RESOURCE_EXHAUSTED | سهمیه منبع صفر است یا نرخ ترافیک از حد مجاز فراتر رفته است. |
| ۵۰۳ | دردسترس نیست | سرویس دردسترس نیست. معمولاً سرور ازکار افتاده است. |
| 504 | DEADLINE_EXCEEDED | مهلت درخواست بهپایان رسید. این خطا فقط زمانی رخ میدهد که تماسگیرنده مهلتی را تنظیم کند که کوتاهتر از مهلت پیشفرض روش باشد (یعنی مهلت درخواستشده برای پردازش درخواست توسط سرور کافی نباشد) و درخواست در مهلت مقرر تکمیل نشود. |
رسیدگی به خطاهای کیت توسعه نرمافزار مصرفکننده
«کیت توسعه نرمافزار مصرفکننده» خطاهای بهروزرسانی سفر را بااستفاده از سازوکار فراخوانی برگشتی به برنامه مصرفکننده ارسال میکند. پارامتر callback یک نوع پاسخ مختص پلاتفرم است (
TripUpdateError
در Android، و
NSError
در iOS).
استخراج کدهای وضعیت
خطاهایی که به فراخوان برگشتی ارسال میشوند معمولاً خطاهای gRPC هستند و همچنین میتوانید اطلاعات بیشتری را بهصورت کد وضعیت از آنها استخراج کنید. برای فهرست کامل کدهای وضعیت، به کدهای وضعیت و کاربرد آنها در gRPC مراجعه کنید.
Swift
NSError در tripModel(_:didFailUpdateTripWithError:) بازخوانی میشود.
// Called when there is a trip update error.
func tripModel(_ tripModel: GMTCTripModel, didFailUpdateTripWithError error: Error?) {
// Check to see if the error comes from gRPC.
if let error = error as NSError?, error.domain == "io.grpc" {
let gRPCErrorCode = error.code
...
}
}
آبجکتیو-سی
NSError در tripModel:didFailUpdateTripWithError: بازخوانی میشود.
// Called when there is a trip update error.
- (void)tripModel:(GMTCTripModel *)tripModel didFailUpdateTripWithError:(NSError *)error {
// Check to see if the error comes from gRPC.
if ([error.domain isEqualToString:@"io.grpc"]) {
NSInteger gRPCErrorCode = error.code;
...
}
}
تفسیر کدهای وضعیت
کدهای وضعیت دو نوع خطا را پوشش میدهند: خطاهای مربوط به سرور و شبکه، و خطاهای سمت کارخواه.
خطاهای سرور و شبکه
کدهای وضعیت زیر مربوط به خطاهای شبکه یا سرور هستند و برای حل آنها نیازی به انجام هیچ اقدامی ندارید. «کیت توسعه نرمافزار مصرفکننده» بهطور خودکار از آنها بازیابی میشود.
| کد وضعیت | شرح |
|---|---|
| لغوشده | سرور ارسال پاسخ را متوقف کرد. این مشکل معمولاً بهدلیل مشکل سرور رخ میدهد. |
| لغو شد | سرور پاسخ خروجی را خاتمه داد. این معمولاً
زمانی اتفاق میافتد که
برنامه به پسزمینه ارسال میشود، یا زمانی که تغییری در وضعیت برنامه «مصرفکننده» رخ میدهد. |
| قطعشده | |
| DEADLINE_EXCEEDED | پاسخ دادن سرور خیلی طول کشید. |
| دردسترس نیست | سرور دردسترس نبود. این مشکل معمولاً بهدلیل مشکل شبکه رخ میدهد. |
خطاهای کارخواه
کدهای وضعیت زیر مربوط به خطاهای مشتری است و برای حل آنها باید اقدام کنید. «کیت توسعه نرمافزار مصرفکننده» تا زمانی که همرسانی سفر را پایان دهید، به تلاش مجدد برای بازآوری سفر ادامه میدهد، اما تا زمانی که اقدام نکنید، بازیابی نخواهد شد.
| کد وضعیت | شرح |
|---|---|
| INVALID_ARGUMENT | برنامه «مصرفکننده» نام سفر نامعتبری را مشخص کرده است؛ نام سفر باید از قالب providers/{provider_id}/trips/{trip_id} پیروی کند.
|
| NOT_FOUND | سفر هرگز ایجاد نشده است. |
| PERMISSION_DENIED | برنامه «مصرفکننده» اجازههای کافی ندارد. این خطا زمانی رخ میدهد که:
|
| RESOURCE_EXHAUSTED | سهمیه منبع صفر است، یا نرخ جریان ترافیک از حد مجاز سرعت فراتر رفته است. |
| اصالتسنجینشده | اصالتسنجی درخواست بهدلیل کد JWT نامعتبر ناموفق بود. این خطا زمانی رخ میدهد که توکن JWT بدون شناسه سفر امضا شده باشد، یا زمانی که توکن JWT منقضی شده باشد. |