Pliki danych z informacjami krok po kroku zawierają informacje nawigacyjne przeznaczone do urządzeń, które nie są przeznaczone do nawigacji na mapie. Umożliwia to uwzględnienie nadchodzących manewrów z uwzględnieniem podanych przez Ciebie elementów:

• ikony (skręt w lewo, w prawo, zawracanie)
• numery na rondzie
• nazwy dróg,
• szacowane odległości i czas do następnego etapu nawigacji lub docelowego miejsca docelowego;

Pliki danych z nawigacją możesz używać do tworzenia funkcji, w których pełny interfejs pakietu SDK do nawigacji nie jest odpowiedni, np. w przypadku Androida Auto lub małych ekranów, na których nie jest dostępny pełny pakiet Androida. Możesz na przykład wyświetlać wskazówki nawigacyjne tylko dla kierowców pojazdów dwukołowych, aby pomagać im w szybszym i bardziej pewnym docieraniu do celu przy minimalnych rozproszeniach.

Aby korzystać z pakietu SDK, utwórz usługę i zarejestruj ją w pakiecie Navigation SDK na Androida, aby mogła otrzymywać nowe informacje nawigacyjne w czasie rzeczywistym (około raz na sekundę podczas nawigacji).

Z tego dokumentu dowiesz się, jak utworzyć i zarejestrować usługę nawigacji, która otrzymuje informacje nawigacyjne z pakietu SDK i przekazuje stan nawigacji do urządzenia odbiorczego.

Omówienie

W tej sekcji opisano, jak dodać do projektów bibliotekę TurnByTurn, oraz podsumowano ogólny proces tworzenia funkcji wskazówek dojazdu.

Dodawanie biblioteki TurnByTurn do projektu za pomocą Maven (zalecane)

Aby użyć samodzielnej wersji biblioteki TurnByTurn:

1. Skonfiguruj środowisko, aby uzyskać dostęp do hostowanego repozytorium Maven:

   Maven

   Dodaj do pliku pom.xml te informacje:

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

   Gradle

   Dodaj do pliku build.gradle te informacje:

   repositories {
       ...
       google()
   }
       

2. Dodaj tę zależność do konfiguracji Maven lub 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'
   }
       

Dodawanie biblioteki TurnByTurn do projektu za pomocą pobranego pliku JAR (alternatywa)

Biblioteka TurnByTurn jest dostępna jako plik JAR w tym folderze pakietu SDK. Jeśli nie masz dostępu, skontaktuj się z przedstawicielem.

1. Pobierz i rozpakuj plik google_turnbyturn_*.jar.
2. Skopiuj pobrany plik JAR do katalogu app/libs projektu.

3. Aby uwzględnić plik JAR w kompilacji, dodaj do pliku build.gradle ten ciąg.

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

Korzystanie z biblioteki TurnByTurn

Oto ogólne instrukcje włączania funkcji wskazówek dojazdu. W sekcjach poniżej znajdziesz szczegółowe informacje o każdym kroku.

1. Utwórz usługę, aby otrzymywać aktualizacje dotyczące nawigacji.

2. Zarejestruj usługę.

3. Poznaj stany nawigacji

Tworzenie usługi do otrzymywania aktualizacji nawigacji

Pakiet SDK do nawigacji łączy się z usługą TurnByTurn i wysyła do niej informacje o nawigacji za pomocą Androida Messenger. Możesz utworzyć nową usługę nawigacji na potrzeby tych aktualizacji lub użyć istniejącej.

Korzyścią z korzystania z usługi do otrzymywania aktualizacji nawigacji jest to, że usługa może działać w ramach osobnego procesu w tle.

Usługa w tym przykładzie otrzymuje informacje nawigacyjne i korzysta z elementu TurnByTurnManager, aby przekonwertować dane na obiekt NavInfo zawierający szczegóły nawigacji.

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

Kody wiadomości

Wiadomości NavInfo można zidentyfikować za pomocą pola Message.what klasy Message, które ma wartość TurnByTurnManager.MSG_NAV_INFO.

Rejestrowanie usługi w celu otrzymywania aktualizacji nawigacji

Poniższe fragmenty kodu rejestrują usługę nawigacji.

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

Uruchamianie i zatrzymywanie usługi

Usługa nawigacji jest aktywna, dopóki pakiet SDK do nawigacji jest z nią powiązany. Aby kontrolować cykl życia usługi nawigacji, możesz ręcznie wywoływać metody startService() i stopService(), ale gdy zarejestrujesz usługę w Navigation SDK, uruchamia się ona automatycznie i zatrzymuje się dopiero po jej wyrejestrowaniu. W zależności od konfiguracji aplikacji możesz rozważyć uruchomienie usługi na pierwszym planie, o której mowa w dokumentacji na temat Androida Podsumowanie dotyczące usług.

Wyrejestrowywanie usługi

Aby przestać otrzymywać aktualizacje nawigacji, wyrejestruj usługę w pakiecie SDK nawigacji.

navigator.unregisterServiceForNavUpdates();

Stany nawigacji

Użyj wartości NavInfo.getNavState(), aby pobrać bieżący stan nawigacji, który jest jedną z tych wartości:

