Activer le flux de données détaillés

Un flux de données détaillé fournit des informations de navigation uniquement aux appareils qui ne sont pas conçus pour le guidage de navigation basé sur une carte. Il fournit les manœuvres à venir avec les éléments que vous fournissez :

• Icônes (gauche, droite, demi-tour)
• Numéros de sortie des ronds-points
• Noms de rues
• Distances et temps estimés jusqu'à la prochaine étape de navigation ou la destination finale

Vous pouvez utiliser le flux détaillé pour créer des expériences dans 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. Vous pouvez par exemple l'utiliser pour les conducteurs de véhicules à deux roues, en projetant un guidage de navigation uniquement pour les aider à atteindre leur destination plus rapidement et plus facilement, avec un minimum de 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 des informations de navigation du SDK et fournit l'état de navigation à l'appareil récepteur.

Présentation

Cette section résume le flux général permettant d'activer la fonctionnalité détaillée.

Utiliser la fonctionnalité détaillée

Voici les grandes étapes à suivre pour activer la fonctionnalité détaillée. Les sections suivantes fournissent des informations détaillées sur chaque étape.

1. Créez un service pour recevoir les mises à jour de navigation.

2. Enregistrez le service.

3. Comprenez les états de navigation.

Créer un service pour recevoir les mises à jour de navigation

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 les mises à jour de navigation est qu'il peut s'exécuter dans un processus d'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 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 de messages

NavInfo messages peuvent être identifiés via le Message.what champ de la classe Message, qui est défini sur la valeur de TurnByTurnManager.MSG_NAV_INFO.

Remarque : Veillez à mettre de côté la plage de valeurs 7200-7299 pour les codes de messages, car le SDK Navigation pourra utiliser des codes de messages dans cette plage à l'avenir.

Enregistrer le service pour les mises à jour de navigation

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 y est lié. Vous pouvez appeler manuellement startService() et stopService() pour contrôler le cycle de vie du service de navigation, mais lorsque vous enregistrez votre service auprès du 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 documentation Android Présentation des services.

Annuler l'enregistrement du service

Pour arrêter de recevoir les mises à jour de navigation, annulez l'enregistrement du service auprès du SDK Navigation.

navigator.unregisterServiceForNavUpdates();

Comprendre les états de navigation

Utilisez NavInfo.getNavState() pour obtenir l'état actuel de la navigation, qui peut être l'un des suivants :

• En route : l'état ENROUTE signifie que la navigation guidée est active et que l'utilisateur suit l'itinéraire fourni. Des informations sur l'étape de manœuvre à venir sont disponibles.

• Recalcul de l'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 aucun nouvel itinéraire n'a encore été trouvé. Dans l'exemple d'application, le message "Recalcul de l'itinéraire..." s'affiche dans l'écran d'informations de navigation. Une fois l'itinéraire trouvé, un message NavInfo est envoyé avec l'état ENROUTE.

• Arrêt : 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'exemple d'application, l'état STOPPED efface l'écran d'informations de navigation pour éviter que les instructions d'étape ne s'affichent.

Remplir l'écran du flux

Maintenant que vous avez configuré votre service détaillé, cette section couvre les éléments visuels et textuels que vous pouvez utiliser pour remplir les cartes de guidage du flux détaillé.

Champs d'informations de la carte de navigation

Lorsque l'utilisateur active la navigation guidée, une carte de navigation s'affiche en haut, contenant les données de navigation renseignées à partir du SDK Navigation. L'image associée montre un exemple de ces éléments de navigation essentiels.

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

Champs pour chaque étape de navigation	Champs pour l'ensemble du trajet
Trouvé dans StepInfo	Trouvé dans NavInfo
Nom complet de la rue	Temps restant
Icône de manœuvre	Distance jusqu'à la destination
Distance jusqu'à l'étape suivante
Champs de guidage sur les voies

Guidage sur les voies

Le SDK Navigation représente les voies sur la carte de navigation sous 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 qui décrivent tous les virages possibles à partir de cette voie.

La direction recommandée qu'un utilisateur doit prendre dans une voie est indiquée par le isRecommended champ.

Exemple de guidage sur les voies

L'extrait 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' Maneuver énumération définit chaque manœuvre possible qui peut se produire pendant 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 correspondantes. Pour certaines manœuvres, vous pouvez configurer un mappage un-à-un vers une icône, comme DESTINATION_LEFT et DESTINATION_RIGHT. Toutefois, comme certaines manœuvres sont similaires, vous pouvez mapper plusieurs manœuvres sur une seule icône. Par exemple, TURN_LEFT et ON_RAMP_LEFT peuvent toutes deux être mappées sur l'icône de virage à gauche.

Manœuvres Android Auto : les manœuvres du SDK Navigation sont mappées un-à-un sur Android Auto, mais vous devez convertir les types au format approprié pour Android Auto. Consultez la section Vérifier les types de manœuvres corrects dans Activer la navigation pour Android Auto.

Certaines manœuvres contiennent un libellé clockwise ou counterclockwise supplémentaire, que le SDK détermine en fonction du sens de circulation d'un pays. Par exemple, dans les pays où la circulation se fait à gauche, les conducteurs prennent un rond-point ou font un demi-tour dans le sens des aiguilles d'une montre, tandis que dans les pays où la circulation se fait à droite, ils le font dans le sens inverse des aiguilles d'une montre. Le SDK Navigation détecte si une manœuvre se produit dans un trafic à gauche ou à 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'il s'agit d'une manœuvre dans le sens des aiguilles d'une montre ou dans le sens inverse.

Développer pour afficher des exemples d'icônes pour différentes manœuvres

Exemple d'icône	Manœuvres détaillées
	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 sont conformes aux consignes de dimensionnement des images de la bibliothèque d'applications pour voitures Android Auto, qui recommande de cibler un cadre de délimitation de 500 x 74 dp. Pour en savoir plus, consultez les sections setsLaneImage et CarIcon de la documentation de référence Android.

Remarque : La génération d'icônes est désactivée par défaut.

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 la génération d'icônes activée, l'objet TurnbyTurn StepInfo remplit les champs maneuverBitmap et lanesBitmap avec les icônes.

Étape suivante

• Pour les applications Android Auto:
  • Dessinez la carte et activez la navigation.