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

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

  • Icônes (gauche, droite, demi-tour)
  • numéros de virage dans les ronds-points
  • noms de rues ;
  • les distances et le temps estimés 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 où l'UI complète du SDK Navigation n'est pas adaptée, par exemple pour Android Auto ou pour les écrans de petit format où une pile Android complète n'est pas disponible. Par exemple, vous pouvez utiliser cette fonctionnalité pour les conducteurs de véhicules à deux roues, afin de leur projeter des instructions de navigation uniquement pour les aider à atteindre leur destination plus rapidement et en toute confiance, 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 à partir 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 d'ensemble pour créer une fonctionnalité de navigation détaillée.

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 hôte :

    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>

    Gradle

    Ajoutez le code ci-dessous à votre fichier build.gradle :

    repositories {
    ...
    google()
}
  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 à l'aide d'un fichier JAR téléchargé (autre méthode)

La bibliothèque TurnByTurn est disponible sous la forme d'un fichier JAR dans ce dossier de 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 ce qui suit à votre build.gradle pour inclure le fichier JAR dans votre build.

    dependencies {
    ...
    api fileTree(include: ['*.jar'], dir: 'libs')
}

Utiliser la bibliothèque TurnByTurn

Voici les grandes étapes à suivre pour activer la fonctionnalité de navigation étape par étape. Les sections suivantes fournissent des détails sur chaque étape.

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

  2. Enregistrez le service.

  3. Comprendre les états de navigation

Créer un service pour recevoir des informations 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 des mises à jour de navigation est que le service peut résider 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 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 message

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 recevoir des informations 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 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 façon dont vous configurez votre application, vous pouvez envisager de démarrer un service de premier plan, décrit dans la section 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 à partir du SDK Navigation.

navigator.unregisterServiceForNavUpdates();

Comprendre les états de navigation

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

  • En route : 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 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'exemple d'application, le message "Itinéraire modifié…" s'affiche dans l'écran d'informations de navigation. Une fois qu'un parcours a été trouvé, 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 des instructions de procédure ne soient affichées.

Remplir l'affichage du flux

Maintenant que vous avez configuré votre service de navigation, cette section présente les éléments visuels et textuels que vous pouvez utiliser pour renseigner les fiches de guidage du flux de navigation.

Écran d&#39;un mobile affichant un virage à gauche à 30 m sur W Ahwanee Ave. En bas de l&#39;écran, le temps restant avant d&#39;atteindre la destination est de 46 minutes et la distance restante est de 63 km.

Lorsque l'utilisateur active la navigation guidée, une fiche de navigation s'affiche en haut de l'écran, contenant des 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 du trajet global
Trouvé dans StepInfo Trouvé dans NavInfo
Nom complet de la rue Temps restant
Icône de manœuvre Distance par rapport à la destination
Distance jusqu'à l'étape suivante
Champs de l'assistant de voies de circulation

Assistant de voies de circulation

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 et contient une liste d'objets LaneDirection qui décrivent tous les virages pouvant être effectués à partir de cette voie.

Exemple de configuration de guidage de voie.

Le sens de circulation recommandé pour un utilisateur dans une voie est indiqué par le champ isRecommended.

Exemple d'assistant de voies de circulation

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 pouvant 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 associées. Pour certaines manœuvres, vous pouvez configurer un mappage individuel 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 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 du côté de la route sur lequel les conducteurs circulent dans un pays. Par exemple, dans les pays où la circulation se fait à gauche, les conducteurs effectuent un rond-point ou 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 de navigation détecte si une manœuvre se produit dans le trafic à gauche ou à droite, et génère la manœuvre appropriée. Par conséquent, l'icône de la manœuvre peut être différente pour une manœuvre dans le sens des aiguilles d'une montre ou dans le sens inverse.

Développez pour voir des exemples d'icônes pour différentes manœuvres

Icône d'exemple Manœuvres de navigation
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 des icônes générées

Petite liste d&#39;icônes générées fournies par le SDK Navigation.

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 de voie. Ces icônes respectent les consignes de dimensionnement des images de la bibliothèque d'applications pour voitures Android Auto, qui recommande de cibler une zone 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 la génération d'icônes activée, l'objet StepInfo de navigation TurnbyTurn renseigne les champs maneuverBitmap et lanesBitmap avec les icônes.

Étape suivante