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

Uwaga: możesz pominąć ten krok, jeśli aplikacja została już skonfigurowana za pomocą pakietu SDK nawigacji, 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'
   }
       

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.

Uwaga: pamiętaj, aby zachować zakres wartości 7200–7299 dla kodów wiadomości, ponieważ pakiet SDK nawigacji może w przyszłości używać kodów wiadomości z tego zakresu.

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 nawigacyjnej, 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. Na przykład nawigacja przestaje działać, gdy użytkownik zamknie nawigację w aplikacji. W próbnej aplikacji stan STOPPED powoduje wyczyszczenie wyświetlanych informacji nawigacyjnych, aby nie wyświetlały się opóźnione instrukcje dotyczące 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 nawigacji w karcie skrętu 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ć 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ą być mapowane na ikonę skrętu w lewo.

Manewry w Android Auto: manewry w pakiecie SDK do nawigacji są mapowane jeden do jednego na Androida Auto, ale musisz przekonwertować typy na prawidłowe formaty dla Androida Auto. Więcej informacji na temat zapewniania prawidłowego typu manewru znajdziesz 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 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, podczas gdy w krajach, w których ruch odbywa się po prawej stronie drogi, kierują się 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.

Rozwiń, aby zobaczyć przykłady ikon różnych manewrów

Przykładowa ikona	Manewry w ramach nawigacji szczegółowej
	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 SDK nawigacji obsługuje generowanie ikon wskazówek dotyczących manewrów i pasów 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 dokumentacji referencyjnej Androida dotyczącej setsLaneImage i CarIcon.

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

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