• W drodze – stan ENROUTE oznacza, że nawigacja kierowana jest obecnie aktywna, a użytkownik znajduje się na wskazanej trasie. są dostępne informacje o kroku, który ma być wykonany w ramach bieżącego manewru;

• Wyznaczanie nowej trasy – REROUTING oznacza, że nawigacja jest w toku, ale nawigator szuka nowej trasy. Następny krok manewru jest niedostępny, ponieważ nie ma jeszcze nowej trasy. W próbnej aplikacji na wyświetlaczu z informacjami nawigacyjnymi pojawia się komunikat „Zmiana trasy…”. Po znalezieniu trasy wysyłana jest wiadomość NavInfo ze stanem ENROUTE.

• Zatrzymano STOPPED oznacza, że nawigacja została zakończona. Nawigacja kończy się na przykład wtedy, gdy użytkownik ją zamknie. W przypadku aplikacji przykładowej stan STOPPED powoduje wyczyszczenie wyświetlanych informacji nawigacyjnych, aby nie wyświetlały się instrukcje dotyczące poprzednich kroków.

Wypełnianie wyświetlania pliku danych

Po skonfigurowaniu usługi wskazówek szczegółowych w tej sekcji znajdziesz informacje o elementach wizualnych i tekstowych, których możesz używać do wypełniania kart wskazówek w plikach danych z usługą wskazówek szczegółowych.

Pola informacji karty nawigacyjnej

Gdy użytkownik wejdzie w tryb nawigacji wspomaganej, u góry pojawi się karta nawigacji zawierająca dane nawigacyjne wypełnione z pakietu SDK nawigacji. Powiązany obraz pokazuje przykład tych podstawowych elementów nawigacji.

Ta tabela zawiera pola z informacjami nawigacyjnymi i miejsca, w których je znajdziesz.

Pola w każdym kroku nawigacji	Pola dotyczące całej podróży
Znaleziono w StepInfo	Znaleziono w NavInfo
Pełna nazwa drogi	Pozostały czas
Ikona manewru	Odległość do miejsca docelowego
odległość do następnego kroku;
Pola asystenta pasa ruchu

Asystent pasa ruchu

Pakiet SDK Nawigacji reprezentuje pasy na karcie skrętu w nawigacji jako obiekty danych Lane i LaneDirection. Obiekt Lane reprezentuje określony pas podczas nawigacji i zawiera listę obiektów LaneDirection, które opisują wszystkie zakręty, które można wykonać na tym pasie.

Pole isRecommended wskazuje zalecany kierunek jazdy na pasie.

Przykład asystenta pasa ruchu

Poniższy fragment kodu przedstawia dane dotyczące pasów wyświetlonych powyżej.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

Tworzenie ikon manewrów

Enum Maneuver definiuje wszystkie możliwe manewry, które mogą wystąpić podczas nawigacji. Manewr dla danego kroku możesz uzyskać z metody StepInfo.getManeuver().

Musisz utworzyć ikony manewrów i sparować je z powiązanymi manewrami. W przypadku niektórych manewrów możesz skonfigurować bezpośrednie mapowanie na ikonę, taką jak DESTINATION_LEFT i DESTINATION_RIGHT. Ponieważ jednak niektóre manewry są podobne, możesz przypisać więcej niż jeden manewr do jednej ikony. Na przykład TURN_LEFT i ON_RAMP_LEFT mogą być mapowane na ikonę skrętu w lewo.

Niektóre manewry zawierają dodatkową etykietę clockwise lub counterclockwise, którą pakiet SDK określa na podstawie strony ruchu w danym kraju. Na przykład w krajach, w których ruch odbywa się po lewej stronie drogi, kierowcy skręcają w rondzie lub wykonują manewr cofania zgodnie z kierunkiem ruchu wskazówek zegara, a w krajach, w których ruch odbywa się po prawej stronie drogi, – zgodnie z kierunkiem wskazówek zegara. Pakiet SDK nawigacji wykrywa, czy manewr odbywa się przy ruchu lewo- czy prawostronnym, i wyświetla odpowiedni manewr. Dlatego ikona manewru może się różnić w zależności od tego, czy manewr odbywa się zgodnie z kierunkiem ruchu wskazówek zegara, czy przeciwnie do niego.

Używanie wygenerowanych ikon

Aby ułatwić korzystanie z Androida Auto, pakiet SDK nawigacji obsługuje generowanie ikon kierowania i kierowania po pasach. Te ikony są zgodne ze wskazówkami dotyczącymi rozmiaru obrazu w bibliotece aplikacji samochodowych Androida Auto, która zaleca ustawienie pola ograniczającego o wymiarach 500 x 74 dp. Szczegółowe informacje znajdziesz w dokumentacji referencyjnej Androida dotyczącej setsLaneImage i CarIcon.

Przykład generowania ikony

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

Po włączeniu generowania ikon obiekt TurnbyTurn StepInfo wypełnia pola maneuverBitmap i lanesBitmap ikonami.

Co dalej?

• W przypadku aplikacji na Androida Auto:
  • Rysuj mapę i włącz nawigację.