Route zu mehreren Zielen

In dieser Anleitung erfahren Sie, wie Sie in Ihrer App mit dem Navigation SDK for Android eine Route zu mehreren Zielen (sogenannten Wegpunkten) zeichnen.

Überblick

  1. Binden Sie das Navigation SDK in Ihre App ein, wie im Konfigurationshandbuch beschrieben.
  2. Fügen Sie Ihrer App ein NavigationFragment- oder NavigationView-Element hinzu. Dieses UI-Element fügt Ihrer Aktivität die interaktive Karte und die UI mit detaillierter Routenführung hinzu.
  3. Verwenden Sie die Klasse NavigationApi, um das SDK zu initialisieren.

  4. Definieren Sie einen Navigator, um die detaillierte Routenführung zu steuern:

    • Fügen Sie Ziele mit setDestinations() hinzu.
    • Starten Sie die Navigation mit startGuidance().
    • Verwenden Sie getSimulator(), um den Fortschritt des Fahrzeugs auf der Route zu simulieren, um Ihre App zu testen, Fehler zu beheben und zu demonstrieren.

  5. Erstellen Sie Ihre App und führen Sie sie aus.

Code

Navigationsfragment hinzufügen

NavigationFragment ist die UI-Komponente, die die visuelle Ausgabe der Navigation darstellt, einschließlich einer interaktiven Karte und detaillierter Routenführung. Sie können das Fragment in Ihrer XML-Layoutdatei wie unten gezeigt deklarieren:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Alternativ können Sie das Fragment programmatisch erstellen, wie in der Android-Dokumentation beschrieben.

Für Anwendungen, die die Supportversion von Fragment verwenden, bietet das Navigation SDK Kompatibilität über SupportNavigationFragment. Dieses Fragment verhält sich ähnlich wie NavigationFragment und Sie können es programmatisch mit FragmentActivity.getSupportFragmentManager() verwalten.

Als Alternative zu einem Fragment ist die UI-Komponente auch als NavigationView verfügbar. Beachten Sie die Informationen oben in der Klassenbeschreibung, insbesondere in Bezug auf die Anforderung zur Weiterleitung von Lebenszyklusmethoden.

Berechtigung zur Standortermittlung anfordern

Ihre App muss die Berechtigung zur Standortermittlung anfordern, um den Standort des Geräts zu ermitteln.

Dieses Tutorial enthält den Code, den Sie zum Anfordern einer detaillierten Berechtigung zur Standortermittlung benötigen. Weitere Informationen finden Sie im Leitfaden zu Android-Berechtigungen.

  1. Fügen Sie die Berechtigung als untergeordnetes Element des Elements <manifest> in Ihrem Android-Manifest hinzu:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.navsdkmultidestination">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

  2. Fordere in deiner App Laufzeitberechtigungen an und gib dem Nutzer die Möglichkeit, die Berechtigung zur Standortermittlung zu erteilen oder abzulehnen. Mit dem folgenden Code wird geprüft, ob der Nutzer eine gültige Berechtigung zur Standortermittlung erteilt hat. Falls nicht, wird die Berechtigung angefordert:

    if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
        android.Manifest.permission.ACCESS_FINE_LOCATION)
            == PackageManager.PERMISSION_GRANTED) {
    mLocationPermissionGranted = true;
} else {
    ActivityCompat.requestPermissions(this,
            new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
            PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
}

if (!mLocationPermissionGranted) {
    displayMessage("Error loading Navigation SDK: "
            + "The user has not granted location permission.", DISPLAY_BOTH);
    return;
}

  3. Überschreiben Sie den Callback onRequestPermissionsResult(), um das Ergebnis der Berechtigungsanfrage zu verarbeiten:

    @Override
public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                       @NonNull int[] grantResults) {
    mLocationPermissionGranted = false;
    switch (requestCode) {
        case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
            // If request is canceled, the result arrays are empty.
            if (grantResults.length > 0
                    && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                mLocationPermissionGranted = true;
            }
        }
    }
}

Navigation SDK initialisieren und Fahrt konfigurieren

