Premiers pas avec le SDK grand public pour Android

Vous pouvez utiliser le SDK grand public pour créer et exécuter une application grand public basique, avec les services de backend de la solution On-demand Rides and Deliveries. Vous pouvez créer une application de trajet et de progression de la commande qui peut afficher un trajet actif, répondre aux mises à jour des trajets et traiter les erreurs associées.

Comme le SDK grand public possède une architecture modulaire, vous pouvez utiliser les composants de l'API que vous souhaitez utiliser pour votre application et les intégrer à l'aide de vos propres API, des services de backend fournis par Fleet Engine, et d'autres API de Google Maps Platform.

Configuration système minimale requise

L'appareil mobile doit être équipé d'Android. 6,0 (niveau d'API 23) ou version ultérieure.

Configuration de la compilation et des dépendances

Les versions 1.99.0 et ultérieures du SDK grand public sont disponibles à l'aide de l'outil Maven de Google un dépôt de clés. La version du dépôt privé précédemment utilisé est obsolète.

repositories {
    ...
    google()
}

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

Configuration du projet

Pour utiliser le SDK grand public pour Android, votre application doit cibler minSdkVersion 23 ou version ultérieure

Pour exécuter une application créée avec le SDK grand public, l'application Android l'appareil doit avoir Services Google Play installés.

Configurer votre projet de développement

Configurer votre projet de développement et obtenir une clé API du projet dans la console Google Cloud:

1. Créez un projet dans la console Google Cloud ou sélectionnez-en un existant. avec le SDK grand public. Patientez quelques minutes jusqu'à le nouveau projet est visible dans la console Google Cloud.

2. Pour que vous puissiez exécuter l'application de démonstration, votre projet doit avoir accès au SDK Maps pour Android. Dans la console Google Cloud, sélectionnez API et Services > bibliothèque, puis recherchez et activez le SDK Maps pour Android

3. Obtenez une clé API pour le projet en sélectionnant API et Services > Identifiants > Créer des identifiants > Clé API. Pour savoir comment obtenir une clé API, consultez Obtenez une clé API.

Ajouter le SDK grand public à votre application

Le SDK Consumer SDK est disponible via un dépôt Maven privé. La qui inclut les fichiers .pom (Project Object Model) du SDK ainsi que des documents Javadocs. Pour ajouter le SDK grand public à votre application:

1. Configurez votre environnement pour accéder au dépôt Maven de l'hôte, comme décrit dans la section la section précédente.

   Si vous avez une configuration de gestion centralisée des dépendances déclarée dans settings.gradle, désactivez-la comme suit.

   • Supprimez le bloc de code suivant dans settings.gradle:

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

2. Ajoutez la dépendance suivante à votre configuration Gradle ou Maven, en remplaçant la valeur Espace réservé VERSION_NUMBER pour la version souhaitée du SDK grand public.

   Gradle

   Ajoutez les éléments suivants à votre build.gradle :

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

   Maven

   Ajoutez les éléments suivants à votre pom.xml :

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

3. Le SDK grand public dépend du SDK Maps. Cette dépendance est configurée que si la version du SDK Maps n'est pas explicitement définie le fichier de configuration de compilation comme celui-ci, lorsqu'une nouvelle version de Maps le SDK grand public continue à utiliser la version minimale version compatible du SDK Maps requise.

   Gradle

   Ajoutez les éléments suivants à votre build.gradle :

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

   Maven

   Ajoutez les éléments suivants à votre pom.xml :

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

Ajouter la clé API à votre application

Une fois que vous avez ajouté le SDK grand public à votre application, ajoutez la clé API à celle-ci. Vous devez utiliser la clé API du projet que vous avez obtenue lorsque vous configurer votre projet de développement.

Cette section explique comment stocker votre clé API afin de la sécuriser référencées par votre application. Vous ne devez pas vérifier votre clé API dans votre version système de contrôle. Il doit être stocké dans le fichier local.properties, qui est situé dans le répertoire racine de votre projet. Pour en savoir plus sur la Fichier local.properties, voir Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, vous pouvez utiliser le plug-in Secrets Gradle pour Android.

Pour installer le plug-in et stocker votre clé API :

1. Ouvrez le fichier build.gradle au niveau racine et ajoutez le code suivant à dependencies sous buildscript.

   Groovy

   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. Ouvrez le fichier build.gradle au niveau de l'application et ajoutez le code suivant à Élément plugins.

   Groovy

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

   Kotlin

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

3. Si vous utilisez Android Studio, synchroniser votre projet avec Gradle.

4. Ouvrez local.properties dans le répertoire au niveau du projet, puis ajoutez le le code suivant. Remplacez YOUR_API_KEY par votre clé API.

   MAPS_API_KEY=YOUR_API_KEY
   

5. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY Mettez à jour l'attribut android:value comme suit:

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

L'exemple suivant présente un fichier manifeste complet pour une application exemple:

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

Inclure les attributions requises dans votre application

Si vous utilisez le SDK grand public dans votre application, vous devez inclure texte d'attribution et licences Open Source dans les mentions légales de votre application. . Il est préférable d'inclure les mentions sous la forme d'un élément de menu indépendant ou qui fait partie d'un élément de menu À propos.

Les informations sur les licences se trouvent dans le fichier "third_party_licenses.txt". dans le fichier AAR désarchivé.

Consultez https://developers.google.com/android/guides/opensource. sur la façon d'inclure les notifications Open Source.

Authentification par SDK client

Le SDK grand public permet l'authentification à l'aide de jetons Web JSON. Un jeton Web JSON (JWT) est un jeton d'accès basé sur JSON qui fournit ou plusieurs revendications sur un service. Par exemple, un serveur peut générer Un jeton pour lequel la revendication est "connecté en tant qu'administrateur" et nous vous demandons à un client. Le client pourrait ensuite utiliser ce jeton pour prouver que il est connecté en tant qu’administrateur.

Le SDK grand public utilise le jeton Web JSON fourni par l'application. pour communiquer avec Fleet Engine. Pour plus d'informations, consultez la page Authentification et autorisation pour parc Engine.

Le jeton d'autorisation doit inclure une revendication tripid:TRIP_ID dans la partie l'en-tête authorization, où TRIP_ID est l'ID du trajet. Cela donne au consommateur Accès au SDK aux détails du trajet, y compris la position du véhicule, l'itinéraire et l'heure d'arrivée prévue.

Rappels de jeton Web JSON

Le SDK grand public enregistre un rappel de jeton d'autorisation avec l'application lors de l'initialisation. Le SDK appelle l'application afin d'obtenir un jeton pour toutes les requêtes réseau nécessitant une autorisation.

Nous vous recommandons vivement de mettre en cache l'autorisation et actualisez-les uniquement lorsque le délai expiry est écoulé. Les jetons doivent être émises avec un délai d'expiration d'une heure.

Le rappel du jeton d'autorisation spécifie le jeton de service nécessaire. pour le service TripService. Il fournit également les tripId pour le contexte.

L'exemple de code suivant montre comment implémenter une autorisation de jeton.

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

Initialiser l'API

Avant de suivre ces procédures, nous partons du principe que vous avez activé les services appropriés et le SDK grand public.

Obtenir l'instance ConsumerApi

Pour que vous puissiez utiliser le SDK grand public, votre application doit s'initialiser ConsumerApi de manière asynchrone. L'API est un singleton. La méthode d'initialisation utilise un AuthTokenFactory. L'usine génère Jetons JWT pour l'utilisateur, si nécessaire.

providerId correspond à l'ID de projet de votre projet Google Cloud. Consultez le Guide de l'utilisateur de Fleet Engine pour en savoir plus sur la création du projet.

Votre application doit implémenter AuthTokenFactory comme décrit dans L'authentification par SDK grand public

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 et moteurs de rendu de cartes

La version 2.x.x du SDK grand public est compatible avec le SDK Maps pour Android 18.1.0 et versions ultérieures. La table ci-dessous résume le moteur de rendu par défaut en fonction de la version du SDK Maps et de la compatibilité des deux moteurs de rendu. Nous vous recommandons toutefois d'utiliser le dernier moteur de rendu, pour utiliser l'ancien moteur de rendu, vous pouvez le spécifier explicitement en utilisant MapsInitializer.initialize()

* Avec le déploiement du nouveau moteur de rendu Maps, le dernier moteur de rendu est utilisé par défaut.

Ajouter le SDK Maps en tant que dépendance

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>

Initialiser le SDK Maps avant d'initialiser le SDK grand public

Dans votre classe Application ou Activity de démarrage, appelez MapsInitializer.initialize() et attendre le résultat de la requête avant de s'initialiser Consumer SDK.

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

Créer l'interface utilisateur

Vous pouvez utiliser ConsumerMapFragment ou ConsumerMapView pour créer l'interface utilisateur application. ConsumerMapFragment vous permet de définir votre carte à l'aide d'un Fragment tandis que ConsumerMapView vous permet d'utiliser un View. Partage de course les fonctionnalités sont les mêmes dans ConsumerMapView et ConsumerMapFragment. Vous pouvez donc en choisir une en fonction que ce soit View ou Fragment est plus adapté à votre application.

Ajouter la prise en charge de l'API 19 (KitKat) et des drawables vectoriels

Si la conception de votre application nécessite la compatibilité avec les appareils utilisant l'API 19 (KitKat) et les drawables vectoriels, ajoutez le code suivant à votre activité. Ce code étend AppCompatActivity pour utiliser Drawables vectoriels dans le SDK grand public.

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

// ...

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

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

// ...

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

Ajouter la vue ou le fragment de carte

Vous créez la carte pour afficher le partage de parcours dans un fragment Android. ou une vue, que vous définissez dans le fichier XML de mise en page de votre application (situé dans /res/layout). Le fragment (ou la vue) permet ensuite d'accéder au parcours. la carte partagée, à laquelle votre application peut accéder et la modifier. La carte fournit également vers ConsumerController, ce qui permet à votre application de contrôler personnaliser l'expérience de partage du parcours.

Carte et contrôleur de partage de parcours

Vous définissez la carte de partage du parcours comme un fragment (en utilisant ConsumerMapFragment) ou en tant que vue (avec ConsumerMapView), comme indiqué dans les l'exemple de code suivant. Votre méthode onCreate() doit ensuite appeler getConsumerGoogleMapAsync(callback), qui renvoie ConsumerGoogleMap de manière asynchrone dans le rappel. Vous utilisez ensuite ConsumerGoogleMap pour afficher partage de parcours, et il peut être mis à jour si nécessaire par votre application.

ConsumerMapFragment

Vous définissez le fragment dans le fichier XML de mise en page de votre application, comme illustré dans l'exemple de code suivant.

<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" />

L'appel à getConsumerGoogleMapAsync() doit provenir de 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 vue peut être utilisée dans un fragment ou dans une activité, comme défini dans votre 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" />

L'appel à getConsumerGoogleMapAsync() doit provenir de onCreate(). Dans en plus du paramètre de rappel, il nécessite l'activité ou fragment et GoogleMapOptions (qui peut être nul), contenant la configuration pour MapView. La classe de base de l'activité ou du fragment doit être : un FragmentActivity ou un Fragment compatible (respectivement), car ils fournissent à son cycle de vie.

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

Une MapView dans un fragment est la même que dans l'exemple ci-dessus pour MapView dans une activité, sauf que le fragment gonfle la mise en page qui inclut le MapView dans la méthode onCreateView() du fragment.

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

Réglage du zoom de l'appareil photo pour faire la mise au point sur un trajet

Le bouton "Ma position" par défaut intégré au SDK Maps centre l'appareil photo sur la position de l'appareil.

Si une session de partage de parcours est en cours, vous pouvez centrer la caméra de se concentrer sur le parcours plutôt que sur la localisation de l'appareil.

Solution intégrée au SDK grand public pour Android: AutoCamera

Pour vous permettre de vous concentrer sur le trajet plutôt que sur la position de l'appareil, Le SDK grand public fournit une fonctionnalité AutoCamera est activée par défaut. La caméra zoome pour se concentrer sur l'itinéraire et le point de cheminement suivant.

Personnaliser le comportement de l'appareil photo

Si vous avez besoin de mieux contrôler le comportement de la caméra, vous pouvez activer ou désactiver autocamera à l'aide de ConsumerController.setAutoCameraEnabled().

ConsumerController.getCameraUpdate() renvoie les limites recommandées pour l'appareil photo à ce moment précis. Vous pouvez ensuite fournir cet CameraUpdate en tant qu'argument à GoogleMap.moveCamera() ou GoogleMap.animateCamera().

Accédez au partage de course et aux cartes

Pour prendre en charge le partage de course et les interactions sur la carte dans votre application, vous devez disposer d'un accès vers ConsumerGoogleMap et ConsumerController ConsumerMapFragment et ConsumerMapView renvoient tous deux de manière asynchrone ConsumerGoogleMap dans ConsumerMapReadyCallback. Retours pour ConsumerGoogleMap ConsumerController de getConsumerController(). Toi peut accéder à ConsumerGoogleMap et ConsumerController comme suit.

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 est une classe wrapper pour GoogleMap. Elle permet à votre application interagir avec la carte à l'aide d'une API qui équivaut GoogleMap La carte grand public vous permet d'utiliser votre application pour interagir de façon fluide avec la même carte GoogleMap sous-jacente. Par exemple, GoogleMap n'autorise qu'un seul enregistrement de rappel, mais ConsumerGoogleMap est compatible avec les rappels à double enregistrement. Ces rappels permettent à votre application et à votre service de covoiturage d'enregistrer des rappels appelé de manière séquentielle.

ConsumerController

ConsumerController permet d'accéder à des fonctionnalités de partage de course telles que comme la surveillance des trajets, le contrôle de l'état des trajets et la définition de lieux.

Configurer le partage du parcours

Une fois que le backend a mis en correspondance un consommateur et un véhicule, utilisez JourneySharingSession. pour commencer l'interface utilisateur de partage du parcours. Le partage de parcours montre les la position et l'itinéraire du véhicule. Après avoir implémenté le SDK dans votre application, vous pouvez ajouter la fonctionnalité de surveillance des trajets, d'écoute des mises à jour et de gestion des erreurs. Les procédures suivantes supposent que les services de backend sont en place et que votre de mise en correspondance des consommateurs avec des véhicules est opérationnelle.

1. Enregistrez un écouteur sur un objet TripModel pour obtenir des détails sur le trajet, comme l'heure d'arrivée estimée que le véhicule doit parcourir avant l'arrivée.

   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. Configurez votre trajet avec 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)
   

Arrêter le partage du trajet

Veillez à arrêter le partage de parcours lorsqu'il n'est plus nécessaire, par exemple lorsque l'activité hôte est détruite. L'arrêt du partage du parcours entraîne également l'arrêt des requêtes réseau adressées à Fleet Engine et la prévention des fuites de mémoire.

L'exemple de code suivant montre comment arrêter le partage du parcours.

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

Gérer les erreurs de trajet

La méthode onTripRefreshError signale les erreurs qui se produisent lors de la surveillance de trajet. Mappage pour le SDK grand public les erreurs suivent les mêmes directives HTTP/RPC établies pour Google Cloud Platform : Voici quelques erreurs courantes lors de la surveillance des trajets:

Pour en savoir plus, consultez Gestion des erreurs du SDK grand public