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

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

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

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

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

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

Обзор

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

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

  1. Настройте свою среду для доступа к хост-репозиторию Maven:

    Мавен

    Добавьте в файл pom.xml следующее:

        <project>
          ...
          <repositories>
            <repository>
              <id>google-maven-repository</id>
              <url>https://maven.google.com</url>
            </repository>
          </repositories>
          ...
        </project>
        
        

    Градл

    Добавьте в файл build.gradle следующее:

    repositories {
        ...
        google()
    }
        
  2. Добавьте следующую зависимость в вашу конфигурацию Maven или Gradle:
  3. Мавен

    <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. См. пример отображения навигации, в котором показаны основные элементы .

Создайте сервис для получения обновлений навигации.

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 .

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

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

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

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

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

Отмена регистрации сервиса

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

navigator.unregisterServiceForNavUpdates();

Понимание состояний навигации

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

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

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

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

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

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

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

Что дальше