启用精细数据 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 库添加到您的项目中

DonByTurn 库以 JAR 文件的形式位于此 SDK 文件夹中。如果您无权访问，请与您的代表联系。

  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 表示导航正在进行中，但导航器正在查找新路线。由于还没有新路线，即将到来的操作步骤不可用。在示例应用中，导航信息显示屏中显示“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 字段。

后续步骤