Tek bir hedef rotasında gezinme

Uyarı: fromLatLng() ve fromPlaceId() kullanımdan kaldırılmıştır ancak daha fazla güncelleme yapılmadan kullanılabilir durumda kalacaktır. Yeni Waypoint.Builder'e geçmenizi öneririz.

Android için Navigasyon SDK'sını kullanarak uygulamanızda rota çizmek için bu kılavuzu inceleyin. Bu kılavuzda, Projenizi oluşturma bölümünde açıklandığı gibi Navigation SDK'yı uygulamanıza entegre ettiğiniz varsayılmaktadır.

Özet

1. Uygulamanıza gezinme parçası veya gezinme görünümü olarak bir kullanıcı arayüzü öğesi ekleyin. Bu kullanıcı arayüzü öğesi, etkinliğinize etkileşimli haritayı ve adım adım rota kullanıcı arayüzünü ekler.
2. Konum izinleri isteyin. Uygulamanız, cihazın konumunu belirlemek için konum izni istemelidir.
3. NavigationApi sınıfını kullanarak SDK'yı başlatın.

4. Navigator sınıfını kullanarak bir hedef belirleyin ve adım adım rotayı kontrol edin. Bu işlem üç adımdan oluşur:

   • setDestination() kullanarak hedefi ayarlayın.
   • startGuidance() ile navigasyonu başlatın.
   • Uygulamanızı test etmek, hatalarını ayıklamak ve göstermek için rota boyunca aracın ilerlemesini simüle etmek üzere getSimulator() kullanın.

5. Uygulamanızı derleyip çalıştırın.

Kodu göster

Tek hedefli gezinme etkinliği için Java kodunu göster veya gizle.

package com.example.navsdksingledestination;

import android.content.pm.PackageManager;
import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import com.google.android.gms.maps.GoogleMap.CameraPerspective;
import com.google.android.libraries.navigation.AudioGuidanceSettings;
import com.google.android.libraries.navigation.ListenableResultFuture;
import com.google.android.libraries.navigation.NavigationApi;
import com.google.android.libraries.navigation.NavigationFragment;
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.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 NavigationFragment 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 =
                (NavigationFragment)
                    getSupportFragmentManager().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.getMapAsync(
                googleMap -> googleMap.followMyLocation(CameraPerspective.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).
                AudioGuidanceSettings audioSettings =
                    AudioGuidanceSettings.builder()
                        .setGuidanceMode(
                            AudioGuidanceSettings.GuidanceMode.VOICE_ALERTS_AND_GUIDANCE)
                        .build();
                mNavigator.setAudioGuidanceSettings(audioSettings);

                // 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;
              case ROUTING_TIMEOUT:
                displayMessage("Error starting navigation: Routing timed out.");
                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);
  }
}

Uygulamanıza kullanıcı arayüzü öğesi ekleme

Bu bölümde, adım adım rotayı görüntülemek için etkileşimli haritayı ve kullanıcı arayüzünü eklemenin iki yolu açıklanmaktadır. Çoğu durumda, NavigationView ile doğrudan etkileşim kurmak yerine NavigationView için bir sarmalayıcı olan NavigationFragment kullanmanızı öneririz. Daha fazla bilgi için Navigasyon haritası etkileşimiyle ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

Not: SupportNavigationFragment, Navigation SDK 8.0.0 sürümünde kullanımdan kaldırılmıştır. Mevcut kodu güncelliyorsanız NavigationFragment'a güncelleme başlıklı makaleyi inceleyin.

Gezinme parçası kullanma

NavigationFragment, etkileşimli bir harita ve adım adım yol tarifleri de dahil olmak üzere navigasyonun görsel çıkışını gösteren kullanıcı arayüzü bileşenidir. Parçayı XML düzen dosyanızda burada gösterildiği gibi tanımlayabilirsiniz:

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

Alternatif olarak, Android belgelerinde açıklandığı gibi FragmentActivity.getSupportFragmentManager() kullanarak parçayı programatik olarak oluşturabilirsiniz.

Gezinme görünümü kullanma

Parçaya alternatif olarak, navigasyon için harita gösteren kullanıcı arayüzü bileşeni NavigationView olarak da kullanılabilir.

Dikkat: NavigationView sınıf açıklamasının üst kısmındaki kılavuzu, özellikle de yaşam döngüsü yöntemlerini görünümü içeren etkinlik veya parçadan doğru şekilde yönlendirme ve çağırma ile ilgili tavsiyeleri okuduğunuzdan emin olun.

Konum izni iste

Bu bölümde, tam konum izninin nasıl isteneceğini gösterilmektedir. Daha fazla bilgi için Android izinleri kılavuzunu inceleyin.

1. İzni, Android manifest dosyanızdaki <manifest> öğesinin alt öğesi olarak ekleyin:

   <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. Uygulamanızda çalışma zamanında istenen izinleri talep ederek kullanıcıya konum izni verme veya reddetme fırsatı sunun. Aşağıdaki kod, kullanıcının tam konum izni verip vermediğini kontrol eder. Yoksa izin ister:

       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. İzin isteğinin sonucunu işlemek için onRequestPermissionsResult() geri çağırma işlevini geçersiz kılın:

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

Gezinme SDK'sını ilk kullanıma hazırlama