Die Klasse NavigationApi bietet eine Initialisierungslogik, die Ihre App zur Verwendung der Google-Navigation autorisiert. Die Klasse Navigator bietet die Kontrolle über die Konfiguration sowie das Starten und Beenden einer Navigation.

  1. Erstellen Sie eine Hilfsmethode, um eine Nachricht auf dem Bildschirm und im Log anzuzeigen.

    private void displayMessage(String errorMessage, String displayMedium) {
    if (displayMedium.equals(DISPLAY_BOTH) || displayMedium.equals(DISPLAY_TOAST)) {
        Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
    }

    if (displayMedium.equals(DISPLAY_BOTH) || displayMedium.equals(DISPLAY_LOG)) {
        Log.d(TAG, errorMessage);
    }
}

  2. Initialisieren Sie das Navigation SDK und überschreiben Sie den onNavigatorReady()-Callback, um die Navigation zu starten, wenn der Navigator bereit ist:

    NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
            /**
             * Sets up the navigation UI when the navigator is ready for use.
             */
            @Override
            public void onNavigatorReady(Navigator navigator) {
                displayMessage("Navigator ready.", DISPLAY_BOTH);
                mNavigator = navigator;
                mNavFragment = (NavigationFragment) getFragmentManager()
                        .findFragmentById(R.id.navigation_fragment);

                // Set the camera to follow the device location with 'TILTED' driving view.
                mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);

                // Navigate to the specified places.
                navigateToPlaces();
            }

            /**
             * Handles errors from the Navigation SDK.
             * @param errorCode The error code returned by the navigator.
             */
            @Override
            public void onError(@NavigationApi.ErrorCode int errorCode) {
                switch (errorCode) {
                    case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                        displayMessage("Error loading Navigation SDK: Your API key is "
                                + "invalid or not authorized to use the Navigation SDK.",
                                DISPLAY_BOTH);
                        break;
                    case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                        displayMessage("Error loading Navigation SDK: User did not accept "
                                + "the Navigation Terms of Use.", DISPLAY_BOTH);
                        break;
                    case NavigationApi.ErrorCode.NETWORK_ERROR:
                        displayMessage("Error loading Navigation SDK: Network error.",
                                DISPLAY_BOTH);
                        break;
                    case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                        displayMessage("Error loading Navigation SDK: Location permission "
                                + "is missing.", DISPLAY_BOTH);
                        break;
                    default:
                        displayMessage("Error loading Navigation SDK: " + errorCode,
                                DISPLAY_BOTH);
                }
            }
        });

  3. Fügen Sie eine Methode hinzu, um ein Waypoint-Objekt aus einer bestimmten Orts-ID und einem bestimmten Titel zu erstellen.

    private void createWaypoint(String placeId, String title) {
    try {
        mWaypoints.add(
          Waypoint.builder()
                 .setPlaceIdString(placeId)
                 .setTitle(title)
                 .build()
        );
    } catch (Waypoint.UnsupportedPlaceIdException e) {
        displayMessage("Error starting navigation: Place ID is not supported: " + placeId,
                DISPLAY_BOTH);
    }
}

  4. Fügen Sie eine Methode hinzu, um die berechnete Reisezeit und die Entfernung zu jedem Wegpunkt anzuzeigen.

    private void displayTimesAndDistances() {
    List<TimeAndDistance> timesAndDistances = mNavigator.getTimeAndDistanceList();
    int leg = 1;
    String message = "You're on your way!";
    for (TimeAndDistance timeAndDistance : timesAndDistances) {
        message = message + "\nRoute leg: " + leg++
                + ": Travel time (seconds): " + timeAndDistance.getSeconds()
                + ". Distance (meters): " + timeAndDistance.getMeters();
    }
    displayMessage(message, DISPLAY_BOTH);
}

  5. Lege alle Wegpunkte für diese Reise fest. Hinweis: Sie erhalten möglicherweise eine Fehlermeldung, wenn Sie Orts-IDs verwenden, für die in der Navigation keine Route erstellt werden kann. In der Beispiel-App in dieser Anleitung werden Orts-IDs für Wegpunkte in Australien verwendet. Weitere Informationen zum Abrufen verschiedener Orts-IDs finden Sie in den Hinweisen unten. Nach der Berechnung der Route wird im NavigationFragment eine Polylinie angezeigt, die die Route auf der Karte mit einer Markierung an jedem Wegpunkt darstellt.

    private void navigateToPlaces() {

    // Set up a waypoint for each place that we want to go to.
    createWaypoint("ChIJq6qq6jauEmsRJAf7FjrKnXI", "Sydney Star");
    createWaypoint("ChIJ3S-JXmauEmsRUcIaWtf4MzE", "Sydney Opera House");
    createWaypoint("ChIJLwgLFGmuEmsRzpDhHQuyyoU", "Sydney Conservatorium of Music");

    // If this journey is already in progress, no need to restart navigation.
    // This can happen when the user rotates the device, or sends the app to the background.
    if (mSavedInstanceState != null
            && mSavedInstanceState.containsKey(KEY_JOURNEY_IN_PROGRESS)
            && mSavedInstanceState.getInt(KEY_JOURNEY_IN_PROGRESS) == 1) {
        return;
    }

    // Create a future to await the result of the asynchronous navigator task.
    ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
            mNavigator.setDestinations(mWaypoints);

    // Define the action to perform when the SDK has determined the route.
    pendingRoute.setOnResultListener(
            new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                @Override
                public void onResult(Navigator.RouteStatus code) {
                    switch (code) {
                        case OK:
                            mJourneyInProgress = true;
                            // Hide the toolbar to maximize the navigation UI.
                            if (getActionBar() != null) {
                                getActionBar().hide();
                            }

                            // Register some listeners for navigation events.
                            registerNavigationListeners();

                            // Display the time and distance to each waypoint.
                            displayTimesAndDistances();

                            // Enable voice audio guidance (through the device speaker).
                            mNavigator.setAudioGuidance(
                                    Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                            // Simulate vehicle progress along the route for demo/debug builds.
                            if (BuildConfig.DEBUG) {
                                mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                        new SimulationOptions().speedMultiplier(5));
                            }

                            // Start turn-by-turn guidance along the current route.
                            mNavigator.startGuidance();
                            break;
                        // Handle error conditions returned by the navigator.
                        case NO_ROUTE_FOUND:
                            displayMessage("Error starting navigation: No route found.",
                                    DISPLAY_BOTH);
                            break;
                        case NETWORK_ERROR:
                            displayMessage("Error starting navigation: Network error.",
                                    DISPLAY_BOTH);
                            break;
                        case ROUTE_CANCELED:
                            displayMessage("Error starting navigation: Route canceled.",
                                    DISPLAY_BOTH);
                            break;
                        default:
                            displayMessage("Error starting navigation: "
                                    + String.valueOf(code), DISPLAY_BOTH);
                    }
                }
            });
}

