Seguire un viaggio in iOS

Seleziona la piattaforma: Android iOS JavaScript

Quando segui un viaggio, l'app per i consumatori mostra al consumatore la posizione del veicolo appropriato. Per farlo, l'app deve iniziare a seguire un viaggio, aggiornarne l'avanzamento e interrompere il monitoraggio al termine.

Questo documento illustra il funzionamento della procedura.

Iniziare a seguire un viaggio

Ecco come iniziare a seguire un viaggio:

  • Raccogliere tutti gli input degli utenti, come i luoghi di consegna e ritiro, da un ViewController.

  • Crea un nuovo ViewController per iniziare a seguire direttamente un viaggio.

L'esempio seguente mostra come iniziare a seguire un viaggio immediatamente dopo il caricamento della visualizzazione.

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

Objective-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];
}

Smettere di seguire un viaggio

Puoi interrompere il monitoraggio di un viaggio quando è completato o annullato. L'esempio seguente mostra come interrompere la condivisione del viaggio attivo.

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

Objective-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];
}

Aggiornare l'avanzamento della corsa

Durante un viaggio, puoi gestire l'avanzamento come segue:

Quando una corsa termina o viene annullata, interrompi l'ascolto degli aggiornamenti. Per un esempio, consulta Esempio di interruzione dell'ascolto di aggiornamenti.

Esempio di inizio dell'ascolto degli aggiornamenti

L'esempio seguente mostra come registrare il callback tripModel.

Swift

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

Objective-C

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

Esempio di interruzione dell'ascolto degli aggiornamenti

L'esempio seguente mostra come annullare la registrazione del callback tripModel.

Swift

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

Objective-C

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

Esempio di gestione degli aggiornamenti delle corse

L'esempio seguente mostra come implementare il protocollo GMTCTripModelSubscriber per gestire i callback quando viene aggiornato lo stato della corsa.

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

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

Gestire gli errori relativi ai viaggi

Se hai sottoscritto tripModel e si verifica un errore, puoi ottenere il callback di tripModel implementando il metodo delegato tripModel(_:didFailUpdateTripWithError:). I messaggi di erroreseguono lo standard di errore di Google Cloud. Per definizioni dettagliate dei messaggi di errore e per tutti i codici di errore, consulta la documentazione relativa agli errori di Google Cloud.

Di seguito sono riportati alcuni errori comuni che possono verificarsi durante il monitoraggio dei viaggi:

HTTP RPC Descrizione
400 INVALID_ARGUMENT Il client ha specificato un nome di viaggio non valido. Il nome della corsa deve seguire il formato providers/{provider_id}/trips/{trip_id}. provider_id deve essere l'ID del progetto cloud di proprietà del fornitore di servizi.
401 UNAUTHENTICATED Questo errore viene visualizzato se non sono presenti credenziali di autenticazione valide. Ad esempio, se il token JWT è firmato senza un ID corsa o se è scaduto.
403 PERMISSION_DENIED Questo errore viene visualizzato se il client non dispone delle autorizzazioni sufficienti (ad esempio, un utente con il ruolo Consumer tenta di chiamare updateTrip), se il token JWT non è valido o se l'API non è abilitata per il progetto client. Il token JWT potrebbe non essere presente o il token potrebbe essere firmato con un ID corsa che non corrisponde all'ID corsa richiesto.
429 RESOURCE_EXHAUSTED La quota di risorse è pari a zero o la frequenza del traffico supera il limite.
503 UNAVAILABLE Servizio non disponibile. In genere, il server non è attivo.
504 DEADLINE_EXCEEDED Scadenza richiesta superata. Questo errore si verifica solo se chi chiama imposta una scadenza più breve di quella predefinita del metodo (ovvero la scadenza richiesta non è sufficiente per l'elaborazione della richiesta da parte del server) e la richiesta non è stata completata entro la scadenza.

Gestire gli errori dell'SDK consumer

L'SDK Consumer invia gli errori di aggiornamento dei viaggi all'app consumer utilizzando un meccanismo di callback. Il parametro di callback è un tipo di ritorno specifico della piattaforma ( TripUpdateError su Android e NSError su iOS).

Codici di stato dell'estrazione

Gli errori passati al callback sono in genere errori gRPC e puoi anche ricavarne ulteriori informazioni sotto forma di codice di stato. Per l'elenco completo dei codici di stato, consulta Codici di stato e relativo utilizzo in gRPC.

Swift

NSError viene richiamato in 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
    ...
  }
}

Objective-C

NSError viene richiamato in 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;
    ...
  }
}

Interpreta i codici di stato

I codici di stato coprono due tipi di errori: errori relativi al server e alla rete ed errori lato client.

Errori del server e della rete

I seguenti codici di stato si riferiscono a errori di rete o del server e non è necessario intraprendere alcuna azione per risolverli. L'SDK Consumer si riprende automaticamente da questi errori.

Codice di statoDescrizione
ABORTED Il server ha smesso di inviare la risposta. Di solito è causato da un problema del server.
CANCELLATO Il server ha terminato la risposta in uscita. Questo accade normalmente quando l'app viene inviata in background o quando si verifica una modifica di stato nell'app consumer.
INTERRUPTED
DEADLINE_EXCEEDED Il server ha impiegato troppo tempo per rispondere.
UNAVAILABLE Il server non era disponibile. In genere questo problema è causato da un problema di rete.

Errori client

I seguenti codici di stato si riferiscono a errori del client e devi intervenire per risolverli. L'SDK Consumer continua a riprovare ad aggiornare il viaggio finché non interrompi la condivisione del viaggio, ma non lo recupererà finché non intervieni.

Codice di statoDescrizione
INVALID_ARGUMENT L'app Consumer ha specificato un nome di corsa non valido. Il nome della corsa deve seguire il formato providers/{provider_id}/trips/{trip_id}.
NOT_FOUND Il viaggio non è mai stato creato.
PERMISSION_DENIED L'app Consumer non dispone di autorizzazioni sufficienti. Questo errore si verifica quando:
  • L'app Consumer non dispone delle autorizzazioni
  • L'SDK Consumer non è abilitato per il progetto nella console Google Cloud.
  • Il token JWT non è presente o non è valido.
  • Il token JWT è firmato con un ID corsa che non corrisponde alla corsa richiesta.
RESOURCE_EXHAUSTED La quota di risorse è pari a zero o la frequenza del flusso di traffico supera il limite di velocità.
UNAUTHENTICATED L'autenticazione della richiesta non è riuscita a causa di un token JWT non valido. Questo errore si verifica quando il token JWT è firmato senza un ID corsa o quando il token JWT è scaduto.