Itinéraire vers une destination unique

Suivez ce guide pour tracer un itinéraire vers une destination unique dans votre application à l'aide du SDK Navigation pour Android.

Présentation

  1. Intégrez le SDK Navigation à votre application, comme décrit dans le guide de configuration.
  2. Ajoutez un NavigationFragment ou un NavigationView à votre application. Cet élément d'interface utilisateur ajoute la carte interactive et l'interface utilisateur de navigation détaillée à votre activité.
  3. Utilisez la classe NavigationApi pour initialiser le SDK.

  4. Définissez un Navigator pour contrôler la navigation détaillée:

    • Ajoutez une destination à l'aide de setDestination().
    • Démarrez la navigation avec startGuidance().
    • Utilisez getSimulator() pour simuler la progression du véhicule sur l'itinéraire afin de tester, déboguer et présenter votre application.

  5. Créez et exécutez votre application.

Voir le code

Ajouter un fragment de navigation

NavigationFragment est le composant d'interface utilisateur qui affiche la sortie visuelle de la navigation, y compris une carte interactive et des instructions de navigation détaillées. Vous pouvez déclarer le fragment dans votre fichier de mise en page XML, comme indiqué ci-dessous:

<?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"/>

Vous pouvez également construire le fragment de manière programmatique, comme décrit dans la documentation Android.

Pour les applications qui utilisent la version de support de Fragment, le SDK Navigation assure la compatibilité via SupportNavigationFragment. Ce fragment se comporte de manière identique à NavigationFragment. Vous pouvez le gérer programmatiquement à l'aide de FragmentActivity.getSupportFragmentManager().

Au lieu d'un fragment, le composant d'interface utilisateur est également disponible en tant que NavigationView. Veuillez prendre note des informations en haut de la description du cours, en particulier sur l'exigence de transfert des méthodes de cycle de vie.

Demander l'autorisation d'accéder à la position

Votre application doit demander l'autorisation d'accéder à la position pour déterminer la position de l'appareil.

Ce tutoriel fournit le code nécessaire pour demander une autorisation d'accéder à la position précise. Pour en savoir plus, consultez le guide sur les autorisations Android.

  1. Ajoutez l'autorisation en tant qu'enfant de l'élément <manifest> dans votre fichier manifeste Android:

    <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. Demandez les autorisations d'exécution dans votre application, en donnant à l'utilisateur la possibilité d'accorder ou de refuser l'autorisation d'accéder à la position. Le code suivant vérifie si l'utilisateur a accordé une autorisation d'accéder à la position précise. Si ce n'est pas le cas, il demande l'autorisation :

    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. Ignorez le rappel onRequestPermissionsResult() pour gérer le résultat de la demande d'autorisation:

    @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;
            }
        }
    }
}

Initialiser le SDK Navigation et configurer un parcours

La classe NavigationApi fournit une logique d'initialisation qui autorise votre application à utiliser la navigation Google. La classe Navigator permet de contrôler la configuration et le démarrage/l'arrêt d'un trajet de navigation.

  1. Initialisez le SDK Navigation et ignorez le rappel onNavigatorReady() pour lancer la navigation lorsque le navigateur est prêt.

  2. (Facultatif) Définissez le dernier chiffre de la plaque d'immatriculation pour activer les restrictions routières dans les pays où cette option est disponible (actuellement le Brésil et l'Indonésie). Si cet appel est utilisé pour d'autres codes pays, l'API l'ignorera. Cet appel ne doit être effectué qu'une seule fois. Les demandes d'itinéraire suivantes continueront de l'utiliser.

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

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

  3. À l'aide du Navigator obtenu ci-dessus, définissez un Waypoint de destination pour ce trajet. Après avoir calculé l'itinéraire, NavigationFragment affiche une polyligne représentant l'itinéraire sur la carte et un repère pour la destination.

    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));
                    }
                }
            });
}

Compiler et exécuter votre application

  1. Connectez un appareil Android à votre ordinateur. Suivez les instructions pour activer les options pour les développeurs sur votre appareil Android et configurer votre système afin qu'il détecte l'appareil. Vous pouvez également utiliser l'outil AVD (Android Virtual Device) Manager pour configurer un appareil virtuel. Lorsque vous choisissez un émulateur, assurez-vous de choisir une image qui inclut les API Google.)
  2. Dans Android Studio, cliquez sur l'option de menu Run (Exécuter) ou sur l'icône du bouton de lecture. Choisissez un appareil lorsque vous y êtes invité.

Conseils pour améliorer l'expérience utilisateur

  • L'utilisateur doit accepter les conditions d'utilisation de Google Navigation pour que la fonctionnalité de navigation soit disponible. Cette acceptation n'est requise qu'une seule fois. Par défaut, le SDK vous invite à accepter la demande la première fois que le navigateur est appelé. Si vous préférez, vous pouvez afficher la boîte de dialogue des conditions d'utilisation de la navigation à un stade précoce du flux d'expérience utilisateur de votre application, par exemple lors de l'inscription ou de la connexion, à l'aide de showTermsAndConditionsDialog().
  • La qualité de la navigation et la précision de l'heure d'arrivée prévue sont considérablement améliorées si vous utilisez des ID de lieu pour initialiser un point de cheminement plutôt qu'une destination de latitude/longitude.
  • Cet exemple extrait le point de cheminement de destination à partir d'un ID de lieu spécifique (pour l'opéra de Sydney). Vous pouvez utiliser l'outil de recherche d'ID de lieu pour obtenir des ID de lieu pour d'autres établissements spécifiques. Vous pouvez également offrir à l'utilisateur la possibilité de choisir une destination en ajoutant un sélecteur de lieu à votre application. Pour essayer un exemple fonctionnel du sélecteur de lieu avec le SDK Navigation, consultez l'application de démonstration décrite dans l'introduction.

Étape suivante

Découvrez comment accéder à plusieurs destinations en un seul parcours. Si votre contrat avec Google spécifie une facturation par transaction, configurez vos transactions facturables.