Introduzione all'SDK Consumer per Android

Puoi utilizzare l'SDK consumer per creare ed eseguire un'app consumer di base integrata con i servizi di backend Ride and Deliveries on demand. Puoi creare un'app Trip and Order Progress che può visualizzare una corsa attiva, rispondere agli aggiornamenti della corsa e gestire gli errori della corsa.

Poiché l'SDK Consumer ha un'architettura modulare, puoi utilizzare le parti dell'API che vuoi utilizzare per la tua app specifica e integrarle con le tue API, i servizi di backend forniti da Fleet Engine e le API aggiuntive di Google Maps Platform.

Requisiti minimi di sistema

Sul dispositivo deve essere installato Android 5.0 (livello API 21) o versioni successive.

Prerequisiti

Gli SDK Android per i trasporti e la logistica vengono pubblicati in un repository Maven di Artifact Registry. Il repository include i file Project Object Model (.pom) dell'SDK e i documenti Java offline.

Accedi

Se sei un cliente Google Workspace, crea un gruppo Workspace, ad esempio google-maps-platform-sdk-users@workspacedomain.com, durante l'onboarding e fornisci il nome a Google. Questo è l'approccio consigliato. Il tuo gruppo di Workspace verrà quindi aggiunto a una lista consentita che concede l'accesso al repository Maven gmp-artifacts/transportation. Conferma che l'elenco delle email degli utenti e degli account di servizio che richiedono l'accesso sia incluso.

Se la tua organizzazione non può creare gruppi Workspace, invia a Google un elenco di indirizzi email degli account utente e di servizio che devono accedere a questi elementi.

Sviluppo locale

Per lo sviluppo locale, è sufficiente accedere con Cloud SDK.

gcloud auth login

L'indirizzo email utilizzato per l'accesso deve essere un membro del gruppo Workspace.

Automazione (sistemi build o integrazione continua)

Configura gli host di automazione in base alle best practice:

• Se il tuo processo viene eseguito in un ambiente Google Cloud, utilizza il rilevamento automatico delle credenziali.

• Altrimenti, archivia il file della chiave dell'account di servizio in una posizione sicura nel file system dell'host e imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS in modo appropriato.

L'indirizzo email dell'account di servizio associato alle credenziali deve essere membro del gruppo Workspace.

Configurazione

Configura Maven o Gradle per rilevare automaticamente le credenziali dell'utente o del servizio.

plugins {
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
}
repositories {
  maven {
    url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
  }
}

<repositories>
  <repository>
    <id>gmp-artifacts</id>
    <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
    <releases>
      <enabled>true</enabled>
    </releases>
  </repository>
</repositories>
<build>
  <extensions>
    <extension>
      <groupId>com.google.cloud.artifactregistry</groupId>
      <artifactId>artifactregistry-maven-wagon</artifactId>
      <version>2.1.5</version>
    </extension>
  </extensions>
</build>

Per informazioni sulla verifica dell'accesso, consulta Gestione dei pacchetti Java.

Configurazione progetto

Per utilizzare l'SDK Consumer per Android, la tua app deve avere come target minSdkVersion 19 o versioni successive.

Per eseguire un'app creata con l'SDK Consumer, è necessario che sul dispositivo Android sia installato Google Play Services.

Configura il progetto di sviluppo

Per configurare il progetto di sviluppo e ricevere una chiave API per il progetto in Google Cloud Console:

1. Creare un nuovo progetto della console Google Cloud o selezionare un progetto esistente da utilizzare con l'SDK Consumer. Attendi qualche minuto finché il nuovo progetto non sarà visibile nella console Google Cloud.

2. Per eseguire l'app demo, il tuo progetto deve avere accesso all'SDK di Maps per Android. In Google Cloud Console, seleziona API e servizi > Libreria, quindi cerca e attiva l'SDK Maps per Android.

3. Per ottenere una chiave API per il progetto, seleziona API e servizi > Credenziali > Crea credenziali > Chiave API. Per scoprire di più su come ottenere una chiave API, consulta Ottenere una chiave API.

Aggiungi l'SDK Consumer alla tua app