App erstellen und ausführen

  1. Verbinden Sie ein Android-Gerät mit Ihrem Computer. Folgen Sie instructions, um Entwickleroptionen auf Ihrem Android-Gerät zu aktivieren und Ihr System so zu konfigurieren, dass das Gerät erkannt wird. Alternativ können Sie mit Android Virtual Device (AVD) Manager ein virtuelles Gerät konfigurieren. Beim Auswählen eines Emulators sollten Sie ein Image angeben, das die Google APIs enthält.)
  2. Klicken Sie in Android Studio auf die Menüoption Run oder das Wiedergabesymbol. Wählen Sie ein Gerät aus, wenn Sie dazu aufgefordert werden.

Tipps für eine bessere User Experience

  • Der Nutzer muss die Nutzungsbedingungen von Google Navigation akzeptieren, bevor die Navigation verfügbar ist. Diese Zustimmung ist nur einmal erforderlich. Standardmäßig werden Sie vom SDK zur Bestätigung aufgefordert, wenn der Navigator zum ersten Mal aufgerufen wird. Sie können das Dialogfeld mit den Nutzungsbedingungen auch zu einem frühen Zeitpunkt im UX-Ablauf Ihrer App auslösen, z. B. bei der Registrierung oder Anmeldung mit showTermsAndConditionsDialog().
  • Die Navigationsqualität und die voraussichtliche Ankunftszeit werden erheblich verbessert, wenn zum Initialisieren eines Wegpunkts Orts-IDs anstelle eines Breiten- und Längengradziels verwendet werden.

  • In diesem Beispiel werden die Wegpunkte von bestimmten Orts-IDs abgeleitet. Weitere Möglichkeiten, eine Orts-ID zu erhalten:

    • Verwenden Sie die Orts-ID-Suche, um Orts-IDs für bestimmte Standorte abzurufen.
    • Sie können Nutzern die Möglichkeit bieten, ein Ziel auszuwählen, indem Sie Ihrer App eine Ortsauswahl hinzufügen. Ein Beispiel für die Ortsauswahl mit dem Navigation SDK finden Sie in der Demo-App, die in der Einführung beschrieben wird.
    • Sie können die Geocoding API verwenden, um die Orts-ID einer bestimmten Adresse zu ermitteln. Die Geocoding API funktioniert gut, wenn die Adressen der Wegpunkte vollständig und eindeutig sind. Weitere Informationen finden Sie im Leitfaden mit Best Practices für die Geocodierung.
    • Verwenden Sie die Textsuche der Places API, um die Orts-ID für eine bestimmte Adresse zu ermitteln. Die Places API eignet sich gut, wenn die Adressen der Wegpunkte unvollständig oder nicht eindeutig sind. Weitere Informationen finden Sie im Leitfaden mit Best Practices für die Geocodierung.

Nächster Schritt

Wenn in Ihrem Vertrag mit Google die Abrechnung pro Transaktion angegeben ist, richten Sie Ihre abrechenbaren Transaktionen ein. Hier erfahren Sie, wie Sie Ereignis-Listener mit Ihrem Navigator verknüpfen, um wichtige Ereignisse wie die Ankunft am Ziel zu erfassen.