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 On-demand Rides and Deliveries Solution. Puoi creare un'app di avanzamento viaggi e ordini che può visualizzare una corsa attiva, rispondere agli aggiornamenti delle corse e gestire gli errori.

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

Requisiti minimi di sistema

Sul dispositivo mobile deve essere installato Android 6,0 (livello API 23) o versioni successive.

Configurazione della build e delle dipendenze

Le versioni 1.99.0 e successive dell'SDK consumer sono disponibili tramite Google Maven repository Git. Il canale del repository privato utilizzato in precedenza è stato ritirato.

repositories {
    ...
    google()
}

<project>
  ...
  <repositories>
    <repository>
      <id>google-maven-repository</id>
      <url>https://maven.google.com</url>
    </repository>
  </repositories>
  ...
</project>

Configurazione progetto

Per utilizzare l'SDK consumer per Android, la tua app deve avere come target minSdkVersion 23 o superiore.

Per eseguire un'app creata con l'SDK consumer, Android il dispositivo deve avere Google Play Services installato.

Configura il progetto di sviluppo

Per configurare il progetto di sviluppo e ottenere una chiave API: per il progetto nella console Google Cloud:

1. Crea un nuovo progetto nella console Google Cloud o selezionane uno esistente da utilizzare con l'SDK consumer. Attendi qualche minuto il nuovo progetto sia visibile nella console Google Cloud.

2. Per eseguire l'app demo, il progetto deve avere accesso a Maps SDK per Android. Nella console Google Cloud, seleziona API e Servizi > Library, quindi cerca e attiva Maps SDK per Android.

3. Ottieni una chiave API per il progetto selezionando API e Servizi > Credenziali > Crea le credenziali > chiave API. Per ulteriori informazioni su come ottenere una chiave API, consulta Ottieni una chiave API.

Aggiungi l'SDK consumer alla tua app

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

1. Configura l'ambiente per accedere al Repository Maven host come descritto in nella sezione precedente.

   Se hai dichiarato una configurazione per la gestione delle dipendenze centralizzata settings.gradle, disattivalo 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 Segnaposto VERSION_NUMBER per la versione desiderata dell'SDK consumer.

   Gradle

   Aggiungi il seguente codice a build.gradle:

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

   Maven

   Aggiungi il seguente codice a pom.xml:

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

3. L'SDK consumer dipende dall'SDK Maps. Questa dipendenza è configurata in modo da in modo che se la versione dell'SDK di Maps non sia esplicitamente definita in il file di configurazione della build come il seguente, quando una nuova versione di Maps quando viene rilasciato, l'SDK consumer continua a utilizzare la la versione di Maps SDK supportata richiesta.

   Gradle

   Aggiungi il seguente codice a build.gradle:

   dependencies {
     ...
     implementation 'com.google.android.gms:play-services-maps:18.1.0'
   }
   

   Maven

   Aggiungi il seguente codice a pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.gms</groupId>
       <artifactId>play-services-maps</artifactId>
       <version>18.1.0</version>
     </dependency>
   </dependencies>
   

Aggiungi la chiave API all'app

Dopo aver aggiunto l'SDK consumer all'app, aggiungi la chiave API. Devi usare la chiave API del progetto che hai ottenuto quando configurare il progetto di sviluppo.

Questa sezione descrive come archiviare la chiave API in modo che possa essere a cui fa riferimento la tua app. Non controllare la tua versione con la chiave API di controllo qualità. Dovrebbe essere archiviato nel file local.properties, che è nella directory radice del progetto. Per ulteriori informazioni sui local.properties file, vedi File delle proprietà di Gradle.

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

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

1. Apri il file build.gradle a livello di directory principale e aggiungi il seguente codice alla 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 alla Elemento plugins.

   Trendy

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

   Kotlin

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

3. Se usi Android Studio, sincronizzare il progetto con Gradle.

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

   MAPS_API_KEY=YOUR_API_KEY
   

5. Nel file AndroidManifest.xml, vai a com.google.android.geo.API_KEY e aggiorna l'attributo android:value come segue:

   <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 nella tua app utilizzi l'SDK consumer, devi includere testo di attribuzione e licenze open source nell'ambito delle note legali dell'app . È meglio includere le attribuzioni come voce di menu indipendente o come di una voce di menu Informazioni.

Le informazioni sulle licenze sono disponibili nel file "third_party_licenses.txt" file in del file AAR non archiviato.

Visita la pagina https://developers.google.com/android/guides/opensource su come includere avvisi open source.

Autenticazione SDK consumer

