启用精细数据 Feed

精细导航数据 Feed 为并非专为基于地图的导航设计的设备提供导航专用信息。它使用您提供的元素为即将发生的操作提供：

  • 图标（向左、向右、调头）
  • 在环岛中转弯数字
  • 道路名称
  • 预计到达下一导航路段或最终目的地的距离和时间

您可以使用精细导航信息流来打造不适合使用完整 Navigation SDK 界面的体验，例如针对 Android Auto 或无法使用完整 Android 堆栈的小屏幕显示屏。例如，您可以针对双轮机动车乘客使用此设置，以便投影仅限导航的指导信息，帮助他们更快速、更放心地到达目的地，同时最大限度地减少干扰。

如需使用该 SDK，您需要创建一个服务并向 Navigation SDK for Android 注册该服务，以便该服务可以实时（在导航期间大约每秒一次）接收新的导航信息。

本文档介绍了如何创建和注册从 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 库添加到您的项目中

此 SDK 文件夹中以 JAR 文件的形式提供 TurnByTurn 库。如果您没有访问权限，请与您的代表联系。

  1. 下载并解压缩 google_turnbyturn_*.jar。
  2. 将下载的 JAR 文件复制到项目的 app/libs 目录中。

  3. 将以下内容添加到 build.gradle，以将 JAR 包含在 build 中。

    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 状态表示引导式导航当前处于活动状态，并且用户位于提供的路线上。提供有关当前即将进行的操作步骤的信息。

  • 正在重选路线 - REROUTING 表示导航正在进行中，但导航器正在查找新路线。即将到来的操作步骤不可用，因为还没有新路线。在示例应用中，导航信息显示区中会显示“正在重新规划...”消息。找到路由后，系统会发送状态为 ENROUTE 的 NavInfo 消息。

  • 已停止 - STOPPED 表示导航已结束。例如，当用户退出应用中的导航时，导航会停止。在示例应用中，STOPPED 状态会清除导航信息显示，以免显示延迟的步骤说明。

填充 Feed 显示内容

现在，您已经设置了精细导航服务，本部分将介绍可用于为精细导航 Feed 填充导航卡片的视觉和文本元素。

一个手机屏幕，显示 100 英尺处即将到来的左转弯，进入 W Ahwanee Ave。在屏幕底部，到达目的地的剩余时间是 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 汽车应用库的图片大小指南，该库建议以 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 字段。

后续步骤