NavigationApi sınıfı, uygulamanızı Google navigasyonu kullanma konusunda yetkilendiren başlatma mantığı sağlar. Bu bölümde, navigasyon aracının nasıl ilk kullanıma hazırlanacağı ve uygulamanız için etkinleştirebileceğiniz diğer bazı yapılandırmalar açıklanmaktadır:

1. Navigation SDK'yı ilk kullanıma hazırlayın ve navigasyon hazır olduğunda navigasyonu başlatmak için onNavigatorReady() geri çağırma işlevini geçersiz kılın.

2. İsteğe bağlı: Uygulamayı, kullanıcı uygulamayı cihazından kapattığında rehberlik bildirimleri ve arka plan hizmetleri kapanacak şekilde yapılandırın. Bu seçim, iş modelinize bağlıdır. Uygulama kapatıldığında bile dönüş talimatlarını ve konum güncellemelerini göstermeye devam eden varsayılan navigasyon davranışını kullanmak isteyebilirsiniz. Son kullanıcı uygulamayı kapattığında navigasyon ve konum güncellemelerini kapatmak istiyorsanız bu yapılandırmayı kullanırsınız.

3. İsteğe bağlı: Desteklenen ülkelerde yol kısıtlamalarını etkinleştirin. Plakanın son hanesini ayarlayın. Bu çağrının yalnızca bir kez yapılması gerekir. Sonraki yol tarifi istekleri bu çağrıyı kullanmaya devam eder. Bu çağrı yalnızca desteklenen bölgelerde çalışır. Navigation SDK'nın desteklendiği ülkeler listesine bakın.

       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) getSupportFragmentManager()
                               .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);
                       }
                   }
               });
   

Hedef belirleme

Navigator sınıfı, navigasyon yolculuğunu yapılandırma, başlatma ve durdurma üzerinde kontrol sağlar.

Önceki bölümde elde edilen Navigator değerini kullanarak bu yolculuk için bir hedef Waypoint ayarlayın. Yol tarifleri hesaplandıktan sonra NavigationFragment, haritada rotayı temsil eden bir çoklu çizgi ve varış noktasında bir işaretçi gösterir.

```none
    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).
                                AudioGuidanceSettings audioSettings =
                                        AudioGuidanceSettings.builder()
                                                .setGuidanceMode(
                                                        AudioGuidanceSettings.GuidanceMode
                                                                .VOICE_ALERTS_AND_GUIDANCE)
                                                .build();
                                mNavigator.setAudioGuidanceSettings(audioSettings);

                                // 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;
                            case ROUTING_TIMEOUT:
                                displayMessage("Error starting navigation: Routing timed out.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }
```

Sesli rehberliği yapılandırma

Sesli rehberlik ayarlarını (rehberlik modu ve ses seviyesi dahil) düzenlemek için navigasyon cihazına bir AudioGuidanceSettings nesnesi iletin.

Navigasyon, son kaydedilen ayarları kullanır veya varsayılan olarak normal ses seviyesine ve sesli uyarılara geçer.

Aşağıdaki örnekte, navigasyon cihazının düşük ses seviyesi kullanacak ve hem sesli uyarıları hem de adım adım yol tarifini etkinleştirecek şekilde nasıl yapılandırılacağı gösterilmektedir:

// Configure audio guidance settings.
AudioGuidanceSettings audioSettings = AudioGuidanceSettings.builder()
        .setGuidanceMode(AudioGuidanceSettings.GuidanceMode.VOICE_ALERTS_AND_GUIDANCE)
        .setVolumeLevel(AudioGuidanceSettings.VolumeLevel.LOW)
        .build();

mNavigator.setAudioGuidanceSettings(audioSettings);

Uygulamanızı derleyip çalıştırma

1. Android cihazınızı bilgisayarınıza bağlayın. Uygulamaları donanım cihazında çalıştırma ile ilgili Android Studio talimatlarını uygulayın. Alternatif olarak, Android Sanal Cihazı (AVD) Yöneticisi'ni kullanarak sanal cihaz yapılandırabilirsiniz. Emülatör seçerken Google API'lerini içeren bir görüntü seçtiğinizden emin olun.
2. Android Studio'da Run (Çalıştır) menü seçeneğini veya Run'ı (Çalıştır) tıklayın. İstendiğinde bir cihaz seçin.

Daha iyi bir kullanıcı deneyimi için ipuçları

• Navigasyonun kullanılabilir hale gelmesi için kullanıcının Google Navigasyon Hizmet Şartları'nı kabul etmesi gerekir. Bu kabul yalnızca bir kez gereklidir. Varsayılan olarak SDK, gezinme aracı ilk kez çağrıldığında kabul isteminde bulunur. İsterseniz Gezinme Hizmet Şartları iletişim kutusunu, uygulamanızın kullanıcı deneyimi akışının erken bir aşamasında (ör. kaydolma veya giriş yapma sırasında) TermsAndConditionsCheckOption kullanarak tetikleyebilirsiniz.
• Navigasyon kalitesini ve TVS doğruluğunu önemli ölçüde artırmak için ara nokta başlatırken enlem/boylam koordinatları yerine yer kimliklerini kullanın.
• Bu örnek, hedef ara noktayı Sidney Opera Binası'nın belirli bir yer kimliğinden alır. Diğer belirli konumların yer kimliklerini almak için yer kimliği bulma aracını kullanabilirsiniz.