L'SDK consumer fornisce l'autenticazione mediante token web JSON. Un token JWT (JSON Web Token) è un token di accesso basato su JSON che fornisce o più rivendicazioni su un servizio. Ad esempio, un server potrebbe generare un token con la dichiarazione "è stato eseguito l'accesso come amministratore" e fornire questo a un cliente. Il client potrebbe quindi utilizzare quel token per dimostrare che ha effettuato l'accesso come amministratore.

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

Il token di autorizzazione deve includere un'attestazione tripid:TRIP_ID nel Intestazione authorization, dove TRIP_ID è l'ID corsa. Ciò offre al consumatore Accesso all'SDK ai dettagli della corsa, tra cui posizione del veicolo, percorso e orario di arrivo stimato.

Callback di token web JSON

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

Ti consigliamo vivamente di autorizzare la cache per l'implementazione del callback e aggiornali solo quando è trascorso il tempo di expiry. I token devono con scadenza di un'ora.

Il callback del token di autorizzazione specifica il token di servizio necessario per il servizio TripService. Fornisce anche i tripId richiesti per il contesto.

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

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

Inizializzare l'API

Prima di seguire queste procedure, si presume che le i servizi appropriati e l'SDK consumer.

Ottieni l'istanza ConsumerApi

Per utilizzare l'SDK consumer, la tua app deve essere inizializzata ConsumerApi in modo asincrono. L'API è un singleton. Il metodo di inizializzazione prevede un valore AuthTokenFactory. La fabbrica genera nuovi Token JWT per l'utente quando necessario.

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

La tua app deve implementare AuthTokenFactory come descritto in Autenticazione SDK consumer.

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
}

SDK Maps e renderer di Maps

L'SDK consumer v2.x.x supporta l'SDK Maps per Android 18.1.0 e versioni successive. La tabella riportato di seguito riassume il renderer predefinito in base alla versione di Maps SDK e la supportabilità di entrambi i renderer. Consigliamo, però, di utilizzare il renderer più recente, se necessario per utilizzare il renderer precedente, puoi specificarlo esplicitamente utilizzando MapsInitializer.initialize()

* Con il lancio del nuovo Maps Renderer, il renderer più recente sarà quello predefinito.

Aggiungi Maps SDK come dipendenza

dependencies {
  //...
  implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}

 <dependencies>
   ...
   <dependency>
     <groupId>com.google.android.gms</groupId>
     <artifactId>play-services-maps</artifactId>
     <version>18.1.0</version>
   </dependency>
 </dependencies>

Inizializza Maps SDK prima di inizializzare l'SDK consumer

Nel corso del corso Application o della startup Activity, chiama MapsInitializer.initialize() e attendere il risultato della richiesta del renderer prima dell'inizializzazione SDK consumer.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);
  initViews();

  MapsInitializer.initialize(getApplicationContext(), Renderer.LATEST,
      new OnMapsSdkInitializedCallback() {
        @Override
        public void onMapsSdkInitialized(Renderer renderer) {
          switch (renderer) {
            case LATEST:
              Log.i("maps_renderer", "LATEST renderer");
              break;
            case LEGACY:
              Log.i("maps_renderer", "LEGACY renderer");
              break;
          }

          initializeConsumerSdk();
        }
      });
}

fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)
  initViews()

  MapsInitializer.initialize(
    getApplicationContext(), Renderer.LATEST,
    object : OnMapsSdkInitializedCallback() {
      fun onMapsSdkInitialized(renderer: Renderer?) {
        when (renderer) {
          LATEST -> Log.i("maps_renderer", "LATEST renderer")
          LEGACY -> Log.i("maps_renderer", "LEGACY renderer")
        }
        initializeConsumerSdk()
      }
    })
  }

Crea l'interfaccia utente

Puoi utilizzare ConsumerMapFragment o ConsumerMapView per creare l'interfaccia utente un'applicazione. ConsumerMapFragment ti consente di definire la tua mappa utilizzando un Fragment, mentre ConsumerMapView ti consente di utilizzare un oggetto View. Ride sharing la funzionalità è la stessa sia in ConsumerMapView che ConsumerMapFragment, così potrai sceglierne uno in base a se View o Fragment è più adatto alla tua applicazione.

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

Se la progettazione della tua app richiede il supporto per i dispositivi API 19 (KitKat) e i drawable vettoriali, aggiungi il seguente codice alla tua Attività. Questo codice si estende AppCompatActivity per utilizzare Drawable vettoriali in Consumer SDK.

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

// ...

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

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

// ...

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

Aggiungere la vista o il frammento della mappa

Tu crei la mappa per visualizzare la condivisione del viaggio in un frammento Android o una vista, che definisci nel file XML di layout dell'applicazione (che si trova /res/layout). Il frammento (o vista) fornisce quindi l'accesso al percorso la condivisione della mappa, a cui l'app può accedere e che può modificare. La mappa fornisce anche a ConsumerController, che consente alla tua app di controllare e personalizzare l'esperienza di condivisione del percorso.

