Routen für einzelne Ziele

Folgen Sie dieser Anleitung, um mit dem Navigation SDK for Android eine Route in Ihrer App darzustellen. In diesem Leitfaden wird davon ausgegangen, dass Sie das Navigation SDK bereits in Ihre App integriert haben, wie unter Projekt einrichten beschrieben.

Zusammenfassung

1. Fügen Sie Ihrer App ein UI-Element hinzu, entweder als Navigationsfragment oder als Navigationsansicht. Mit diesem UI-Element werden Ihrer Aktivität die interaktive Karte und die UI-Navigation mit detaillierter Routenführung hinzugefügt.
2. Fordere Berechtigungen zur Standortermittlung an. Ihre App muss die Berechtigung zur Standortermittlung anfordern, um den Standort des Geräts zu ermitteln.
3. Initialisieren Sie das SDK mit der Klasse NavigationApi.

4. Mit der Klasse Navigator können Sie ein Ziel festlegen und die detaillierte Routenführung steuern. Dieser Vorgang umfasst drei Schritte:

   • Legen Sie das Ziel mit setDestination() fest.
   • 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

package com.example.navsdksingledestination;

import android.content.pm.PackageManager;
import android.os.Bundle;
import android.support.v4.app.ActivityCompat;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;
import android.widget.Toast;
import androidx.annotation.NonNull;
import com.google.android.libraries.navigation.Camera;
import com.google.android.libraries.navigation.ListenableResultFuture;
import com.google.android.libraries.navigation.NavigationApi;
import com.google.android.libraries.navigation.Navigator;
import com.google.android.libraries.navigation.RoutingOptions;
import com.google.android.libraries.navigation.SimulationOptions;
import com.google.android.libraries.navigation.SupportNavigationFragment;
import com.google.android.libraries.navigation.Waypoint;

/**
 * An activity that displays a map and a navigation UI, guiding the user
 * from their current location to a single, given destination.
 */
public class NavigationActivitySingleDestination extends AppCompatActivity {

    private static final String TAG = NavigationActivitySingleDestination.class.getSimpleName();
    private Navigator mNavigator;
    private SupportNavigationFragment mNavFragment;
    private RoutingOptions mRoutingOptions;

    // Define the Sydney Opera House by specifying its place ID.
    private static final String SYDNEY_OPERA_HOUSE = "ChIJ3S-JXmauEmsRUcIaWtf4MzE";

    // Set fields for requesting location permission.
    private static final int PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION = 1;
    private boolean mLocationPermissionGranted;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize the Navigation SDK.
        initializeNavigationSdk();
    }

    /**
     * Starts the Navigation SDK and sets the camera to follow the device's location.
     * Calls the navigateToPlace() method when the navigator is ready.
     */
    private void initializeNavigationSdk() {
        /*
         * Request location permission, so that we can get the location of the
         * device. The result of the permission request is handled by a callback,
         * onRequestPermissionsResult.
         */
        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.");
            return;
        }

        // Get a navigator.
        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.");
                        mNavigator = navigator;
                        mNavFragment = (SupportNavigationFragment) getFragmentManager()
                                .findFragmentById(R.id.navigation_fragment);

                        // Set the last digit of the car's license plate to get route restrictions
                        // in supported countries. (optional)
                        // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");

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

                        // Set the travel mode (DRIVING, WALKING, CYCLING, or TWO_WHEELER).
                        mRoutingOptions =  new RoutingOptions();
                        mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);

                        // Navigate to a place, specified by Place ID.
                        navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
                    }

                    /**
                     * 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.");
                                break;
                            case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                                displayMessage("Error loading Navigation SDK: User did not accept "
                                        + "the Navigation Terms of Use.");
                                break;
                            case NavigationApi.ErrorCode.NETWORK_ERROR:
                                displayMessage("Error loading Navigation SDK: Network error.");
                                break;
                            case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                                displayMessage("Error loading Navigation SDK: Location permission "
                                        + "is missing.");
                                break;
                            default:
                                displayMessage("Error loading Navigation SDK: " + errorCode);
                        }
                    }
                });
    }

    /**
     * Requests directions from the user's current location to a specific place (provided
     * by the Google Places API).
     */
    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

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

        // 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:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // 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.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

    /**
     * Handles the result of the request for location permissions.
     */
    @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;
                }
            }
        }
    }

    /**
     * Shows a message on screen and in the log. Used when something goes wrong.
     * @param errorMessage The message to display.
     */
    private void displayMessage(String errorMessage) {
        Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
        Log.d(TAG, errorMessage);
    }
}

Einer App ein UI-Element hinzufügen

In diesem Abschnitt werden zwei Möglichkeiten beschrieben, die interaktive Karte und die Benutzeroberfläche für die detaillierte Routenführung hinzuzufügen.

Navigationsfragment verwenden

