این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

یک سفر را در iOS دنبال کنید

پلتفرم را انتخاب کنید: Android iOS JavaScript

هنگامی که یک سفر را دنبال می کنید، برنامه مصرف کننده شما مکان وسیله نقلیه مناسب را به مصرف کننده نشان می دهد. برای انجام این کار، برنامه شما باید شروع به دنبال کردن یک سفر کند، پیشرفت سفر را به‌روزرسانی کند و پس از اتمام آن سفر را دنبال نکند.

این سند نحوه عملکرد آن فرآیند را پوشش می دهد.

دنبال کردن یک سفر را شروع کنید

در اینجا نحوه شروع به دنبال کردن یک سفر با استفاده از اشتراک گذاری سفر آمده است:

همه ورودی‌های کاربر مانند مکان‌های تحویل و تحویل را از ViewController جمع‌آوری کنید.
برای شروع مستقیم اشتراک گذاری سفر، یک ViewController جدید ایجاد کنید.

مثال زیر نشان می دهد که چگونه می توان یک سفر را بلافاصله پس از بارگیری نمای شروع کرد.

سویفت

/*
 * 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()
}

هدف-C

/*
 * 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];
}

یک سفر را دنبال نکنید

وقتی سفری کامل یا لغو شد، آن را دنبال نمی‌کنید. مثال زیر نحوه توقف اشتراک‌گذاری سفر فعال را نشان می‌دهد.

سویفت

/*
 * 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)
}

هدف-C

/*
 * 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];
}

به روز رسانی پیشرفت سفر

در طول یک سفر، پیشرفت سفر را به صورت زیر مدیریت می کنید:

شروع به گوش دادن برای به روز رسانی کنید . برای مثال، به مثال شروع گوش دادن برای به‌روزرسانی‌ها را ببینید.
هر گونه به روز رسانی سفر را مدیریت کنید . برای مثال، نمونه به‌روزرسانی‌های Handle trip را ببینید

وقتی یک سفر کامل شد یا لغو شد، گوش دادن به به‌روزرسانی‌ها را متوقف کنید . برای مثال، به مثال توقف گوش دادن برای به‌روزرسانی‌ها را ببینید.

شروع به گوش دادن برای مثال به روز رسانی کنید

مثال زیر نحوه ثبت callback tripModel را نشان می دهد.

سویفت

/*
 * MapViewController.swift
 */
override func viewDidLoad() {
  super.viewDidLoad()
  // Register for trip update events.
  self.currentTripModel.register(self)
}

هدف-C

/*
 * MapViewController.m
 */
- (void)viewDidLoad {
  [super viewDidLoad];
  // Register for trip update events.
  [self.currentTripModel registerSubscriber:self];
  ...
}

به عنوان مثال گوش دادن به به روز رسانی ها را متوقف کنید

مثال زیر نحوه لغو ثبت نام tripModel callback را نشان می دهد.

سویفت

/*
 * MapViewController.swift
 */
deinit {
  self.currentTripModel.unregisterSubscriber(self)
}

هدف-C

/*
 * MapViewController.m
 */
- (void)dealloc {
  [self.currentTripModel unregisterSubscriber:self];
  ...
}

نمونه به‌روزرسانی‌های مربوط به سفر

مثال زیر نحوه پیاده‌سازی پروتکل GMTCTripModelSubscriber را برای رسیدگی به تماس‌ها هنگام به‌روزرسانی وضعیت سفر نشان می‌دهد.

سویفت

/*
 * 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.
}

هدف-C

/*
 * 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 مشترک شده‌اید و خطایی رخ می‌دهد، می‌توانید با اجرای روش delegate tripModel(_:didFailUpdateTripWithError:) پاسخ تماس tripModel را دریافت کنید. پیام های خطا از استاندارد 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 را ببینید.

سویفت

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
    ...
  }
}

هدف-C

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;
    ...
  }
}

کدهای وضعیت را تفسیر کنید

کدهای وضعیت دو نوع خطا را پوشش می دهند: خطاهای مربوط به سرور و شبکه و خطاهای سمت سرویس گیرنده.

خطاهای سرور و شبکه

کدهای وضعیت زیر مربوط به خطاهای شبکه یا سرور هستند و برای رفع آنها نیازی به اقدامی ندارید. Consumer SDK به طور خودکار از آنها بازیابی می شود.

کد وضعیت	توضیحات
سقط شد	سرور ارسال پاسخ را متوقف کرد. این معمولاً به دلیل مشکل سرور ایجاد می شود.
لغو شد	سرور پاسخ خروجی را خاتمه داد. این معمولا زمانی اتفاق می افتد که برنامه به پس‌زمینه ارسال می‌شود، یا زمانی که تغییر حالتی در آن وجود دارد اپلیکیشن مصرف کننده
قطع شد
DEADLINE_EXCEEDED	پاسخ سرور خیلی طول کشید.
در دسترس نیست	سرور در دسترس نبود این معمولاً به دلیل یک مشکل شبکه ایجاد می شود.

خطاهای مشتری

کدهای وضعیت زیر مربوط به خطاهای کلاینت هستند و شما باید برای رفع آنها اقدام کنید. Consumer SDK همچنان به تلاش مجدد برای بازخوانی سفر تا پایان اشتراک‌گذاری سفر ادامه می‌دهد، اما تا زمانی که اقدامی انجام ندهید، بازیابی نمی‌شود.

کد وضعیت	توضیحات
INVALID_ARGUMENT	برنامه مصرف کننده یک نام سفر نامعتبر را مشخص کرده است. نام سفر باید از فرمت `providers/{provider_id}/trips/{trip_id}` پیروی کند.
NOT_FOUND	سفر هرگز ایجاد نشد.
PERMISSION_DENIED	برنامه Consumer مجوزهای کافی ندارد. این خطا زمانی رخ می دهد که: برنامه Consumer مجوز ندارد Consumer SDK برای پروژه در Google Cloud Console فعال نیست. رمز JWT یا گم شده یا نامعتبر است. رمز JWT با یک شناسه سفر امضا شده است که با سفر درخواستی مطابقت ندارد.
RESOURCE_EXHAUSTED	سهمیه منابع صفر است، یا سرعت جریان ترافیک از حد مجاز بیشتر است.
بدون احراز هویت	این درخواست به دلیل یک توکن JWT نامعتبر احراز هویت نشد. این خطا یا زمانی رخ می دهد که توکن JWT بدون شناسه سفر امضا شده باشد یا زمانی که توکن JWT منقضی شده باشد.