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

• アイコン（左折、右折、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. ナビゲーション状態について

4. 必須要素を表示するナビゲーション ディスプレイの例をご覧ください。

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

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 状態は、ガイド付きナビゲーションが有効であり、ユーザーが指定された経路を進んでいることを意味します。現在の次の操作ステップに関する情報が表示されます。

• ルートの再検索 - REROUTING は、ナビゲーションが進行中だが、ナビゲータが新しいルートを検索していることを意味します。新しいルートはまだないため、次の操作ステップは利用できません。サンプルアプリでは、ナビゲーション情報ディスプレイに「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 ターンで時計回りに、道路の右側の国では時計回りに走行します。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 アプリの場合:
  • 地図を描画してナビゲーションを有効にする。