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
ViewControllerper 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:
Inizia a monitorare gli aggiornamenti. Per un esempio, consulta Esempio di inizio dell'ascolto degli aggiornamenti.
Gestire gli aggiornamenti delle corse. Per un esempio, consulta Esempio di gestione degli aggiornamenti della corsa
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 del 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 stato | Descrizione |
|---|---|
| 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 stato | Descrizione |
|---|---|
| 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:
|
| 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. |