Vous pouvez utiliser le SDK Driver pour améliorer la navigation et le suivi à votre application de suivi du trajet et de progression de la commande. Le SDK Driver fournit Informations concernant l'emplacement et les tâches des véhicules dans la solution On-demand Rides and Deliveries Solution Fleet Engine
Le SDK Driver permet de tenir les services Fleet Engine et vos services personnalisés informés
de l'emplacement et de l'état du véhicule. Par exemple, le véhicule peut être ONLINE
ou OFFLINE
, et la position du véhicule 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 que vous puissiez utiliser le SDK Driver, votre application doit cibler
minSdkVersion
23 ou version ultérieure
Pour exécuter une application créée avec le SDK Driver, 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:
Créez un projet dans la console Google Cloud ou sélectionnez-en un existant. avec le SDK Driver. Patientez quelques minutes jusqu'à le nouveau projet est 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 Obtenez une clé API.
Ajouter le SDK Driver à votre application
Le SDK Driver est disponible dans le dépôt Maven de Google. La qui inclut les fichiers .pom (Project Object Model) du SDK ainsi que des documents Javadocs. Pour ajouter le SDK Driver à votre application:
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 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 que si une version spécifique du SDK Navigation est nécessaire, explicitement défini dans le fichier de configuration de compilation, comme suit : 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 de Driver SDK et Le SDK Navigation a fait l'objet de tests rigoureux avant sa publication.
Organiser la configuration des dépendances de votre développement et de votre version 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 à celle-ci. Toi doit utiliser la clé API du projet que vous avez obtenue lorsque vous avez 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 :
Ouvrez le fichier
build.gradle
au niveau racine et ajoutez le code suivant àdependencies
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é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, synchroniser votre projet avec Gradle.
Ouvrez
local.properties
dans le répertoire au niveau du projet, puis ajoutez le 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
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 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.
Dépendances
Si vous utilisez ProGuard pour optimiser vos builds, vous devrez peut-être ajouter les lignes suivantes à votre ProGuard configuration Terraform:
-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 du projet Google Cloud) est requis pour
initialisez l'objet DriverContext
. Pour en savoir plus sur la configuration
pour un projet Google Cloud, consultez
Authentification et autorisation
Avant d'utiliser le SDK Driver, vous devez 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 renseignant 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)
Obtenez
RidesharingVehicleReporter
à partir de l'objet 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 la position,
il doit envoyer ces
mises à jour à
le serveur Fleet Engine. Pour authentifier ces requêtes,
Le SDK pilote appellera un utilisateur fourni par l'appelant
Instance de AuthTokenFactory
.
La fabrique est chargée de générer des jetons d'authentification sur le site
l'heure de mise à jour.
Le mode de génération exact des jetons dépend de la situation de chaque développeur. Cependant, l'implémentation devra probablement:
- Extraire un jeton d'authentification, éventuellement au format JSON, à partir d'un serveur HTTPS
- analyser et mettre en cache le jeton ;
- actualiser le jeton lorsqu'il expire
Pour en savoir plus sur les jetons attendus par le serveur Fleet Engine, consultez Créer un jeton Web JSON (JWT) pour l'autorisation
Voici un squelette d'implémentation 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 récupérer au format JSON provenant du serveur d'authentification du développeur. Le jeton est enregistrées pour être réutilisées. Le jeton est de nouveau récupéré si l'ancien jeton est disponible dans les 10 minutes maximum de son délai d'expiration.
Votre implémentation peut se comporter différemment, par exemple en utilisant un thread d'arrière-plan pour actualiser les jetons.
Les exceptions dans AuthTokenFactory
seront traitées comme temporaires, sauf si elles se produisent
à plusieurs reprises. Après plusieurs tentatives, le SDK Driver
partirons du principe que
est définitive et cessera toute tentative d'envoi des mises à jour.
Rapports d'état et d'erreurs avec StatusListener
Étant donné que le SDK Driver effectue des actions dans
arrière-plan, utilisez le 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 (BACKEND_CONNECTIVITY_ERROR
, par exemple) ou qui peuvent
entraîner l'arrêt définitif des mises à jour de la position (VEHICLE_NOT_FOUND
,
indiquant une erreur de configuration).
Vous fournissez une implémentation StatusListener
facultative comme celle-ci:
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 en toute sécurité
avec le serveur Fleet Engine. Les anciennes versions d'Android (versions 19 ou 19 de l'API
inférieure) peuvent nécessiter un correctif SecurityProvider
pour pouvoir communiquer avec
Google Cloud. Vous devriez voir ce lien
cet article
pour en savoir plus sur l'utilisation de SSL sous Android. L'article contient également
contient des exemples de code pour appliquer
des correctifs au fournisseur de solutions de sécurité.
Activation des mises à jour de la position...
Une fois que vous disposez d'une instance *VehicleReporter
, l'activation des mises à jour de la position
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()
n'entraîne pas
définit automatiquement l'état du véhicule sur ONLINE
. Vous devez
définir explicitement l'état du véhicule ;
Par défaut, l'intervalle du rapport est de 10 secondes. L'intervalle de reporting peut
être modifié par reporter.setLocationReportingInterval(long, TimeUnit)
. La
l'intervalle minimal de mise à jour pris en charge est de 5 secondes. Des mises à jour plus fréquentes peuvent
ce qui ralentit les requêtes et entraîne des erreurs.
Désactivation des mises à jour de la position géographique
Une fois le quart de travail du conducteur terminé, la mise à jour de la position peut être interrompue et
véhicule marqué hors connexion en appelant
DeliveryVehicleReporter.disableLocationTracking
ou
RidesharingVehicleReporter.disableLocationTracking
Cet appel entraînera la planification d’une dernière mise à jour pour une livraison immédiate, indiquant que le véhicule est hors connexion. Cette mise à jour ne contiendra pas l'adresse e-mail l'emplacement.
Définir l'état du véhicule
Lorsque les mises à jour de la position sont activées, définir l'état du véhicule sur ONLINE
rendre le véhicule disponible pour des requêtes SearchVehicles
; de même, en marquant une
véhicule en tant que OFFLINE
, il sera 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 au setVehicleState
est propagé à
la prochaine mise à jour de la position géographique.
Marquer un véhicule comme ONLINE
lorsque le suivi de la localisation n'est pas activé aura pour effet
dans une IllegalStateException
. Un véhicule peut être marqué comme OFFLINE
lorsque
le suivi de la position n'est pas encore activé ou explicitement désactivé. Cela se traduira par
immédiatement. Un appel à
RidesharingVehicleReporter.disableLocationTracking()
va
définissez l'état du véhicule sur OFFLINE
.
Notez que setVehicleState
renvoie immédiatement un résultat et que les mises à jour sont effectuées sur
fil de discussion de mise à jour de la position. Semblable à la gestion des mises à jour d'établissements,
la mise à jour de l'état du véhicule sont propagés à l'aide de la méthode
StatusListener
défini dans DriverContext
.