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 le guidage de la navigation basé sur une carte. Il fournit les manœuvres à venir avec les éléments que vous fournissez:

• Icônes (gauche, droite, demi-tour)
• tournez les numéros sur les ronds-points
• noms des routes
• une estimation des distances et du temps de trajet jusqu'à l'étape de navigation suivante 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 deux-roues, où vous pouvez projeter des conseils de navigation pour les aider à atteindre leur destination plus rapidement et en toute confiance, tout en minimisant les distractions.

Pour utiliser le SDK, vous devez 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 les informations de navigation du SDK et fournit l'état de navigation à l'appareil destinataire.

Présentation

Cette section explique comment ajouter la bibliothèque TurnByTurn à vos projets et résume le flux général de 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, procédez comme suit:

1. Configurez votre environnement pour accéder au dépôt Maven de l'hôte, comme décrit dans la section Premiers pas avec le SDK Driver de la documentation sur les trajets et les commandes.

2. 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 en utilisant un fichier JAR téléchargé (alternative)

La bibliothèque TurnByTurn est disponible sous forme de fichier JAR dans ce dossier SDK. Si ce n'est pas le cas, contactez votre représentant.

1. Téléchargez et décompressez google_turnbyturn_*.jar.
2. Copiez le fichier JAR téléchargé dans le répertoire app/libs de votre projet.

3. Ajoutez les éléments suivants à 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 principales étapes à suivre pour activer la fonctionnalité de navigation détaillée. Les sections suivantes fournissent des informations sur chaque étape.

1. Créez un service pour recevoir des informations sur la navigation.

2. Enregistrez le service.

3. Comprendre les états de navigation

4. Consultez un exemple d'affichage de navigation qui montre les éléments essentiels.

Créer un service pour recevoir des informations sur la 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 s'exécuter dans un processus d'arrière-plan distinct.

Le service de l'exemple suivant 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 la navigation {#register}

L'extrait de code suivant enregistre 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, mais lorsque vous enregistrez votre service avec le SDK Navigation, il démarre automatiquement et ne s'arrête que lorsque vous l'annulez. Selon 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 mises à jour de navigation, annulez l'enregistrement du service du SDK Navigation.

navigator.unregisterServiceForNavUpdates();

Comprendre les états de navigation {#states}

Utilisez NavInfo.getNavState() pour obtenir l'état actuel de la navigation, qui correspond à l'un des éléments 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 à venir de la manœuvre actuelle sont disponibles.

• Changement d'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 "Rerouting..." s'affiche dans les informations de navigation. Une fois qu'une route est trouvée, un message NavInfo est envoyé avec l'état ENROUTE.

• Arrêtée : STOPPED signifie que la navigation est terminée. Par exemple, la navigation s'arrête lorsque l'utilisateur quitte la navigation dans l'application. Dans l'application exemple, un état STOPPED efface l'affichage des informations de navigation pour éviter que les instructions d'étape restantes ne s'affichent.

Remplir l'affichage du flux

Maintenant que vous avez configuré votre service de navigation détaillée, cette section présente les éléments visuels et textuels que vous pouvez utiliser pour remplir les fiches d'aide du flux de navigation détaillée.

Champs d'informations de la carte de navigation

Lorsque le conducteur entre dans la navigation guidée, une carte de navigation apparaît en haut, contenant la date de navigation renseignée à partir du SDK Navigation. L'image associée montre un exemple de ces éléments de navigation essentiels.

Ce tableau présente les champs des informations de navigation et leur emplacement.

Champs pour chaque étape de navigation	Champs pour le trajet global
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 en tant qu'objets de données Lane et LaneDirection. Un objet Lane représente une voie spécifique pendant la navigation. Il comporte une liste d'objets LaneDirection qui décrivent tous les virages qui peuvent être effectués à partir de cette voie.

Le sens qu'un conducteur doit emprunter sur une voie est indiqué dans le champ isRecommended.

Exemple d'indication de voie

L'extrait de code suivant illustre la représentation des données des voies 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 lors de la navigation. Vous pouvez obtenir la manœuvre pour 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, par exemple DESTINATION_LEFT et DESTINATION_RIGHT. Cependant, étant donné que certaines manœuvres sont similaires, vous pouvez mapper plusieurs manœuvres à une seule icône. Par exemple, TURN_LEFT et ON_RAMP_LEFT peuvent tous deux correspondre à l'icône de virage de gauche.

Certaines manœuvres contiennent une étiquette clockwise ou counterclockwise supplémentaire, que le SDK détermine en fonction du côté conducteur d'un pays. Par exemple, dans les pays où la conduite s'effectue sur le côté gauche de la route, les conducteurs effectuent un rond-point ou un demi-tour dans le sens des aiguilles d'une montre, tandis que les pays qui roulent à droite de la route s'effectuent dans le sens des aiguilles d'une montre. 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 est dans le sens des aiguilles d'une montre ou dans le sens inverse des aiguilles d'une montre.

Utiliser des 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 voie. Ces icônes correspondent aux conseils de taille d'image 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 StepInfo TurnbyTurn remplit les champs maneuverBitmap et lanesBitmap avec les icônes.

Étapes suivantes

• Pour les applications Android Auto :
  • Dessiner la carte et activer la navigation