Mappa del percorso di condivisione e controller

Puoi definire la mappa di condivisione del viaggio come un frammento (utilizzando ConsumerMapFragment) o come vista (utilizzando ConsumerMapView), come mostrato in seguendo questo esempio di codice. Il tuo metodo onCreate() dovrebbe quindi chiamare getConsumerGoogleMapAsync(callback), che restituisce ConsumerGoogleMap in modo asincrono nel callback. Potrai quindi usare ConsumerGoogleMap per visualizzare la condivisione del percorso e può essere aggiornata se necessario dalla tua app.

ConsumerMapFragment

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

<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 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 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(). Nella oltre al parametro callback, richiede l'attività contenitore o frammento e GoogleMapOptions (che può essere nullo), contenente il frammento attributi per MapView. La classe base dell'attività o del frammento deve essere un FragmentActivity o un Fragment di assistenza (rispettivamente), in quanto forniscono per accedere al suo 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 è uguale all'esempio precedente per MapView in un'attività, tranne per il fatto che il frammento gonfia il layout che include MapView nel metodo del frammento onCreateView().

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, ti consigliamo di centrare la fotocamera per concentrarsi sul viaggio, anziché sulla posizione del dispositivo.

Soluzione integrata SDK consumer per Android: fotocamera automatica

Per consentirti di concentrarti sul viaggio anziché sulla posizione del dispositivo, L'SDK consumer offre una funzionalità Fotocamera sono abilitate per impostazione predefinita. La fotocamera esegue lo zoom per mettere a fuoco il percorso di condivisione e alla tappa successiva della corsa.

Personalizzazione del comportamento della videocamera

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

ConsumerController.getCameraUpdate() restituisce i limiti della fotocamera consigliati in quel momento. Puoi quindi fornire questo CameraUpdate come argomento per GoogleMap.moveCamera() o GoogleMap.animateCamera().

Accedere al ridesharing e alle mappe

Per supportare il ridesharing e l'interazione con la mappa nella tua applicazione, devi disporre dell'accesso a ConsumerGoogleMap e ConsumerController. ConsumerMapFragment e ConsumerMapView restituiscono entrambi in modo asincrono ConsumerGoogleMap a ConsumerMapReadyCallback. Resi a ConsumerGoogleMap ConsumerController di getConsumerController(). Tu può 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,
  }
)

ConsumerGoogleMap

ConsumerGoogleMap è una classe wrapper per GoogleMap corso. Consente alla tua app di interagire con la mappa utilizzando un'API equivalente GoogleMap. L'uso della mappa per i consumatori consente alla tua app e al tuo percorso per interagire facilmente con la stessa mappa di base di Google Maps. Ad esempio: GoogleMap consente una sola registrazione di callback, ma ConsumerGoogleMap supporta i callback con doppia registrazione. Questi callback consentono alla tua app e alla tua ride sharing di registrare callback che vengono chiamati in sequenza.

ConsumerController

ConsumerController dà accesso a funzionalità di ride sharing come ad esempio il monitoraggio delle corse, il controllo dello stato delle corse e l'impostazione delle località.

Configura la condivisione del percorso

Dopo che il backend ha abbinato un consumatore a un veicolo, usa JourneySharingSession per iniziare l'interfaccia utente di condivisione del percorso. La condivisione del percorso mostra la posizione del veicolo e il percorso. Dopo aver implementato l'SDK nella tua app, puoi aggiungere la funzionalità per monitorare le corse, ascoltare gli aggiornamenti e gestire gli errori. Le seguenti procedure presuppongono che i servizi di backend siano in uso e che la tua per far corrispondere i consumatori ai veicoli è operativa.

1. Registra un listener su un oggetto TripModel per ottenere dettagli su il viaggio, ad esempio l'orario di arrivo stimato (orario di arrivo stimato) e la distanza. che il veicolo deve viaggiare 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 tuo 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 eliminata. L'interruzione della condivisione del percorso arresta anche le richieste di rete a Fleet Engine e impedisce le perdite di memoria.

Il codice di esempio seguente mostra 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 di blocco

Il metodo onTripRefreshError restituisce gli errori che si verificano durante il monitoraggio delle corse. La mappatura per l'SDK consumer seguono le stesse linee guida HTTP/RPC stabilite per Piattaforma Google Cloud. Gli errori comuni che emergono durante il monitoraggio della corsa includono i seguenti:

Per ulteriori informazioni, vedi Gestione degli errori dell'SDK consumer.