啟用即時路線導航資料動態饋給

即時路線資料動態饋給可為非針對地圖式導航指引的裝置提供導航資訊。它可以使用您提供的元素進行後續操作：

  • 圖示 (左、右、迴轉)
  • 將數字轉換成圓環。
  • 道路名稱
  • 到下個導航步驟或最終目的地的預估距離和時間

您可以使用即時路線動態饋給，打造不適用完整 Navigation SDK UI 的體驗，例如 Android Auto 或小螢幕 (無法使用完整 Android 堆疊) 的情況。舉例來說，您可以為雙輪車輛提供這項功能，例如規劃僅供導航的指引，協助使用者更快、更安心地抵達目的地，盡量減少干擾。

如要使用 SDK，您將建立服務，並透過適用於 Android 的 Navigation SDK 註冊，以便即時接收新的導航資訊 (導航期間約一秒一次)。

本文說明如何建立及註冊從 SDK 接收導航資訊的導航服務，並為接收裝置提供導覽狀態。

總覽

本節說明如何將 TurnByTurn 程式庫新增至專案，並概略說明建構即時路線功能的高階流程。

如要使用獨立版本的 TurnByTurn 程式庫，請按照下列步驟操作：

  1. 按照行程與訂單說明文件中的開始使用驅動程式 SDK 一文，設定環境來存取主機 Maven 存放區。

  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. 查看顯示基本元素的導覽顯示範例。

建立服務來接收導航更新 {#service}

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

訊息代碼

您可以透過 Message 類別的 Message.what 欄位 (設為 TurnByTurnManager.MSG_NAV_INFO 的值) 來識別 NavInfo 訊息。

註冊服務以接收導航更新 {#register}

下列程式碼片段會註冊導航服務。

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

啟動及停止服務

只要 Navigation SDK 繫結至服務，導航服務就會啟用。您可以手動呼叫 startService() 和 stopService() 來控制導航服務生命週期，但當您使用 Navigation SDK 註冊服務時，服務會自動啟動，而且只有在您取消註冊時才會停止。視應用程式的設定方式而定，建議您考慮啟動前景服務，詳情請參閱 Android 說明文件「服務總覽」。

取消註冊服務

如要停止接收導航更新，請從 Navigation SDK 取消註冊服務。

navigator.unregisterServiceForNavUpdates();

瞭解導覽狀態「{#states}」

使用 NavInfo.getNavState() 取得導航目前的狀態，為下列其中一種狀態：

  • Enroute - ENROUTE 狀態表示引導式導航目前處於有效狀態，且使用者位於所提供的路徑上。並提供目前即將推出的驅動程式步驟相關資訊。

  • 「重新傳送」- REROUTING 表示導航正在進行，但導航器正在尋找新路徑。目前還沒有新路徑，因此無法使用接下來的駕駛步驟。在範例應用程式中，導航資訊顯示畫面會顯示「正在重新規劃路線」。找到路徑後，會傳送包含 ENROUTE 狀態的 NavInfo 訊息。

  • 已停止 - STOPPED 表示導航已結束。舉例來說，當使用者在應用程式中離開導航時，導覽就會停止。在範例應用程式中，STOPPED 狀態會清除導航資訊顯示，以免顯示其餘步驟指示。

填入動態消息顯示內容

您已設定即時路線服務，本節會說明視覺化和文字元素，可用來在即時路線動態消息中填入指引資訊卡。

行動裝置螢幕上顯示即將在 100 英尺處左轉到 W Ahwanee 大道。在螢幕底部，距離目的地還有 46 分鐘，剩餘距離為 39 英里。

駕駛人進入導覽後，頂端就會顯示導覽資訊卡，其中包含從 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) 設定一對一對應。不過，由於有些操作類似，因此建議您將多項操作對應至單一圖示。舉例來說，TURN_LEFT 和 ON_RAMP_LEFT 都可以對應到左轉圖示。

部分模擬作業包含額外的 clockwise 或 counterclockwise 標籤，SDK 會根據國家/地區的駕駛結果來判斷。例如，在道路左側行駛的國家/地區，駕駛人會順時針或 U 轉彎，而道路右側國家/地區則會順時針旋轉。Navigation SDK 會偵測在左側或右側流量中是否發生，並輸出適當的驅動程式。因此，隨著順時針與逆時針方向，虛擬程式圖示可能有所不同。

展開即可查看不同播放方式的圖示範例

範例圖示 TurnBy Turn 手
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

使用產生的圖示

Navigation SDK 提供的少量圖示清單。

為協助處理 Android Auto 的用途，Navigation SDK 支援產生車道和車道指引圖示。這些圖示符合 Android Auto Car App 程式庫的圖片大小指南 (建議指定 500 x 74 dp 的定界框)。詳情請參閱 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 欄位。

後續步驟