Включить пошаговую подачу данных

Поток данных с указанием поворотов предоставляет только навигационную информацию устройствам, не предназначенным для навигации по карте. Он обеспечивает предстоящие маневры с помощью предоставленных вами элементов:

• значки (влево, вправо, разворот)
• поворачивать цифры на кольцевых развязках
• названия дорог
• расчетные расстояния и время до следующего этапа навигации или конечного пункта назначения

Вы можете использовать пошаговую ленту для создания возможностей, в которых полный пользовательский интерфейс Navigation SDK не подходит, например, для Android Auto или для небольших экранов, где полный стек Android недоступен. Например, вы можете использовать это для водителей двухколесных транспортных средств, где вы можете проецировать только навигационные указания, чтобы помочь им быстрее и увереннее добраться до места назначения с минимальными отвлекающими факторами.

Чтобы использовать SDK, вы создадите службу и зарегистрируете ее в Navigation SDK для Android, чтобы она могла получать новую навигационную информацию в режиме реального времени (примерно раз в секунду во время навигации).

В этом документе показано, как создать и зарегистрировать службу навигации, которая получает навигационную информацию из SDK и предоставляет состояние навигации принимающему устройству.

Обзор

В этом разделе описывается, как добавить библиотеку TurnByTurn в ваши проекты, и обобщается высокоуровневый процесс создания пошаговой функциональности.

Добавьте библиотеку TurnByTurn в свой проект с помощью Maven (рекомендуется)

Примечание. Вы можете пропустить этот шаг, если в вашем приложении уже настроен навигационный SDK, который сам содержит библиотеку TurnByTurn.

Чтобы использовать автономную версию библиотеки TurnByTurn, выполните следующие действия:

1. Настройте свою среду для доступа к хост-репозиторию Maven, как описано в разделе «Начало работы с Driver SDK» в документации Trip and Order .

2. Добавьте следующую зависимость в вашу конфигурацию Maven или Gradle:

   Мавен

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.maps</groupId>
       <artifactId>google_turnbyturn</artifactId>
       <version>1.0.0</version>
     </dependency>
   </dependencies>
   

   Градл

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
   

Добавьте библиотеку TurnByTurn в свой проект, используя загруженный файл JAR (альтернативный вариант).

Библиотека TurnByTurn доступна в виде JAR-файла в этой папке SDK . Если у вас нет доступа, обратитесь к своему представителю.

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

Коды сообщений

Сообщения NavInfo можно идентифицировать с помощью поля Message.what класса Message , для которого установлено значение TurnByTurnManager.MSG_NAV_INFO .

Примечание. Обязательно оставьте диапазон значений 7200–7299 для кодов сообщений, поскольку в будущем Navigation SDK может использовать коды сообщений в этом диапазоне.

Регистрация сервиса для обновлений навигации {#register}

Следующие фрагменты кода регистрируют службу навигации.

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

Запуск и остановка службы

Служба навигации активна, пока к ней привязан навигационный SDK. Вы можете вручную вызвать startService() и stopService() для управления жизненным циклом службы навигации, но когда вы регистрируете свою службу с помощью Navigation SDK, она запускается автоматически и останавливается только тогда, когда вы отменяете ее регистрацию. В зависимости от того, как вы настроили свое приложение, вы можете рассмотреть возможность запуска службы переднего плана, описанной в документации Android Обзор служб .

Отмена регистрации услуги

Чтобы прекратить получение обновлений навигации, отмените регистрацию службы в Navigation SDK.

navigator.unregisterServiceForNavUpdates();

Понимание состояний навигации {#states}

Используйте NavInfo.getNavState() чтобы получить текущее состояние навигации, которое может быть одним из следующих:

• На маршруте . Состояние ENROUTE означает, что управляемая навигация в данный момент активна и пользователь находится на указанном маршруте. Доступна информация о текущем предстоящем этапе маневра.

• Изменение маршрута - REROUTING означает, что навигация идет, но навигатор ищет новый маршрут. Предстоящий этап маневра недоступен, поскольку нового маршрута еще нет. В примере приложения на дисплее навигационной информации появляется сообщение «Изменение маршрута...». Как только маршрут найден, отправляется сообщение NavInfo со статусом ENROUTE .

• Остановлено – STOPPED означает, что навигация завершена. Например, навигация прекращается, когда пользователь выходит из навигации в приложении. В примере приложения состояние STOPPED очищает отображение навигационной информации, чтобы предотвратить отображение устаревших пошаговых инструкций.

Заполните отображение ленты

Теперь, когда вы настроили службу пошаговых инструкций, в этом разделе рассматриваются визуальные и текстовые элементы, которые вы можете использовать для заполнения карточек с пошаговыми инструкциями.

Информационные поля навигационной карты

Когда водитель входит в управляемую навигацию, вверху появляется навигационная карточка, содержащая дату навигации, заполненную из 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 могут отображаться на значке левого поворота.

Маневры Android Auto . Маневры в Navigation SDK однозначно сопоставлены с Android Auto, но необходимо преобразовать типы в правильный формат для Android Auto. См. раздел «Убедитесь в правильности типов маневров» в разделе «Включение навигации для Android Auto» .

Некоторые маневры содержат дополнительную метку clockwise или counterclockwise , которую SDK определяет в зависимости от ведущей стороны страны. Например, в странах, где движение осуществляется по левой стороне дороги, водители совершают круговой разворот или разворот по часовой стрелке, тогда как в странах с правосторонним движением дороги движутся по часовой стрелке. Навигационный 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

Используйте сгенерированные значки

Для облегчения использования Android Auto Navigation SDK поддерживает создание значков маневра и указания полосы движения. Эти значки соответствуют рекомендациям по размеру изображений библиотеки автомобильных приложений Android Auto, в которых рекомендуется использовать ограничивающую рамку размером 500 x 74 dp. Подробности см. в разделах setLaneImage и CarIcon в справочной документации Android.

Примечание. По умолчанию создание значков отключено.

Пример создания иконки

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

После включения генерации значков объект TurnbyTurn StepInfo заполняет значками поля маневра и полосы движения .

Что дальше

• Для приложений Android Auto :
  • Нарисуйте карту и включите навигацию .