L'SDK Consumer è disponibile tramite un Repository Maven privato. Il repository include i file Project Object Model (.pom) dell'SDK e i documenti Java. Per aggiungere l'SDK Consumer alla tua app:

1. Configura l'ambiente per accedere al repository Maven dell'host come descritto in Ottenere l'accesso.

   Se hai dichiarato la configurazione centralizzata della gestione delle dipendenze in settings.gradle, disabilitala come segue.

   • Rimuovi il seguente blocco di codice in settings.gradle:

     import org.gradle.api.initialization.resolve.RepositoriesMode
     dependencyResolutionManagement {
         repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
         repositories {
             google()
             mavenCentral()
         }
     }
     

2. Aggiungi la seguente dipendenza alla configurazione Gradle o Maven, sostituendo il segnaposto VERSION_NUMBER con la versione desiderata dell'SDK Consumer.

   Gradle

   Aggiungi il seguente codice al tuo build.gradle:

   dependencies {
     ...
     implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER'
   }
   

   Maven

   Aggiungi il seguente codice al tuo pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
       <artifactId>transportation-consumer</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

Aggiungi la chiave API alla tua app

Dopo aver aggiunto l'SDK Consumer alla tua app, aggiungi la chiave API alla tua app. Devi utilizzare la chiave API del progetto che hai ottenuto durante la configurazione del progetto di sviluppo.

Questa sezione descrive come archiviare la chiave API in modo che possa essere fatto riferimento in modo più sicuro dall'app. Non dovresti controllare la chiave API nel sistema di controllo della versione. Deve essere archiviato nel file local.properties, che si trova nella directory principale del tuo progetto. Per ulteriori informazioni sul file local.properties, consulta File delle proprietà Gradle.

Per semplificare questa attività, puoi utilizzare il plug-in Secrets Gradle per Android.

Per installare il plug-in e archiviare la chiave API:

1. Apri il file build.gradle a livello principale e aggiungi il codice seguente all'elemento dependencies in buildscript.

   Trendy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
       }
   }
   

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0")
       }
   }
   

2. Apri il file build.gradle a livello di app e aggiungi il seguente codice all'elemento plugins.

   Trendy

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   

   Kotlin

   id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   

3. Se utilizzi Android Studio, sincronizza il progetto con Gradle.

4. Apri local.properties nella directory a livello di progetto e aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API.

   MAPS_API_KEY=YOUR_API_KEY
   

5. Nel file AndroidManifest.xml, vai alla pagina com.google.android.geo.API_KEY e aggiorna l'attributo android:value nel seguente modo:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
   

L'esempio seguente mostra un manifest completo per un'app di esempio.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.consumerapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/_AppTheme">

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${MAPS_API_KEY}" />

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Includi le attribuzioni richieste nella tua app

Se utilizzi l'SDK Consumer nella tua app, devi includere il testo di attribuzione e le licenze open source nella sezione delle note legali della tua app. È meglio includere le attribuzioni come voce di menu indipendente o come parte di una voce di menu Informazioni.

Puoi trovare il testo di attribuzione richiesto e le licenze open source nel file ZIP Ridesharing Consumer SDK:

• NOTICE.txt
• LICENSES.txt

Autenticazione SDK consumer

L'SDK consumer fornisce l'autenticazione tramite token web JSON. Un token web JSON (JWT) è un token di accesso di base JSON che fornisce una o più rivendicazioni su un servizio. Ad esempio, un server potrebbe generare un token con la dichiarazione "logato come amministratore" e fornirlo a un client. Il client può quindi utilizzare il token per dimostrare che ha eseguito l'accesso come amministratore.

L'SDK consumer utilizza il token web JSON fornito dall'applicazione per comunicare con il parco risorse. Per ulteriori informazioni, consulta Autenticazione e autorizzazione del parco risorse.

Il token di autorizzazione consente di accedere ai seguenti servizi di Fleet Engine:

• TripService: consente all'SDK per i consumatori di accedere a dettagli sulla corsa, tra cui la posizione del veicolo, il percorso e l'orario di arrivo stimato. I token di autorizzazione per il servizio di viaggio devono includere una rivendicazione tripid:TRIP_ID nell'intestazione authorization del token, dove TRIP_ID è l'ID corsa.
• VehicleService: fornisce all'SDK Consumer le informazioni sulla posizione del veicolo arricchita per la visualizzazione del livello di densità del veicolo e la stima degli ATE. Poiché l'SDK Consumer utilizza solo le località fughed, i token di autorizzazione per il servizio veicolo non richiedono una rivendicazione vehicleid.

