Vous pouvez utiliser le SDK grand public pour créer et exécuter une application grand public de base intégrée aux services de backend de la solution On-demand Rides and Deliveries. Vous pouvez créer une application de progression des trajets et des commandes capable d'afficher un trajet actif, de répondre aux mises à jour des trajets et de gérer les erreurs.
Comme le SDK Consumer possède une architecture modulaire, vous pouvez utiliser les parties de l'API que vous souhaitez utiliser pour votre application et les intégrer à vos propres API, services de backend fournis par Fleet Engine et API supplémentaires de Google Maps Platform.
Configuration système minimale requise
L'appareil mobile doit exécuter Android 6.0 (niveau d'API 23) ou une 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 du dépôt Maven de Google. La version du dépôt privé précédemment utilisé est obsolète.
Gradle
Ajoutez le code ci-dessous à votre fichier build.gradle
:
repositories {
...
google()
}
Maven
Ajoutez le code ci-dessous à votre fichier pom.xml
:
<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, les services Google Play doivent être installés sur l'appareil Android.
Configurer votre projet de développement
Pour configurer votre projet de développement et obtenir une clé API pour le projet dans la console Google Cloud:
Créez un projet dans la console Google Cloud ou sélectionnez un projet existant à utiliser avec le SDK Consumer. Attendez quelques minutes que le nouveau projet soit visible dans la console Google Cloud.
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.
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 Obtenir une clé API.
Ajouter le SDK grand public à votre application
Le SDK Consumer SDK est disponible via un dépôt Maven privé. Le dépôt inclut les fichiers .pom (Project Object Model) du SDK, ainsi que des documents Javadocs. Pour ajouter le SDK grand public à votre application:
Configurez votre environnement pour accéder au dépôt Maven de l'hôte, comme décrit dans la section précédente.
Si vous avez déclaré une configuration de gestion centralisée des dépendances 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() } }
Ajoutez la dépendance suivante à votre configuration Gradle ou Maven, en remplaçant l'espace réservé
VERSION_NUMBER
par 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>
Le SDK grand public dépend du SDK Maps. Cette dépendance est configurée de sorte que si la version du SDK Maps n'est pas explicitement définie dans le fichier de configuration de compilation comme celui-ci, lorsqu'une nouvelle version du SDK Maps est publiée, le SDK grand public continue à utiliser la version minimale compatible 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 avez configuré votre projet de développement.
Cette section explique comment stocker votre clé API afin qu'elle puisse être référencée de manière plus sécurisée par votre application. Vous ne devez pas l'enregistrer dans votre système de contrôle des versions. Il doit être stocké dans le fichier local.properties
, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier local.properties
, consultez 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 :
Ouvrez le fichier
build.gradle
au niveau racine et ajoutez le code suivant à l'élémentdependencies
sousbuildscript
.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") } }
Ouvrez le fichier
build.gradle
au niveau de l'application et ajoutez le code suivant à l'élémentplugins
.Groovy
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
Si vous utilisez Android Studio, synchronisez votre projet avec Gradle.
Ouvrez
local.properties
dans votre répertoire au niveau du projet, puis ajoutez le code suivant. RemplacezYOUR_API_KEY
par votre clé API.MAPS_API_KEY=YOUR_API_KEY
Dans votre fichier
AndroidManifest.xml
, accédez àcom.google.android.geo.API_KEY
et mettez à jour l'attributandroid: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 le texte d'attribution et les licences Open Source dans la section des mentions légales de votre application. Il est préférable d'inclure les attributions dans un élément de menu indépendant ou dans un élément de menu About (À propos).
Les informations sur les licences se trouvent dans le fichier "third_party_licenses.txt" du fichier AAR désarchivé.
Pour savoir comment inclure des notifications Open Source, consultez la page https://developers.google.com/android/guides/opensource.
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 une ou plusieurs revendications sur un service. Par exemple, un serveur peut générer un jeton avec la revendication "connecté en tant qu'administrateur" et le transmettre à un client. Le client peut ensuite utiliser ce jeton pour prouver qu'il est connecté en tant qu'administrateur.
Le SDK Consumer 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 l'en-tête authorization
du jeton, où TRIP_ID
correspond à l'ID du trajet. Le SDK grand public peut ainsi accéder 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 les jetons d'autorisation et de ne les actualiser que lorsque le délai expiry
est écoulé. Les jetons doivent être émis avec un délai d'expiration d'une heure.
Le rappel du jeton d'autorisation spécifie le jeton de service nécessaire au service TripService
. Elle fournit également l'élément tripId
requis pour le contexte.
L'exemple de code suivant montre comment implémenter un rappel de jeton d'autorisation.
Java
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;
}
}
Kotlin
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 client.
Obtenir l'instance ConsumerApi
Pour utiliser le SDK grand public, votre application doit initialiser ConsumerApi
de manière asynchrone. L'API est un singleton.
La méthode d'initialisation utilise un AuthTokenFactory
. La fabrique génère de nouveaux 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 Consumer SDK Authentication (Authentification par SDK grand public).
Java
Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
this, "myProviderId", authTokenFactory);
consumerApiTask.addOnSuccessListener(
consumerApi -> this.consumerApi = consumerApi);
Kotlin
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. Le tableau ci-dessous récapitule le moteur de rendu par défaut en fonction de la version du SDK Maps et de la compatibilité des deux. Nous vous recommandons d'utiliser le dernier moteur de rendu. Toutefois, si vous devez utiliser l'ancien moteur de rendu, vous pouvez le spécifier explicitement à l'aide de MapsInitializer.initialize()
.
Version du SDK Maps | Compatibilité avec le dernier moteur de rendu | Compatible avec l'ancien moteur de rendu | Moteur de rendu par défaut |
---|---|---|---|
V18.1.0 et versions antérieures | Oui | Oui | Ancien* |
V18.2.0 | Oui | Oui | La plus récente |
* Lors du déploiement du nouveau moteur de rendu Maps, le dernier moteur de rendu sera utilisé par défaut.
Ajouter le SDK Maps en tant que dépendance
Gradle
Ajoutez les éléments suivants à votre build.gradle
:
dependencies {
//...
implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}
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>
Initialiser le SDK Maps avant d'initialiser le SDK grand public
Dans votre classe Application
ou Activity
de démarrage, appelez MapsInitializer.initialize() et attendez le résultat de la requête du moteur de rendu avant d'initialiser le SDK grand public.
java
@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();
}
});
}
Kotlin
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 de votre application. ConsumerMapFragment
vous permet de définir votre carte à l'aide d'un Fragment
, tandis que ConsumerMapView
vous permet d'utiliser un View
. La fonctionnalité de partage de course est la même dans ConsumerMapView
et ConsumerMapFragment
. Vous pouvez donc en choisir une selon que View
ou Fragment
conviennent mieux à 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
afin d'utiliser les drawables vectoriels dans le SDK grand public.
Java
// ...
import android.support.v7.app.AppCompatActivity;
// ...
public class ConsumerTestActivity extends AppCompatActivity {
// ...
}
Kotlin
// ...
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 à la carte de partage de parcours, que votre application peut consulter et modifier. La carte fournit également un handle vers le ConsumerController
, ce qui permet à votre application de contrôler et de 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 soit en tant que fragment (à l'aide de ConsumerMapFragment
), soit en tant que vue (avec ConsumerMapView
), comme illustré dans 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 le partage du parcours. 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 la méthode onCreate()
.
Java
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();
}
});
}
}
}
Kotlin
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 fichier 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()
. En plus du paramètre de rappel, il nécessite l'activité ou le fragment qui le contiennent, ainsi que GoogleMapOptions
(qui peut être nul) contenant les attributs de configuration pour MapView
. La classe de base de l'activité ou du fragment doit être respectivement une FragmentActivity
ou une Fragment
prise en charge, car elle donne accès à son cycle de vie.
Java
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);
}
}
}
Kotlin
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,
)
}
}
L'élément MapView
d'un fragment est le même que dans l'exemple ci-dessus pour MapView
dans une activité, sauf que le fragment gonfle la mise en page qui inclut MapView
dans la méthode onCreateView()
du fragment.
Java
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);
}
}
Kotlin
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 pour qu'elle se concentre sur le trajet plutôt que sur la position de l'appareil.
Solution intégrée au SDK grand public pour Android: AutoCamera
Pour vous permettre de vous concentrer sur le parcours plutôt que sur la position de l'appareil, le SDK grand public fournit une fonctionnalité AutoCamera activée par défaut. La caméra zoome pour se concentrer sur l'itinéraire de partage du trajet et le point de cheminement du trajet suivant.
Personnaliser le comportement de l'appareil photo
Si vous avez besoin de mieux contrôler le comportement de la caméra, vous pouvez désactiver ou activer la caméra automatique à 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 avec la carte dans votre application, vous devez accéder à ConsumerGoogleMap
et ConsumerController
.
ConsumerMapFragment
et ConsumerMapView
renvoient tous deux de manière asynchrone ConsumerGoogleMap
dans ConsumerMapReadyCallback
.
ConsumerGoogleMap
renvoie ConsumerController
à partir de getConsumerController()
. Vous pouvez accéder à ConsumerGoogleMap
et ConsumerController
comme suit.
Java
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);
Kotlin
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 la classe GoogleMap
. Elle permet à votre application d'interagir avec la carte à l'aide d'une API équivalente à GoogleMap
. L'utilisation de la carte grand public permet à votre application et à votre service de covoiturage d'interagir facilement avec la même carte GoogleMap sous-jacente. Par exemple, GoogleMap
n'autorise qu'un seul enregistrement de rappel, mais ConsumerGoogleMap
accepte les rappels à double enregistrement.
Ces rappels permettent à votre application et à votre service de covoiturage d'enregistrer des rappels appelés de manière séquentielle.
ConsumerController
ConsumerController
permet d'accéder à des fonctionnalités de partage de course, par exemple pour surveiller les trajets, contrôler leur état et définir des lieux.
Configurer le partage du parcours
Une fois que le backend a mis en correspondance un consommateur et un véhicule, utilisez JourneySharingSession
pour démarrer l'interface utilisateur de partage du parcours. Le partage du trajet affiche l'emplacement et l'itinéraire du véhicule correspondant. Après avoir implémenté le SDK dans votre application, vous pouvez ajouter une fonctionnalité permettant de surveiller les trajets, d'écouter les mises à jour et de gérer les erreurs.
Les procédures suivantes supposent que les services de backend sont en place et que vos services de mise en correspondance des consommateurs avec les véhicules sont opérationnels.
Enregistrez un écouteur sur un objet
TripModel
pour obtenir des détails sur le trajet, tels que l'heure d'arrivée estimée (ETA) et la distance 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?, ) { // ... } // ... })
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.
Java
public class MainActivity extends AppCompatActivity
implements ConsumerViewModel.JourneySharingListener {
// Class implementation
@Override
protected void onDestroy() {
super.onDestroy();
if (journeySharingSession != null) {
journeySharingSession.stop();
}
}
}
Kotlin
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.
Le mappage des erreurs du SDK client suit les mêmes consignes HTTP/RPC que celles établies pour Google Cloud Platform.
Voici quelques erreurs courantes lors de la surveillance des trajets:
HTTP | RPC | Description |
---|---|---|
400 | INVALID_ARGUMENT | Le client a spécifié un nom de trajet non valide. Le nom du trajet doit respecter le format providers/{provider_id}/trips/{trip_id} .
provider_id doit être l'ID du projet Cloud appartenant au fournisseur de services. |
401 | UNAUTHENTICATED | Requête non authentifiée en raison d'un jeton JWT non valide. Cette erreur se produit si le jeton JWT est signé sans ID de trajet ou si le jeton JWT a expiré. |
403 | PERMISSION_DENIED | Le client ne dispose pas des autorisations nécessaires. Cette erreur se produit si le jeton JWT n'est pas valide, si le client ne dispose pas des autorisations nécessaires ou si l'API n'est pas activée pour le projet client. Le jeton JWT est peut-être manquant ou il est signé avec un ID de trajet qui ne correspond pas à l'ID de trajet demandé. |
429 | RESOURCE_EXHAUSTED | Le quota de ressources est égal à zéro ou le débit du trafic dépasse la limite. |
503 | UNAVAILABLE | Service indisponible. Généralement, le serveur est en panne. |
504 | DEADLINE_EXCEEDED | Délai de requête dépassé. Cela ne se produit que si l'appelant définit un délai inférieur au délai par défaut de la méthode (c'est-à-dire que le délai demandé ne suffit pas pour que le serveur traite la requête) et que la requête ne s'est pas terminée dans le délai. |
Pour en savoir plus, consultez la page Gestion des erreurs du SDK grand public.