Włącz szczegółowy plik danych

Pliki danych z informacjami krok po kroku zawierają informacje nawigacyjne przeznaczone do urządzeń, które nie są przeznaczone do nawigacji na mapie. Dzięki dostarczonym przez Ciebie elementom możesz wykonać kolejne ruchy:

• ikony (skręt w lewo, w prawo, zawracanie)
• numery na rondzie
• nazwy dróg
• szacowana odległość i czas do następnego etapu nawigacji lub 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. Jest to przydatne na przykład w przypadku kierowców pojazdów dwukołowych, gdzie możesz wyświetlać wskazówki dotyczące nawigacji, aby szybciej i pewniej docierać do celu przy minimalnym rozpraszaniu uwagi.

Aby korzystać z pakietu SDK, musisz utworzyć usługę i zarejestrować ją w pakiecie SDK Navigation SDK na Androida, aby otrzymywała nowe informacje nawigacyjne w czasie rzeczywistym (mniej więcej raz na sekundę podczas nawigacji).

Z tego dokumentu dowiesz się, jak utworzyć i zarejestrować usługę nawigacji, która odbiera informacje nawigacyjne z pakietu SDK i udostępnia stan nawigacji urządzeniu odbierającemu.

Omówienie

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

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

Uwaga: możesz pominąć ten krok, jeśli Twoja aplikacja jest już skonfigurowana za pomocą pakietu Navigation SDK, który zawiera bibliotekę TurnByTurn.

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'
   }
       

Dodaj bibliotekę TurnByTurn do projektu za pomocą pobranego pliku JAR (alternatywnego)

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. Dodaj ten kod do pliku build.gradle, aby uwzględnić plik JAR w kompilacji.

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

Korzystanie z biblioteki TurnByTurn

Oto ogólne kroki, które musisz wykonać, aby włączyć funkcję zakręt po zakręcie. W sekcjach poniżej znajdziesz szczegółowe informacje o każdym kroku.

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

2. Zarejestruj usługę.

3. Zapoznaj się ze stanami nawigacji.

4. Zobacz przykład wyświetlania nawigacji z podstawowymi elementami

Tworzenie usługi do otrzymywania aktualizacji nawigacji

Navigation SDK tworzy powiązanie z usługą TurnByTurn i wysyła do niej aktualizacje nawigacji przez Android Messenger. Na potrzeby tych aktualizacji możesz utworzyć nową usługę nawigacji lub użyć istniejącej.

Korzyścią z użycia 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.

Uwaga: pamiętaj o pomijaniu zakresu wartości 7200–7299 w przypadku kodów wiadomości, ponieważ w przyszłości pakiet SDK nawigacji może używać tych kodów.

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 powiąże z nią pakiet SDK nawigacji. 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ę z pakietu SDK Navigation.

navigator.unregisterServiceForNavUpdates();

Informacje o stanach 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;

• Zmiana trasy – REROUTING oznacza, że nawigacja trwa, ale nawigacja 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 informacji nawigacyjnych, aby nie wyświetlały się instrukcje dotyczące poprzednich kroków.

Wypełnianie widoku kanału

Po skonfigurowaniu usługi zakręt po zakręcie ta sekcja obejmuje elementy wizualne i tekstowe, których możesz użyć do wypełnienia kart ze wskazówkami dotyczącymi wskazówek zakręt po zakręcie.

Pola informacji na karcie 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 na informacje nawigacyjne i miejsca, w których można je znaleźć.

Pola dla każdego 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 Navigation SDK reprezentuje pasy na karcie 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

Ten fragment przedstawia dane dotyczące pasów widocznych 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ć mapowanie jeden-do-jednego do ikony, takiej 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ą się wiązać z ikoną skrętu w lewo.

Manewry w Android Auto: manewry w pakiecie SDK nawigacji są mapowane jeden do jednego na Androida Auto, ale musisz przekonwertować typy na prawidłowy format dla Androida Auto. Patrz Sprawdzanie prawidłowych typów manewrów w artykule Włączanie nawigacji w Androidzie Auto.

Niektóre manewry zawierają dodatkową etykietę clockwise lub counterclockwise, którą pakiet SDK określa na podstawie 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 lewostronnym czy prawostronnym ruchu drogowym, i wyświetla odpowiedni manewr. Z tego powodu ikona może być inna w przypadku skrętu w prawo i w lewo.

Rozwiń, aby zobaczyć przykładowe ikony różnych manewrów

Ikona przykładowej	Makiety TurnByTurn
	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

Używanie wygenerowanych ikon

Aby ułatwić korzystanie z Androida Auto, pakiet Navigation SDK obsługuje generowanie ikon skrętu i asystenta pasa ruchu. 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 sekcjach setsLaneImage i CarIcon w dokumentacji Androida.

Uwaga: generowanie ikon jest domyślnie wyłączone.

Przykład generowania ikon

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ę.