Un flux de données de navigation détaillée fournit uniquement des informations de navigation aux appareils qui ne sont pas conçus pour les indications de navigation basées sur une carte. Il fournit les manœuvres à venir avec les éléments que vous fournissez:
- Icônes (à gauche, à droite, demi-tour)
- CANNOT TRANSLATE
- noms des routes
- l'estimation des distances et du temps pour passer à la prochaine étape de navigation ou à la destination finale ;
Vous pouvez utiliser le flux de navigation détaillée pour créer des expériences pour lesquelles l'interface utilisateur complète du SDK Navigation n'est pas appropriée, par exemple pour Android Auto ou pour les petits écrans où une pile Android complète n'est pas disponible. Par exemple, vous pouvez l'utiliser pour les usagers de véhicules à deux roues, où vous pouvez projeter des indications de navigation uniquement pour les aider à atteindre leur destination plus rapidement et avec plus de confiance avec un minimum de distractions.
Pour utiliser le SDK, vous allez créer un service et l'enregistrer auprès du SDK Navigation pour Android afin qu'il puisse recevoir de nouvelles informations de navigation en temps réel (environ une fois par seconde pendant la navigation).
Ce document explique comment créer et enregistrer un service de navigation qui reçoit des informations de navigation du SDK et fournit l'état de la navigation à l'appareil récepteur.
Présentation
Cette section explique comment ajouter la bibliothèque TurnByTurn à vos projets et résume le flux de haut niveau pour la création d'une fonctionnalité de navigation détaillée.
Ajouter la bibliothèque TurnByTurn à votre projet à l'aide de Maven (recommandé)
Pour utiliser une version autonome de la bibliothèque TurnByTurn comme suit:
Configurez votre environnement pour accéder au dépôt Maven hôte, comme décrit dans la section Premiers pas avec le SDK Driver de la documentation sur les trajets et les commandes.
Ajoutez la dépendance suivante à votre configuration Maven ou Gradle:
Maven
<dependencies> ... <dependency> <groupId>com.google.android.maps</groupId> <artifactId>google_turnbyturn</artifactId> <version>1.0.0</version> </dependency> </dependencies>
Gradle
dependencies { ... implementation 'com.google.android.maps:google_turnbyturn:1.0.0' }
Ajouter la bibliothèque TurnByTurn à votre projet à l'aide d'un fichier JAR téléchargé (alternative)
La bibliothèque TurnByTurn est disponible en tant que fichier JAR dans ce dossier du SDK. Si ce n'est pas le cas, contactez votre représentant.
- Téléchargez et décompressez
google_turnbyturn_*.jar
. - Copiez le fichier JAR téléchargé dans le répertoire
app/libs
de votre projet. Ajoutez le code suivant à votre fichier
build.gradle
pour inclure le fichier JAR dans votre build.dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
Utiliser la bibliothèque TurnByTurn
Vous trouverez ci-dessous les grandes étapes à suivre pour activer la fonctionnalité de navigation détaillée. Les sections suivantes fournissent des détails sur chaque étape.
Créez un service pour recevoir des informations sur la navigation.
Consultez un exemple d'écran de navigation montrant les éléments essentiels.
Créez un service pour recevoir des informations de navigation {#service}
Le SDK Navigation se lie à votre service TurnByTurn et lui envoie des mises à jour de navigation via Android Messenger. Vous pouvez créer un service de navigation pour ces mises à jour ou utiliser un service existant.
L'avantage d'utiliser un service pour recevoir des mises à jour de navigation est qu'il peut se trouver dans un processus en arrière-plan distinct.
Dans l'exemple suivant, le service reçoit des informations de navigation et utilise TurnByTurnManager
pour convertir les données en un objet NavInfo
contenant les détails de navigation.
/** * Receives turn-by-turn navigation information forwarded from NavSDK. */ public class NavInfoReceivingService extends Service { /** The messenger used by the service to receive nav step updates. */ private Messenger incomingMessenger; private TurnByTurnManager turnByTurnManager; private final class IncomingNavStepHandler extends Handler { public IncomingNavStepHandler(Looper looper) { super(looper); } @Override public void handleMessage(Message msg) { // Identify the message through the msg.what field. if (TurnByTurnManager.MSG_NAV_INFO == msg.what) { // Extract the NavInfo object using the TurnByTurnManager. NavInfo navInfo = turnByTurnManager .readNavInfoFromBundle(msg.getData())); // Do something with the NavInfo } } } @Nullable @Override public IBinder onBind(Intent intent) { return incomingMessenger.getBinder(); } @Override public void onCreate() { turnByTurnManager = TurnByTurnManager.createInstance(); HandlerThread thread = new HandlerThread("NavInfoReceivingService", Process.THREAD_PRIORITY_DEFAULT); thread.start(); incomingMessenger = new Messenger( new IncomingNavStepHandler(thread.getLooper())); }
Codes des messages
Les messages NavInfo
peuvent être identifiés via le champ Message.what de la classe Message
, qui est défini sur la valeur de TurnByTurnManager.MSG_NAV_INFO
.
Enregistrer le service pour les mises à jour de navigation {#register}
Les extraits de code suivants enregistrent le service de navigation.
boolean isNavInfoReceivingServiceRegistered = navigator.registerServiceForNavUpdates( getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);
Démarrer et arrêter le service
Le service de navigation est actif tant que le SDK Navigation s'y lie. Vous pouvez appeler manuellement startService()
et stopService()
pour contrôler le cycle de vie du service de navigation. Toutefois, lorsque vous enregistrez votre service auprès du SDK Navigation, il démarre automatiquement et ne s'arrête que lorsque vous l'annulez. En fonction de la configuration de votre application, vous pouvez envisager de démarrer un service de premier plan, comme décrit dans la présentation des services de la documentation Android.
Annuler l'enregistrement du service
Pour ne plus recevoir de notifications de navigation, annulez l'enregistrement du service dans le SDK Navigation.
navigator.unregisterServiceForNavUpdates();
Comprendre les états de navigation {#states}
Utilisez NavInfo.getNavState()
pour obtenir l'état actuel de la navigation, qui est l'un des suivants:
Enroute : l'état
ENROUTE
signifie que la navigation guidée est actuellement active et que l'utilisateur suit l'itinéraire fourni. Des informations sur l'étape de manœuvre à venir en cours sont disponibles.Nouvel itinéraire :
REROUTING
signifie que la navigation est en cours, mais que le navigateur recherche un nouvel itinéraire. L'étape de manœuvre à venir n'est pas disponible, car il n'y a pas encore de nouvel itinéraire. Dans l'application exemple, le message "Nouvel itinéraire..." s'affiche sur l'écran des informations de navigation. Une fois qu'une route est trouvée, un messageNavInfo
est envoyé avec l'étatENROUTE
.Arrêtée :
STOPPED
signifie que la navigation est terminée. Par exemple, la navigation s'arrête lorsque l'utilisateur quitte l'application. Dans l'application exemple, un étatSTOPPED
efface l'affichage des informations de navigation pour éviter que des instructions d'étape ne s'affichent.
Insérer des données à l'écran du flux
Maintenant que vous avez configuré votre service de navigation détaillée, cette section décrit les éléments visuels et textuels que vous pouvez utiliser pour remplir les fiches de guidage pour le flux de navigation détaillée.
Champs d'informations de la carte de navigation
Lorsque le conducteur ouvre la navigation guidée, une fiche de navigation contenant la date de navigation renseignée à partir du SDK Navigation s'affiche en haut de l'écran. L'image associée montre un exemple de ces éléments de navigation essentiels.
Ce tableau montre les champs d'informations de navigation et leur emplacement.
Champs associés à chaque étape de navigation | Champs correspondant à l'ensemble du trajet |
---|---|
Trouvé dans StepInfo |
Trouvé dans NavInfo |
Nom complet de la route | Temps restant |
Icône de manœuvre | Distance jusqu'à la destination |
Distance jusqu'à l'étape suivante | |
Champs d'indication de voie |
Indication de voie
Le SDK Navigation représente les voies dans la fiche de navigation sous la forme d'objets de données Lane et LaneDirection. Un objet Lane
représente une voie spécifique pendant la navigation et comporte une liste d'objets LaneDirection
décrivant tous les virages pouvant être effectués à partir de cette voie.
La direction recommandée à un conducteur dans une voie est indiquée dans le champ isRecommended.
Exemple d'indication de voie
L'extrait de code suivant illustre la représentation des données des voies affichées ci-dessus.
// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
{/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]
// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]
Créer des icônes pour les manœuvres
L'énumération Maneuver
définit chaque manœuvre possible qui peut se produire pendant la navigation. Vous pouvez également obtenir la manœuvre d'une étape donnée à partir de la méthode StepInfo.getManeuver()
.
Vous devez créer des icônes de manœuvre et les associer aux manœuvres qui leur sont associées.
Pour certaines manœuvres, vous pouvez configurer un mappage "un à un" avec une icône, comme DESTINATION_LEFT
et DESTINATION_RIGHT
. Toutefois, étant donné que certaines manœuvres sont similaires, vous pouvez associer plusieurs manœuvres à une même icône. Par exemple, TURN_LEFT
et ON_RAMP_LEFT
peuvent tous deux être mappés à l'icône de virage à gauche.
Certaines manœuvres contiennent un libellé clockwise
ou counterclockwise
supplémentaire, que le SDK détermine en fonction de l'aspect automobile d'un pays. Par exemple, dans les pays où la conduite s'effectue à gauche de la route, les conducteurs font un rond-point ou un demi-tour dans le sens des aiguilles d'une montre, tandis que ceux qui se trouvent à droite empruntent le sens horaire. Le SDK Navigation détecte si une manœuvre se produit dans le trafic de gauche ou de droite et génère la manœuvre appropriée. Par conséquent, l'icône de manœuvre peut être différente selon qu'elle s'effectue dans le sens des aiguilles d'une montre ou dans le sens inverse des aiguilles d'une montre.
Développer pour voir des exemples d'icônes pour différentes manœuvres
Icône Exemple | Commandes principales |
---|---|
DEPART UNKNOWN |
|
STRAIGHT ON_RAMP_UNSPECIFIED OFF_RAMP_UNSPECIFIED NAME_CHANGE
|
|
TURN_RIGHT ON_RAMP_RIGHT
|
|
TURN_LEFT ON_RAMP_LEFT
|
|
TURN_SLIGHT_RIGHT ON_RAMP_SLIGHT_RIGHT OFF_RAMP_SLIGHT_RIGHT
|
|
TURN_SLIGHT_LEFT ON_RAMP_SLIGHT_LEFT OFF_RAMP_SLIGHT_LEFT
|
|
TURN_SHARP_RIGHT ON_RAMP_SHARP_RIGHT OFF_RAMP_SHARP_RIGHT
|
|
TURN_SHARP_LEFT ON_RAMP_SHARP_LEFT OFF_RAMP_SHARP_LEFT
|
|
TURN_U_TURN_COUNTERCLOCKWISE ON_RAMP_U_TURN_COUNTERCLOCKWISE OFF_RAMP_U_TURN_COUNTERCLOCKWISE
|
|
TURN_U_TURN_CLOCKWISE ON_RAMP_U_TURN_CLOCKWISE OFF_RAMP_U_TURN_CLOCKWISE
|
|
ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
|
|
ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_STRAIGHT_CLOCKWISE
|
|
ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
|
|
ROUNDABOUT_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_LEFT_CLOCKWISE
|
|
ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_SHARP_LEFT_CLOCKWISE
|
|
ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
|
|
ROUNDABOUT_U_TURN_CLOCKWISE
|
|
ROUNDABOUT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_CLOCKWISE
|
|
ROUNDABOUT_EXIT_COUNTERCLOCKWISE
|
|
ROUNDABOUT_EXIT_CLOCKWISE
|
|
MERGE_RIGHT OFF_RAMP_RIGHT
|
|
MERGE_LEFT OFF_RAMP_LEFT
|
|
FORK_RIGHT TURN_KEEP_RIGHT ON_RAMP_KEEP_RIGHT OFF_RAMP_KEEP_RIGHT
|
|
FORK_LEFT TURN_KEEP_LEFT ON_RAMP_KEEP_LEFT OFF_RAMP_KEEP_LEFT
|
|
MERGE_UNSPECIFIED
|
|
DESTINATION
|
|
DESTINATION_RIGHT
|
|
DESTINATION_LEFT
|
|
FERRY_BOAT
|
|
FERRY_TRAIN
|
Utiliser les icônes générées
Pour faciliter les cas d'utilisation d'Android Auto, le SDK Navigation permet de générer des icônes de manœuvre et de guidage sur les voies. Ces icônes correspondent aux conseils de dimensionnement des images de la bibliothèque Android Auto Car App, qui recommande de cibler un cadre de délimitation de 500 x 74 dp. Pour en savoir plus, consultez setsLaneImage et CarIcon dans la documentation de référence Android.
Exemple de génération d'icônes
NavigationUpdatesOptions options =
NavigationUpdatesOptions.builder()
.setNumNextStepsToPreview(numNextStepsToPreview)
.setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
.setDisplayMetrics(getResources().getDisplayMetrics())
.build();
boolean isRegistered =
navigator.registerServiceForNavUpdates(
getPackageName(),
NavInfoReceivingService.class.getName(),
options);
Une fois que vous avez activé la génération d'icônes, l'objet TurnbyTurn StepInfo
remplit les champs maneuverBitmap et lanesBitmap avec les icônes.
Étapes suivantes
- Pour les applications Android Auto :