Vous pouvez utiliser le SDK Driver pour améliorer la navigation et le suivi dans votre application Trip and Order Progress. Le SDK Driver fournit des informations sur l'emplacement des véhicules et les tâches au parc de solutions On-demand Rides and Deliveries.
Le SDK Driver permet aux services Fleet Engine et à vos services personnalisés de connaître l'emplacement et l'état du véhicule. Par exemple, le véhicule peut être ONLINE
ou OFFLINE
, et sa position change au fur et à mesure du trajet.
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 4.99 et ultérieures du SDK Driver sont disponibles dans le dépôt Maven de Google.
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 Driver, votre application doit cibler minSdkVersion
23 ou une version ultérieure.
Pour que vous puissiez exécuter une application créée avec le SDK Driver, 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 Driver. Attendez quelques minutes que le nouveau projet soit visible dans la console Google Cloud.
Pour 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 Driver à votre application
Le SDK Driver est disponible dans le dépôt Maven de Google. Ce dépôt comprend les fichiers .pom (Project Object Model) du SDK, ainsi que des fichiers Javadocs. Pour ajouter le SDK Driver à votre application:
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 Driver.Gradle
Ajoutez les éléments suivants à votre
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER' }
Maven
Ajoutez les éléments suivants à votre
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-driver</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Le SDK Driver dépend du SDK Navigation. Cette dépendance est configurée de sorte que, si une version spécifique de ce SDK est nécessaire, elle doit être définie explicitement dans le fichier de configuration de compilation, comme indiqué ci-dessous. Si vous omettez le bloc de code mentionné, le projet pourra toujours télécharger la dernière version du SDK Navigation dans la version majeure. Notez que les comportements combinés des dernières versions du SDK Driver et du SDK Navigation ont été soumis à des tests rigoureux avant leur sortie.
Organisez la configuration des dépendances de vos environnements de développement et de publication en conséquence.
Gradle
Ajoutez les éléments suivants à votre
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
Ajoutez les éléments suivants à votre
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>5.0.0</version> </dependency> </dependencies>
Ajouter la clé API à votre application
Une fois que vous avez ajouté le SDK Driver à votre application, ajoutez la clé API à votre application. Vous devez utiliser la clé API du projet que vous avez obtenue lors de la configuration de 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 vérifier votre clé API 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 votre 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.driverapidemo">
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_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 Driver dans votre application, vous devez inclure un texte d'attribution et des 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).
Vous trouverez les informations sur les licences dans le fichier "third_party_licenses.txt" dans le fichier AAR désarchivé.
Consultez https://developers.google.com/android/guides/opensource pour découvrir comment inclure les notifications Open Source.
Dépendances
Si vous utilisez ProGuard pour optimiser vos builds, vous devrez peut-être ajouter les lignes suivantes à votre fichier de configuration ProGuard:
-dontwarn com.google.**
-dontwarn okio.**
Le niveau d'API minimal accepté est 23.
Initialiser le SDK
Un ID de fournisseur (généralement l'ID de projet Google Cloud) est nécessaire pour initialiser l'objet DriverContext
. Pour en savoir plus sur la configuration du projet Google Cloud, consultez la page Authentification et autorisation.
Avant d'utiliser le SDK Driver, vous devez d'abord initialiser le SDK Navigation. Pour initialiser le SDK, procédez comme suit :
Obtenez un objet
Navigator
à partir deNavigationApi
.Java
NavigationApi.getNavigator( this, // Activity new NavigationApi.NavigatorListener() { @Override public void onNavigatorReady(Navigator navigator) { // Keep a reference to the Navigator (used to configure and start nav) this.navigator = navigator; } } );
Kotlin
NavigationApi.getNavigator( this, // Activity object : NavigatorListener() { override fun onNavigatorReady(navigator: Navigator) { // Keep a reference to the Navigator (used to configure and start nav) this@myActivity.navigator = navigator } }, )
Créez un objet
DriverContext
en remplissant les champs obligatoires.Java
DriverContext driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider( NavigationApi.getRoadSnappedLocationProvider(application)) .build();
Kotlin
val driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application)) .build()
Utilisez l'objet
DriverContext
pour initialiser*DriverApi
.Java
RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
Kotlin
val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
Récupérez
RidesharingVehicleReporter
à partir de l'objet d'API. (*VehicleReporter
étendNavigationVehicleReporter
.)Java
RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
Kotlin
val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
Authentification avec AuthTokenFactory
Lorsque le SDK Driver génère des mises à jour de position, il doit les envoyer au serveur Fleet Engine. Afin d'authentifier ces requêtes, le SDK pilote appelle une instance de AuthTokenFactory
fournie par l'appelant.
La fabrique est chargée de générer des jetons d'authentification au moment de la mise à jour des emplacements.
Le mode exact de génération des jetons dépend de la situation de chaque développeur. Toutefois, l'implémentation devra probablement:
- Récupérer un jeton d'authentification, éventuellement au format JSON, à partir d'un serveur HTTPS
- analyser et mettre en cache le jeton
- actualiser le jeton à son expiration ;
Pour en savoir plus sur les jetons attendus par le serveur Fleet Engine, consultez la page Créer un jeton Web JSON (JWT) pour l'autorisation.
Voici une implémentation squelette d'un AuthTokenFactory
:
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private String token; // initially null
private long expiryTimeMs = 0;
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
@Override
public String getToken(AuthTokenContext authTokenContext) {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId());
}
return token;
}
private void fetchNewToken(String vehicleId) {
String url =
new Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token = obj.get("Token").getAsString();
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 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000;
} catch (IOException e) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw new RuntimeException("Could not get auth token", e);
}
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: String = ""
private var expiryTimeMs: Long = 0
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
override fun getToken(context: AuthTokenContext): String {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId())
}
return token
}
fun fetchNewToken(vehicleId: String) {
val url =
Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token = obj.get("ServiceToken").getAsString()
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 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000
}
} catch (e: IOException) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw RuntimeException("Could not get auth token", e)
}
}
}
Cette implémentation particulière utilise le client HTTP Java intégré pour extraire un jeton au format JSON à partir du serveur d'authentification du développeur. Le jeton est enregistré pour être réutilisé. Le jeton est de nouveau récupéré si l'ancien jeton a lieu moins de 10 minutes avant son délai d'expiration.
Votre implémentation peut faire les choses différemment, par exemple utiliser un thread d'arrière-plan pour actualiser les jetons.
Les exceptions dans AuthTokenFactory
seront traitées comme temporaires, sauf si elles se produisent de manière répétée. Après un certain nombre de tentatives, le SDK Driver suppose que l'erreur est permanente et cessera d'envoyer des mises à jour.
Rapports d'état et d'erreurs avec StatusListener
Étant donné que le SDK Driver effectue des actions en arrière-plan, utilisez StatusListener
pour déclencher des notifications lorsque certains événements se produisent, tels que des erreurs, des avertissements ou des messages de débogage. Les erreurs peuvent être de nature temporaire (par exemple, BACKEND_CONNECTIVITY_ERROR
) ou entraîner l'arrêt permanent des mises à jour de position (par exemple, VEHICLE_NOT_FOUND
, qui indique une erreur de configuration).
Vous fournissez une implémentation facultative de StatusListener
, comme suit:
Java
class MyStatusListener implements StatusListener {
/** Called when background status is updated, during actions such as location reporting. */
@Override
public void updateStatus(
StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Kotlin
class MyStatusListener : StatusListener() {
/** Called when background status is updated, during actions such as location reporting. */
override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Remarques sur SSL/TLS
En interne, l'implémentation du SDK Driver utilise SSL/TLS pour communiquer de manière sécurisée avec le serveur Fleet Engine. Les anciennes versions d'Android (versions d'API 19 ou antérieures) peuvent nécessiter un correctif SecurityProvider
pour pouvoir communiquer avec le serveur. Consultez cet article pour en savoir plus sur l'utilisation de SSL dans Android. Il contient également des exemples de code permettant d'appliquer des correctifs au fournisseur de solutions de sécurité.
Activer les mises à jour de la position géographique
Une fois que vous disposez d'une instance *VehicleReporter
, l'activation des mises à jour de la position est simple:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
Les mises à jour de la position sont envoyées à intervalles réguliers lorsque l'état du véhicule est ONLINE
. Notez que l'appel de reporter.enableLocationTracking()
ne définit pas automatiquement l'état du véhicule sur ONLINE
. Vous devez définir l'état du véhicule de manière explicite.
Par défaut, l'intervalle de reporting est de 10 secondes. L'intervalle de reporting peut être modifié avec reporter.setLocationReportingInterval(long, TimeUnit)
. L'intervalle minimal de mise à jour accepté est de 5 secondes. Des mises à jour plus fréquentes peuvent entraîner un ralentissement des requêtes et des erreurs.
Désactivation des mises à jour de la position géographique
Une fois le travail du conducteur terminé, vous pouvez arrêter les mises à jour de la position et marquer le véhicule comme étant hors connexion en appelant DeliveryVehicleReporter.disableLocationTracking
ou RidesharingVehicleReporter.disableLocationTracking
.
Cet appel programmera une dernière mise à jour pour une livraison immédiate, qui indique que le véhicule est hors connexion. Cette mise à jour ne contiendra pas la position de l'utilisateur.
Définir l'état du véhicule
Lorsque les mises à jour de la position sont activées, si vous définissez l'état du véhicule sur ONLINE
, le véhicule est disponible pour les requêtes SearchVehicles
. De même, si un véhicule est défini sur OFFLINE
, il est marqué comme indisponible.
Vous avez la possibilité de définir l'état du véhicule côté serveur (voir Mettre à jour un véhicule) ou directement dans le SDK Driver:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
Lorsque les mises à jour de la position sont activées, un appel à setVehicleState
est propagé lors de la mise à jour suivante.
Si un véhicule est défini sur ONLINE
lorsque le suivi de la position n'est pas activé, une IllegalStateException
est générée. Un véhicule peut être marqué comme OFFLINE
lorsque le suivi de la position n'est pas encore activé ou qu'il est explicitement désactivé. La mise à jour est immédiate. Un appel à RidesharingVehicleReporter.disableLocationTracking()
définit l'état du véhicule sur OFFLINE
.
Notez que setVehicleState
est immédiatement renvoyé et que les mises à jour sont effectuées sur le thread de mise à jour de la position. Comme pour la gestion des erreurs de mise à jour des positions, les erreurs de mise à jour de l'état du véhicule sont propagées à l'aide du StatusListener
éventuellement fourni dans DriverContext
.