JSON Token web web

L'SDK consumer registra un callback del token di autorizzazione con l'applicazione durante l'inizializzazione. L'SDK chiama l'applicazione per ricevere un token per tutte le richieste di rete che richiedono l'autorizzazione.

Ti consigliamo vivamente di utilizzare i token di autorizzazione della cache di implementazione dei callback e di aggiornarli solo una volta trascorso il tempo di expiry. I token devono essere emessi con una scadenza di un'ora.

Il callback del token di autorizzazione specifica quale token di servizio è necessario per il servizio TripService. Fornisce inoltre il tripId obbligatorio per il contesto.

Il seguente esempio di codice mostra come implementare un callback del token di autorizzazione.

class JsonAuthTokenFactory implements AuthTokenFactory {

  private static final String TOKEN_URL =
      "https://yourauthserver.example/token";

  private static class CachedToken {
    String tokenValue;
    long expiryTimeMs;
    String tripId;
  }

  private CachedToken token;

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  @Override
  public String getToken(AuthTokenContext context) {
    // If there is no existing token or token has expired, go get a new one.
    String tripId = context.getTripId();
    if (tripId == null) {
      throw new RuntimeException("Trip ID is missing from AuthTokenContext");
    }
    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        !tripId.equals(token.tripId)) {
      token = fetchNewToken(tripId);
    }
    return token.tokenValue;
  }

  private static CachedToken fetchNewToken(String tripId) {
    String url = TOKEN_URL + "/" + tripId;
    CachedToken token = new CachedToken();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();

      token.tokenValue = obj.get("ServiceToken").getAsString();
      token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      /*
      * The expiry time could be an hour from now, but just to try and avoid
      * passing expired tokens, we subtract 5 minutes from that time.
      */
      token.expiryTimeMs -= 5 * 60 * 1000;
    } catch (IOException e) {
      /*
      * It's OK to throw exceptions here. The error listeners will receive the
      * error thrown here.
      */
      throw new RuntimeException("Could not get auth token", e);
    }
    token.tripId = tripId;

    return token;
  }
}

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  override fun getToken(context: AuthTokenContext): String {
    // If there is no existing token or token has expired, go get a new one.
    val tripId = 
      context.getTripId() ?: 
        throw RuntimeException("Trip ID is missing from AuthTokenContext")

    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        tripId != token.tripId) {
      token = fetchNewToken(tripId)
    }

    return token.tokenValue
  }

  class CachedToken(
    var tokenValue: String? = "", 
    var expiryTimeMs: Long = 0,
    var tripId: String? = "",
  )

  private companion object {
    const val TOKEN_URL = "https://yourauthserver.example/token"

    fun fetchNewToken(tripId: String) {
      val url = "$TOKEN_URL/$tripId"
      val token = CachedToken()

      try {
        val reader = InputStreamReader(URL(url).openStream())

        reader.use {
          val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()

          token.tokenValue = obj.get("ServiceToken").getAsString()
          token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()

          /*
          * The expiry time could be an hour from now, but just to try and avoid
          * passing expired tokens, we subtract 5 minutes from that time.
          */
          token.expiryTimeMs -= 5 * 60 * 1000
        }
      } catch (e: IOException) {
        /*
        * It's OK to throw exceptions here. The error listeners will receive the
        * error thrown here.
        */
        throw RuntimeException("Could not get auth token", e)
      }

      token.tripId = tripId

      return token
    }
  }
}

Inizializza l'API

Prima di seguire queste procedure, si presume che tu abbia abilitato i servizi appropriati e l'SDK Consumer.

Recupera l'istanza ConsumerApi

Per utilizzare l'SDK Consumer, la tua app deve inizializzare ConsumerApi in modo asincrono. L'API è un singleton. Il metodo di inizializzazione richiede un AuthTokenFactory. La fabbrica genera nuovi token JWT per l'utente quando necessario.

