ターンバイターン データフィードは、地図ベースのナビゲーション ガイダンス用に設計されていないデバイスに、ナビゲーション専用情報を提供します。指定した要素を使用して、今後の操作を指定します。

• アイコン（左折、右折、U ターン）
• ロータリーの交差点の番号
• 道路名
• 次のナビゲーション ステップまたは最終目的地までの推定距離と推定時間

ターンバイターン フィードを使用すると、Android Auto や、完全な Android スタックを使用できない小型画面ディスプレイなど、Navigation SDK の完全な UI が適切でないエクスペリエンスを作成できます。たとえば、2 輪車のドライバー向けに、ナビゲーションのみのガイダンスを投影して、ドライバーが気を散らすことなく、より速く、より確実に目的地に到着できるようにします。

SDK を使用するには、サービスを作成して Navigation SDK for Android に登録し、新しいナビゲーション情報をリアルタイムで（ナビゲーション中は約 1 秒に 1 回）受信できるようにします。

このドキュメントでは、SDK からナビゲーション情報を受信し、受信デバイスにナビゲーションの状態を提供するナビゲーション サービスを作成して登録する方法について説明します。

概要

このセクションでは、TurnByTurn ライブラリをプロジェクトに追加する方法と、ターンバイターン機能を構築するための大まかなフローについて説明します。

Maven を使用して TurnByTurn ライブラリをプロジェクトに追加する（推奨）

スタンドアロン バージョンの TurnByTurn ライブラリを使用する手順は次のとおりです。

1. ホストの Maven リポジトリにアクセスするように環境を設定します。

   Maven

   次のコードを pom.xml ファイルに追加します。

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   Gradle

   次のコードを build.gradle ファイルに追加します。

   repositories {
       ...
       google()
   }
       

2. Maven または 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'
   }
       

ダウンロードした JAR ファイルを使用して TurnByTurn ライブラリをプロジェクトに追加する（代替方法）

TurnByTurn ライブラリは、この SDK フォルダの JAR ファイルとして入手できます。アクセス権がない場合は、担当者にお問い合わせください。

1. google_turnbyturn_*.jar をダウンロードして解凍します。
2. ダウンロードした JAR ファイルをプロジェクトの app/libs ディレクトリにコピーします。

3. build.gradle に次のコードを追加して、ビルドに JAR を含めます。

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

TurnByTurn ライブラリの使用

ターンバイターン機能を有効にする手順の概要は次のとおりです。以降のセクションでは、各ステップについて詳しく説明します。

1. ナビゲーションの更新を受け取るサービスを作成する。

2. サービスを登録します。

3. ナビゲーションの状態を理解する。

ナビゲーションの更新を受け取るサービスを作成する

Navigation SDK は TurnByTurn サービスにバインドし、Android Messenger を介してナビゲーションの更新を送信します。これらの更新用に新しいナビゲーション サービスを作成することも、既存のサービスを使用することもできます。

サービスを使用してナビゲーションの更新を受け取る利点は、サービスを別のバックグラウンド プロセスに配置できることです。

次の例のサービスは、ナビゲーション情報を受信し、TurnByTurnManager を使用して、ナビゲーションの詳細を含む NavInfo オブジェクトに変換します。

