Navigation SDK 目前僅供特定客戶使用。如要瞭解詳情，請聯絡銷售人員。

Google 地圖平台即將推出全新地圖樣式設定。本次地圖樣式更新包含新的預設調色盤，並改善地圖體驗和可用性。所有地圖樣式都將在 2025 年 3 月自動更新。如要進一步瞭解可用性及如何選擇加入計畫，請參閱「Google 地圖平台的全新地圖樣式」一文。

本頁面由 Cloud Translation API 翻譯而成。

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

即時路線資料動態饋給會為非以地圖為導航指引設計的裝置提供僅限導航的資訊。這項服務會根據您提供的元素，提供即將執行的動作：

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

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

如要使用 SDK，您必須建立服務並將其註冊至 Navigation SDK for Android，以便即時接收新的導航資訊 (在導航期間約每秒一次)。

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

總覽

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

使用 Maven 將 TurnByTurn 程式庫新增至專案 (建議)

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

設定環境，以便存取主機 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()
}

將下列依附元件新增至 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 檔案。如果您沒有相關存取權，請與您的代表聯絡。

下載並解壓縮 google_turnbyturn_*.jar。
將下載的 JAR 檔案複製到專案的 app/libs 目錄中。

將以下內容加入 build.gradle，即可在版本中加入 JAR。

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

使用 TurnByTurn 程式庫

以下是啟用即時路線功能的大致步驟。以下各節將詳細說明每個步驟。

建立接收導航更新的服務。
註冊服務。
瞭解導覽狀態。

建立接收導覽更新的服務

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...」訊息會顯示在導航資訊顯示畫面中。找到路線後，系統會傳送 NavInfo 訊息，並附上狀態 ENROUTE。
已停止：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 會偵測左側或右側車流中是否發生變換動作，並輸出適當的變換動作。因此，如果是順時針或逆時針的機動，圖示可能會有所不同。

展開即可查看不同機動動作的圖示範例

範例圖示	TurnByTurn 操作
	`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 欄位中填入圖示。

後續步驟

適用於 Android Auto 應用程式：
- 繪製地圖並啟用導航功能。