providerId è l'ID progetto del progetto Google Cloud. Consulta la Guida dell'utente di Fleet Engine per ulteriori informazioni sulla creazione del progetto.

La tua app deve implementare l'AuthTokenFactory come descritto in Autenticazione dell'SDK del consumatore.

Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
    this, "myProviderId", authTokenFactory);

consumerApiTask.addOnSuccessListener(
  consumerApi -> this.consumerApi = consumerApi);

val consumerApiTask =
  ConsumerApi.initialize(this, "myProviderId", authTokenFactory)

consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
  this@YourActivity.consumerApi = consumerApi
}

Crea l'interfaccia utente

Puoi utilizzare ConsumerMapFragment o ConsumerMapView per creare l'interfaccia utente per la tua applicazione. ConsumerMapFragment ti consente di definire la tua mappa utilizzando un Fragment mentre ConsumerMapView ti consente di utilizzare un View. La funzionalità di ride sharing è la stessa sia in ConsumerMapView che in ConsumerMapFragment, quindi puoi sceglierne una in base a se View o Fragment sono i migliori per la tua applicazione.

Aggiunta del supporto per il drawable API 19 (KitKat) e Vector

Se il design dell'app richiede il supporto per i dispositivi API 19 (KitKat) e i drawable vettoriale, aggiungi il seguente codice alla tua attività. Questo codice estende AppCompatActivity per utilizzare i bozze di Vector nell'SDK Consumer.

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

Aggiungere il frammento o la vista della mappa

Puoi creare la mappa per visualizzare la condivisione dei percorsi in un frammento o una vista di Android, che hai definito nel file XML di layout dell'applicazione (situato in /res/layout). Il frammento (o la vista) fornisce quindi l'accesso alla mappa di condivisione del percorso, a cui la tua app può accedere e modificare. La mappa fornisce anche un handle per ConsumerController, che consente alla tua app di controllare e personalizzare l'esperienza di condivisione dei percorsi.

Mappa e controller di condivisione del percorso

Puoi definire la mappa di condivisione del percorso come frammento (tramite ConsumerMapFragment) o come vista (utilizzando ConsumerMapView), come mostrato nel seguente esempio di codice. Il tuo metodo onCreate() dovrebbe quindi chiamare getConsumerGoogleMapAsync(callback), che restituisce ConsumerGoogleMap in modo asincrono nel callback. In seguito, utilizzi ConsumerGoogleMap per visualizzare la condivisione del percorso e puoi aggiornarlo in base alle esigenze della tua app.

Frammento ConsumerMap

Devi definire il frammento nel file XML di layout dell'applicazione, come mostrato nell'esempio di codice seguente.

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

La chiamata a getConsumerGoogleMapAsync() deve provenire dal metodo onCreate().

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

    // Find the ConsumerMapFragment.
    ConsumerMapFragment consumerMapFragment =
        (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

    // Initiate the callback that returns the map.
    if (consumerMapFragment != null) {
      consumerMapFragment.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          });
    }
  }

}

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    // Find the ConsumerMapFragment.
    val consumerMapFragment =
      fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

    consumerMapFragment.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      }
    )
  }
}

ConsumerMapView

La vista può essere utilizzata in un frammento o in un'attività, come definito nel file XML.

<com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/consumer_map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

La chiamata a getConsumerGoogleMapAsync() deve provenire da onCreate(). Oltre al parametro di callback, richiede l'attività o il frammento contenitore e GoogleMapOptions (che può essere nullo) contenente attributi di configurazione per MapView. L'attività o la classe di base del frammento devono essere FragmentActivity o un supporto Fragment (rispettivamente), poiché forniscono accesso al relativo ciclo di vita.

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

Un MapView in un frammento è lo stesso dell'esempio precedente per MapView in un'attività, tranne per il fatto che il frammento gonfia il layout che include MapView nel metodo onCreateView() del frammento.

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

Regolare lo zoom della fotocamera per mettere a fuoco un percorso

Il pulsante La mia posizione predefinito integrato in Maps SDK centra la fotocamera sulla posizione del dispositivo.

Se è attiva una sessione di condivisione del percorso, potresti voler centrare la fotocamera per concentrarti sul percorso anziché sulla posizione del dispositivo.