SupportNavigationFragment ist die UI-Komponente, mit der die visuelle Ausgabe der Navigation angezeigt wird, einschließlich einer interaktiven Karte und detaillierter Routenführung. Sie können das Fragment in Ihrer XML-Layoutdatei wie hier 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.SupportNavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Alternativ kannst du das Fragment wie in der Android-Dokumentation beschrieben programmatisch mithilfe von FragmentActivity.getSupportFragmentManager() erstellen.

Navigationsansicht verwenden

Als Alternative zu einem Fragment ist die UI-Komponente zum Anzeigen einer Karte für die Navigation auch als NavigationView verfügbar.

Berechtigung zur Standortermittlung anfordern

In diesem Abschnitt wird erläutert, wie Sie eine detaillierte Berechtigung zur Standortermittlung anfordern. Weitere Informationen findest du 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.navsdksingledestination">
       <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 zu verweigern. 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.");
       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

Die Klasse NavigationApi bietet eine Initialisierungslogik, mit der deine App zur Verwendung der Google-Navigation autorisiert wird. In diesem Abschnitt werden die Initialisierung des Navigators und einige weitere Konfigurationen beschrieben, die du für deine App aktivieren kannst:

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

2. Optional. Die App muss so konfiguriert sein, dass Benachrichtigungen zu Wegbeschreibungen und Hintergrunddienste heruntergefahren werden, wenn der Nutzer die App auf seinem Gerät schließt. Diese Wahl hängt von Ihrem Geschäftsmodell ab. Sie können das Standardverhalten des Navigators verwenden, bei dem weiterhin Wegbeschreibungen und Standortaktualisierungen angezeigt werden, auch wenn die App geschlossen wird. Wenn du stattdessen die Navigation und Standortaktualisierungen beenden möchtest, wenn der Endnutzer die App geschlossen hat, verwendest du diese Konfiguration.

3. Optional. Straßeneinschränkungen in unterstützten Ländern aktivieren. Legen Sie die letzte Ziffer des Kfz-Kennzeichens fest. Dieser Aufruf muss nur einmal ausgeführt werden: Bei nachfolgenden Routenanfragen wird er weiterhin verwendet. Dieser Aufruf funktioniert nur in unterstützten Regionen. Siehe Countries and regions supported for two-wheeled vehicles.

   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.");
                   mNavigator = navigator;
                   mNavFragment = (NavigationFragment) getFragmentManager()
                           .findFragmentById(R.id.navigation_fragment);
   
                   // Optional. Disable the guidance notifications and shut down the app
                   // and background service when the user closes the app.
                   // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)
   
                   // Optional. Set the last digit of the car's license plate to get
                   // route restrictions for supported countries.
                   // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");
   
                   // Set the camera to follow the device location with 'TILTED' driving view.
                   mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);
   
                   // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI).
                   mRoutingOptions = new RoutingOptions();
                   mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);
   
                   // Navigate to a place, specified by Place ID.
                   navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
               }
   
               /**
                * 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.");
                           break;
                       case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                           displayMessage("Error loading Navigation SDK: User did not accept "
                                   + "the Navigation Terms of Use.");
                           break;
                       case NavigationApi.ErrorCode.NETWORK_ERROR:
                           displayMessage("Error loading Navigation SDK: Network error.");
                           break;
                       case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                           displayMessage("Error loading Navigation SDK: Location permission "
                                   + "is missing.");
                           break;
                       default:
                           displayMessage("Error loading Navigation SDK: " + errorCode);
                   }
               }
           });
   

Ziel festlegen

Die Klasse Navigator bietet die Kontrolle über das Konfigurieren, Starten und Beenden einer Navigation.

Legen Sie mit dem Navigator aus dem vorherigen Abschnitt ein Ziel Waypoint für diese Fahrt fest. Nach der Berechnung einer Route werden im SupportNavigationFragment eine Polylinie für die Route auf der Karte und eine Markierung am Zielort angezeigt.

    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

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

        // 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:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // 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.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

App erstellen und ausführen

1. Verbinden Sie ein Android-Gerät mit Ihrem Computer. Folgen Sie der Anleitung in Android Studio zum Ausführen von Apps auf einem Hardwaregerät. Alternativ können Sie ein virtuelles Gerät mit dem Android Virtual Device (AVD) Manager 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 TermsAndConditionsCheckOption.
• Um die Navigationsqualität und die Genauigkeit der voraussichtlichen Ankunftszeit erheblich zu verbessern, sollten Sie zum Initialisieren eines Wegpunkts Orts-IDs anstelle von Breiten- und Längengradkoordinaten verwenden.
• In diesem Beispiel wird der Ziel-Wegpunkt von einer bestimmten Orts-ID für das Opernhaus von Sydney abgeleitet. Sie können die Orts-ID-Suche verwenden, um Orts-IDs für andere bestimmte Orte abzurufen.