/**
 *   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()));
}

メッセージ コード

NavInfo メッセージは、Message クラスの Message.what フィールドで識別できます。このフィールドは TurnByTurnManager.MSG_NAV_INFO の値に設定されています。

ナビゲーションの更新用にサービスを登録する

次のコード スニペットは、ナビゲーション サービスを登録します。

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

サービスの開始と停止

ナビゲーション サービスは、Navigation SDK がそれにバインドされている限りアクティブです。startService() と stopService() を手動で呼び出してナビゲーション サービスのライフサイクルを制御できますが、Navigation SDK にサービスを登録すると、サービスは自動的に開始され、登録解除すると停止します。アプリの設定によっては、Android のドキュメントのサービスの概要で説明されているフォアグラウンド サービスの開始を検討することをおすすめします。

サービスの登録解除

ナビゲーションの更新の受信を停止するには、Navigation SDK からサービスの登録を解除します。

navigator.unregisterServiceForNavUpdates();

ナビゲーションの状態について

NavInfo.getNavState() を使用して、ナビゲーションの現在の状態を取得します。これは次のいずれかです。

• Enroute - ENROUTE 状態は、ガイド付きナビゲーションが現在アクティブで、ユーザーが指定されたルート上にいることを意味します。現在の次の操作ステップに関する情報が表示されます。

• ルート変更 - REROUTING は、ナビゲーションが進行中だが、ナビゲータが新しいルートを検索していることを意味します。新しいルートはまだないため、次の操作ステップは利用できません。サンプルアプリでは、ナビゲーション情報ディスプレイに「ルート変更中...」というメッセージが表示されます。ルートが見つかったら、ENROUTE の状態の NavInfo メッセージが送信されます。

• 停止 - STOPPED はナビゲーションの終了を示します。たとえば、ユーザーがアプリ内のナビゲーションを終了すると、ナビゲーション停止します。サンプルアプリでは、STOPPED 状態がナビゲーション情報の表示を消去し、残りの手順が表示されないようにします。

フィードのディスプレイにデータを入力する

ここまでで、ターンバイターン サービスを設定しました。このセクションでは、ターンバイターン フィードのガイダンス カードに入力できるビジュアル要素とテキスト要素について説明します。

ナビゲーション カード情報のフィールド

ユーザーがガイド付きナビゲーションを開始すると、上部にナビゲーション カードが表示されます。このカードには、Navigation SDK から入力されたナビゲーション データが含まれています。関連する画像は、これらの必須のナビゲーション要素の例を示しています。

次の表に、ナビゲーション情報のフィールドとその場所を示します。

各ナビゲーション ステップのフィールド	ルート全体のフィールド
StepInfo にあります	NavInfo にあります
道路のフルネーム	残り時間
操縦アイコン	目的地までの距離
次のステップまでの距離
車線案内フィールド

車線案内

Navigation SDK では、ナビゲーションの右折 / 左折カードの車線を Lane データ オブジェクトと LaneDirection データ オブジェクトで表します。Lane オブジェクトは、ナビゲーション中の特定のレーンを表します。このオブジェクトには、このレーンから行えるすべての曲がり角を記述する LaneDirection オブジェクトのリストがあります。

車線でユーザーが進むべき推奨方向は、isRecommended フィールドでマークされます。

車線案内の例

次のスニペットは、上記のレーンのデータ表現を示しています。

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

操縦のアイコンを作成する

Maneuver 列挙型には、ナビゲーション中に発生する可能性のある操作がそれぞれ定義されています。特定のステップの操作は、StepInfo.getManeuver() メソッドから取得できます。

操縦アイコンを作成して、関連する操縦とペア設定する必要があります。一部の操作では、DESTINATION_LEFT や DESTINATION_RIGHT などのアイコンに 1 対 1 のマッピングを設定できます。ただし、一部の操作は類似しているため、複数の操作を 1 つのアイコンにマッピングすることもできます。たとえば、TURN_LEFT と ON_RAMP_LEFT の両方を左折アイコンにマッピングできます。

一部の操作には、追加の clockwise ラベルまたは counterclockwise ラベルが含まれます。これは、国の運転側に基づいて SDK によって決定されます。たとえば、左側通行の国では、ドライバーは時計回りにロータリーや U ターンをしますが、右側通行の国では反時計回りに U ターンします。Navigation SDK は、左側または右側の交通で操作が行われるかどうかを検出し、適切な操作を出力します。そのため、時計回りと反時計回りの操作では、操作アイコンが異なる場合があります。

生成されたアイコンを使用する

Android Auto のユースケースを容易にするため、Navigation SDK は、操作と車線案内アイコンの生成をサポートしています。これらのアイコンは、500 x 74 dp の境界ボックスをターゲットにすることを推奨している Android Auto 自動車向けアプリ ライブラリの画像サイズのガイダンスに準拠しています。詳しくは、Android リファレンス ドキュメントの setsLaneImage と CarIcon をご覧ください。

アイコン生成の例

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

アイコンの生成を有効にすると、TurnbyTurn StepInfo オブジェクトは、maneuverBitmap フィールドと lanesBitmap フィールドにアイコンを入力します。

次のステップ

• Android Auto アプリの場合:
  • 地図を描画してナビゲーションを有効にする。