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

即時路線資料動態饋給為未針對地圖式導航指引的裝置提供導航資訊。這項服務會根據您提供的元素提供即將執行的動作：

  • 圖示 (左、右、迴轉)
  • 圓環內的轉彎號誌
  • 道路名稱
  • 到達下個導航步驟或最終目的地的預估距離和所需時間

您可以使用即時路線動態饋給，打造不適合完整 Navigation SDK UI 的體驗，例如 Android Auto 或無法使用完整 Android 堆疊的小螢幕顯示畫面。舉例來說，您可以為二輪車駕駛使用這項功能，在駕駛過程中投放僅含導航指示的內容，協助他們更快、更有信心地抵達目的地，同時減少分心情況。

如要使用這個 SDK，您要建立服務並向 Android 適用的 Navigation SDK 註冊，以便即時接收新的導覽資訊 (大約在導航期間接收一次新的導覽資訊)。

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

總覽

本節說明如何將 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 程式庫新增至專案中

這個 SDK 資料夾會提供 TurnByTurn 程式庫的 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：ENROUTE 狀態表示目前導航功能處於啟用狀態，且使用者正在沿著指定路線行駛。可提供目前後續行動步驟的相關資訊。

  • Rerouting - REROUTING 表示導航正在進行中，但導航工具正在尋找新路徑。由於目前沒有新路線，因此無法顯示即將前往的路線步驟。在範例應用程式中，導覽資訊畫面會顯示「Rerouting...」訊息。找到路徑後，會傳送 ENROUTE 狀態的 NavInfo 訊息。

  • 已停止 - STOPPED 表示導航已結束。舉例來說，當使用者在應用程式中退出導覽時，導覽就會停止。在範例應用程式中，STOPPED 狀態會清除導覽資訊顯示畫面，避免顯示持續的步驟說明。

填入動態消息顯示畫面

您現在已經設定即時路線服務，本節介紹了可使用的視覺和文字元素，以便為即時路線動態饋給填入指引資訊卡。

行動裝置螢幕顯示即將在 100 英尺處左轉至西 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 會根據國家/地區的推動因素決定標籤內容。舉例來說，如果行駛於道路左側行駛的國家/地區，駕駛會順時針方向進行圓環或迴轉，但道路右側的國家/地區則順時針方向。Navigation SDK 會偵測左側或右側車流中是否發生變換動作，並輸出適當的變換動作。因此，如果是順時針或逆時針的機動，圖示可能會有所不同。

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

範例圖示 轉彎手術
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 欄位。

後續步驟