SDK Consumer per soluzione integrata Android: AutoVideocamera

Per consentirti di concentrarti sul percorso anziché sulla posizione del dispositivo, l'SDK Consumer fornisce una funzionalità della fotocamera automatica abilitata per impostazione predefinita. La videocamera aumenta lo zoom per mettere a fuoco il percorso di condivisione del percorso e il tappa successiva.

Personalizzare il comportamento della videocamera

Se hai bisogno di un maggiore controllo sul comportamento della videocamera, puoi disattivare o attivare la fotocamera automatica utilizzando ConsumerController.setAutoVideocameraEnabled().

ConsumerController.getcameraUpdate() restituisce i limiti della videocamera consigliati in quel momento. Puoi quindi fornire questo CameraUpdate come argomento a GoogleMap.move Camera() o GoogleMap.animate Camera().

Accedere a car sharing e mappe

Per supportare il ridesharing e l'interazione con la mappa nella tua applicazione, devi accedere a ConsumerGoogleMap e ConsumerController. ConsumerMapFragment e ConsumerMapView restituiscono in modo asincrono ConsumerGoogleMap in ConsumerMapReadyCallback. ConsumerGoogleMap restituisce ConsumerController da getConsumerController(). Puoi accedere a ConsumerGoogleMap e ConsumerController come segue.

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

Mappa Google di consumatore

ConsumerGoogleMap è una classe wrapper per la classe GoogleMap. Consente all'app di interagire con la mappa utilizzando un'API equivalente a GoogleMap. L'uso della mappa consumer consente alla tua app e alla condivisione dei viaggi di interagire perfettamente con la stessa mappa Google sottostante. Ad esempio, GoogleMap consente una sola registrazione di callback, ma ConsumerGoogleMap supporta i doppi callback registrati. Questi callback consentono alla tua app e alla condivisione delle corse di registrare i callback chiamati in sequenza.

ConsumerController

ConsumerController consente di accedere alle funzionalità di condivisione delle corse, tra cui il monitoraggio dei viaggi, il controllo dello stato delle corse e l'impostazione delle località.

Configurare la condivisione dei percorsi

Dopo che il backend ha abbinato un consumatore a un veicolo, utilizza JourneySharingSession per iniziare il percorso di condivisione dell'interfaccia utente. La condivisione del percorso mostra la posizione e il percorso del veicolo corrispondenti. Dopo aver implementato l'SDK nell'app, puoi aggiungere la funzionalità di monitoraggio dei viaggi, ascolto degli aggiornamenti e gestione degli errori. Le seguenti procedure presuppongono che i servizi di backend siano in atto e che i tuoi servizi per mettere in contatto i consumatori con i veicoli siano operativi.

1. Registra un listener su un oggetto TripModel per ricevere dettagli sulla corsa, come l'orario di arrivo stimato e la distanza che il veicolo deve percorrere prima dell'arrivo.

   Java

   // 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) {
       // ...
     }
   
     // ...
   });
   

   Kotlin

   // 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?,
       ) {
         // ...
       }
   
     // ...
   })
   

2. Configura il viaggio utilizzando TripModelOptions.

   Java

   // Set refresh interval to 2 seconds.
   TripModelOptions tripOptions =
       TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
   tripModel.setTripModelOptions(tripOptions);
   

   Kotlin

   // Set refresh interval to 2 seconds.
   val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
   tripModel.setTripModelOptions(tripOptions)
   

Interrompi condivisione percorso

Assicurati di interrompere la condivisione del percorso quando non è più necessaria, ad esempio quando l'attività host viene distrutta. L'interruzione della condivisione del percorso interrompe anche le richieste di rete a Fleet Engine e previene le perdite di memoria.

Il seguente codice di esempio illustra come interrompere la condivisione del percorso.

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

Gestire gli errori della corsa

Il metodo onTripRefreshError segnala errori che si verificano durante il monitoraggio delle corse. La mappatura degli errori degli SDK consumer segue le stesse linee guida HTTP/RPC stabilite per Google Cloud Platform. Gli errori comuni visualizzati durante il monitoraggio delle corse includono:

Per ulteriori informazioni, consulta Gestione degli errori degli SDK per i consumatori.