پیمایش مسیر چندمقصدی

توجه: fromLatLng() و fromPlaceId() منسوخ شده‌اند، اما بدون به‌روزرسانی‌های بیشتر دردسترس خواهند بود. توصیه می‌کنیم به Waypoint.Builder جدید منتقل شوید.

این راهنما را دنبال کنید تا بااستفاده از Navigation SDK for Android، مسیری را در برنامه‌تان به چندین مقصد (که نقطه‌مسیر نیز نامیده می‌شود) ترسیم کنید. می‌توانید حداکثر ۲۵ نقطه‌مسیر، ازجمله مقصد نهایی، تنظیم کنید.

نمای کلی

1. همان‌طور که در راه‌اندازی پروژه شرح داده شده است، Navigation SDK را در برنامه‌تان ادغام کنید.
2. NavigationFragment یا NavigationView را به برنامه‌تان اضافه کنید. این عنصر میانای کاربر نقشه تعاملی و میانای کاربر ناوبری گام‌به‌گام را به فعالیتتان اضافه می‌کند.
3. از کلاس NavigationApi برای مقداردهی اولیه کیت توسعه نرم‌افزار استفاده کنید.

4. Navigator را برای کنترل ناوبری گام‌به‌گام تعریف کنید:

   • بااستفاده از setDestinations مقصد اضافه کنید.
   • شروع ناوبری با startGuidance.
   • از getSimulator برای شبیه‌سازی پیشرفت خودرو درطول مسیر، برای آزمایش، اشکال‌زدایی، و نمایش برنامه‌تان استفاده کنید.

5. برنامه‌تان را بسازید و اجرا کنید.

دیدن کد

نمایش/پنهان کردن کد Java برای فعالیت پیمایش.

package com.example.navsdkmultidestination;

import android.content.pm.PackageManager;
import android.location.Location;
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.ArrivalEvent;
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.RoadSnappedLocationProvider;
import com.google.android.libraries.navigation.SimulationOptions;
import com.google.android.libraries.navigation.TimeAndDistance;
import com.google.android.libraries.navigation.Waypoint;
import java.util.ArrayList;
import java.util.List;

/**
 * An activity that displays a map and a navigation UI, guiding the user from their current location
 * to multiple destinations, also known as waypoints.
 */
public class NavigationActivityMultiDestination extends AppCompatActivity {

  private static final String TAG = NavigationActivityMultiDestination.class.getSimpleName();
  private static final String DISPLAY_BOTH = "both";
  private static final String DISPLAY_TOAST = "toast";
  private static final String DISPLAY_LOG = "log";

  private Navigator mNavigator;
  private RoadSnappedLocationProvider mRoadSnappedLocationProvider;
  private NavigationFragment mNavFragment;
  private final List<Waypoint> mWaypoints = new ArrayList<>();

  private Navigator.ArrivalListener mArrivalListener;
  private Navigator.RouteChangedListener mRouteChangedListener;
  private Navigator.RemainingTimeOrDistanceChangedListener mRemainingTimeOrDistanceChangedListener;
  private RoadSnappedLocationProvider.LocationListener mLocationListener;

  private Bundle mSavedInstanceState;
  private static final String KEY_JOURNEY_IN_PROGRESS = "journey_in_progress";
  private boolean mJourneyInProgress = false;

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

  /**
   * Sets up the navigator when the activity is created.
   *
   * @param savedInstanceState The activity state bundle.
   */
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Save the navigator state, used to determine whether a journey is in progress.
    mSavedInstanceState = savedInstanceState;
    if (mSavedInstanceState != null && mSavedInstanceState.containsKey(KEY_JOURNEY_IN_PROGRESS)) {
      mJourneyInProgress = (mSavedInstanceState.getInt(KEY_JOURNEY_IN_PROGRESS) != 0);
    }

    setContentView(R.layout.activity_main);

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

  /** Releases navigation listeners when the activity is destroyed. */
  @Override
  protected void onDestroy() {
    super.onDestroy();

    if ((mJourneyInProgress) && (this.isFinishing())) {
      mNavigator.removeArrivalListener(mArrivalListener);
      mNavigator.removeRouteChangedListener(mRouteChangedListener);
      mNavigator.removeRemainingTimeOrDistanceChangedListener(
          mRemainingTimeOrDistanceChangedListener);
      if (mRoadSnappedLocationProvider != null) {
        mRoadSnappedLocationProvider.removeLocationListener(mLocationListener);
      }
      displayMessage("OnDestroy: Released navigation listeners.", DISPLAY_LOG);
    }
  }

  /** Saves the state of the app when the activity is paused. */
  @Override
  protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);
    if (mJourneyInProgress) {
      outState.putInt(KEY_JOURNEY_IN_PROGRESS, 1);
    } else {
      outState.putInt(KEY_JOURNEY_IN_PROGRESS, 0);
    }
  }

  /**
   * Starts the Navigation SDK and sets the camera to follow the device's location. Calls the
   * navigateToPlaces() 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.",
          DISPLAY_BOTH);
      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.", DISPLAY_BOTH);
            mNavigator = navigator;

            mNavFragment =
                (NavigationFragment)
                    getSupportFragmentManager().findFragmentById(R.id.navigation_fragment);

            // Set the camera to follow the device location with 'TILTED' driving view.
            mNavFragment.getMapAsync(
                googleMap -> googleMap.followMyLocation(CameraPerspective.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.");
                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);
            }
          }
        });
  }

  /** Requests directions from the user's current location to a list of waypoints. */
  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).
                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.", 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;
              case ROUTING_TIMEOUT:
                displayMessage("Error starting navigation: Routing timed out.", DISPLAY_BOTH);
                break;
              default:
                displayMessage("Error starting navigation: " + String.valueOf(code), DISPLAY_BOTH);
            }
          }
        });
  }

  /**
   * Creates a waypoint from a given place ID and title.
   *
   * @param placeId The ID of the place to be converted to a waypoint.
   * @param title A descriptive title for the waypoint.
   */
  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);
    }
  }

  /** Displays the calculated travel time and distance to each waypoint. */
  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);
  }

  /**
   * Registers some event listeners to show a message and take other necessary steps when specific
   * navigation events occur.
   */
  private void registerNavigationListeners() {
    mArrivalListener =
        new Navigator.ArrivalListener() {
          @Override
          public void onArrival(ArrivalEvent arrivalEvent) {
            displayMessage(
                "onArrival: You've arrived at a waypoint: "
                    + mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_BOTH);
            // Start turn-by-turn guidance for the next leg of the route.
            if (arrivalEvent.isFinalDestination()) {
              displayMessage("onArrival: You've arrived at the final destination.", DISPLAY_BOTH);
            } else {
              mNavigator.continueToNextDestination();
              mNavigator.startGuidance();
            }
          }
        };
    // Listens for arrival at a waypoint.
    mNavigator.addArrivalListener(mArrivalListener);

    mRouteChangedListener =
        new Navigator.RouteChangedListener() {
          @Override
          public void onRouteChanged() {
            displayMessage(
                "onRouteChanged: The driver's route has changed. Current waypoint: "
                    + mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_LOG);
          }
        };
    // Listens for changes in the route.
    mNavigator.addRouteChangedListener(mRouteChangedListener);

    // Listens for road-snapped location updates.
    mRoadSnappedLocationProvider = NavigationApi.getRoadSnappedLocationProvider(getApplication());
    mLocationListener =
        new RoadSnappedLocationProvider.LocationListener() {
          @Override
          public void onLocationChanged(Location location) {
            displayMessage(
                "onLocationUpdated: Navigation engine has provided a new"
                    + " road-snapped location: "
                    + location.toString(),
                DISPLAY_LOG);
          }

          @Override
          public void onRawLocationUpdate(Location location) {
            displayMessage(
                "onLocationUpdated: Navigation engine has provided a new"
                    + " raw location: "
                    + location.toString(),
                DISPLAY_LOG);
          }
        };
    if (mRoadSnappedLocationProvider != null) {
      mRoadSnappedLocationProvider.addLocationListener(mLocationListener);
    } else {
      displayMessage("ERROR: Failed to get a location provider", DISPLAY_LOG);
    }

    mRemainingTimeOrDistanceChangedListener =
        new Navigator.RemainingTimeOrDistanceChangedListener() {
          @Override
          public void onRemainingTimeOrDistanceChanged() {
            displayMessage(
                "onRemainingTimeOrDistanceChanged: Time or distance estimate" + " has changed.",
                DISPLAY_LOG);
          }
        };
    // Listens for changes in time or distance.
    mNavigator.addRemainingTimeOrDistanceChangedListener(
        60, 100, mRemainingTimeOrDistanceChangedListener);
  }

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

افزودن قطعه پیمایش

NavigationFragment مؤلفه میانای کاربر است که خروجی دیداری ناوبری را نمایش می‌دهد، ازجمله نقشه تعاملی و مسیرهای گام‌به‌گام. می‌توانید قطعه را در فایل چیدمان XML خود به‌صورت زیر اعلام کنید:

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

یا می‌توانید قطعه را به‌صورت برنامه‌نویسی‌شده، همان‌طور که در سند Android شرح داده شده است، بااستفاده از FragmentActivity.getSupportFragmentManager() بسازید.

توجه: SupportNavigationFragment در کیت توسعه نرم‌افزار ناوبری نسخه ۸.۰.۰ منسوخ شده است. اگر کد موجود را به‌روز می‌کنید، به‌روزرسانی به NavigationFragment را ببینید.

به‌عنوان جایگزینی برای قطعه، مؤلفه واسط کاربر به‌صورت NavigationView نیز دردسترس است. در اکثر موارد، توصیه می‌کنیم به‌جای تعامل مستقیم با NavigationView، از NavigationFragment که پوششی برای NavigationView است استفاده کنید. برای اطلاعات بیشتر، روال‌های مطلوب تعامل با نقشه ناوبری را ببینید.

درخواست اجازه مکان

برنامه شما باید اجازه مکان را درخواست کند تا بتواند مکان دستگاه را تعیین کند.

این آموزش گام‌به‌گام کدی را که برای درخواست اجازه مکان دقیق نیاز دارید ارائه می‌دهد. برای جزئیات بیشتر، راهنمای اجازه‌های Android را ببینید.

1. اجازه را به‌عنوان فرزند عنصر <manifest> در مانیفست Android خود اضافه کنید:

       <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. اجازه‌های زمان اجرا را در برنامه‌تان درخواست کنید و به کاربر فرصت دهید اجازه مکان را مجاز یا رد کند. کد زیر بررسی می‌کند که آیا کاربر اجازه مکان دقیق را اعطا کرده است یا نه. اگر این‌طور نباشد، اجازه را درخواست می‌کند:

       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. فراخوانی برگشتی onRequestPermissionsResult را لغو کنید تا نتیجه درخواست اجازه را مدیریت کنید:

       @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 و پیکربندی سفر

کلاس NavigationApi منطق مقداردهی اولیه را ارائه می‌دهد که به برنامه شما اجازه می‌دهد از ناوبری Google استفاده کند. کلاس Navigator کنترل پیکربندی، شروع، و توقف سفر ناوبری را فراهم می‌کند.

1. یک روش کمکی برای نمایش پیام روی صفحه و در گزارش ایجاد کنید.

       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. کیت توسعه نرم‌افزار ناوبری را مقداردهی اولیه کنید و فراخوان برگشتی onNavigatorReady را لغو کنید تا وقتی ناوبری آماده شد، ناوبری شروع شود:

       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) getSupportFragmentManager()
                               .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. روشی برای ایجاد شیء Waypoint از شناسه و عنوان مکان داده‌شده اضافه کنید.

       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. روشی برای نمایش مدت سفر و مسافت محاسبه‌شده برای هر نقطه‌مسیر اضافه کنید.

       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. برای این سفر، حداکثر ۲۵ نقطه‌مسیر تنظیم کنید. پس‌از محاسبه مسیرها، NavigationFragment چندخطی‌ای را نمایش می‌دهد که نشان‌دهنده مسیر روی نقشه است و نشانگری در هر نقطه‌مسیر دارد.

   توجه: اگر از شناسه مکان‌هایی استفاده کنید که ناوبر نتواند برای آن‌ها مسیر ترسیم کند، ممکن است خطا دریافت کنید. برنامه نمونه در این آموزش از شناسه‌های جا برای نقطه‌مسیرها در استرالیا استفاده می‌کند. با نحوه دریافت شناسه‌های مختلف مکان آشنا شوید.

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

ساختن و اجرای برنامه

1. دستگاه Android را به رایانه وصل کنید. دستورالعمل‌ها را دنبال کنید تا گزینه‌های توسعه‌دهنده را در دستگاه Android خود فعال کنید و سیستم خود را برای شناسایی دستگاه پیکربندی کنید. (یا می‌توانید از مدیر دستگاه مجازی Android (AVD) برای پیکربندی دستگاه مجازی استفاده کنید. هنگام انتخاب شبیه‌ساز، مطمئن شوید تصویری را انتخاب می‌کنید که شامل Google APIs باشد.)
2. در Android Studio، روی گزینه منو اجرا (یا نماد دکمه پخش) کلیک کنید. دستگاهی را طبق درخواست انتخاب کنید.

نکاتی برای بهبود تجربه کاربری

• کاربر باید «شرایط خدمات Google Navigation» را بپذیرد تا ناوبری دردسترس قرار گیرد. این پذیرش فقط یک‌بار لازم است. به‌طور پیش‌فرض، کیت توسعه نرم‌افزار اولین باری که ناوبر فراخوانده می‌شود، درخواست پذیرش می‌کند. اگر ترجیح می‌دهید، می‌توانید کادر گفتگوی «شرایط خدمات ناوبری» را در نقطه‌ای اولیه در جریان تجربه کاربری برنامه‌تان، مثلاً درطول ثبت‌نام یا ورود به سیستم، بااستفاده از showTermsAndConditionsDialog راه‌اندازی کنید.
• اگر برای مقداردهی اولیه نقطه‌مسیر به‌جای مقصد طول/عرض جغرافیایی از شناسه جا استفاده کنید، کیفیت ناوبری و دقت زمان تخمینی رسیدن به‌طور قابل‌توجهی بهبود می‌یابد.

• این نمونه نقاط‌مسیر را از شناسه‌های مکان خاصی مشتق می‌کند. روش‌های دیگر برای دریافت شناسه مکان عبارت‌اند از:

• از یابنده شناسه مکان برای دریافت شناسه مکان برای مکان‌های خاص استفاده کنید.

• از Geocoding API برای پیدا کردن شناسه مکان برای نشانی داده‌شده استفاده کنید. Geocoding API درصورتی به‌خوبی کار می‌کند که نشانی‌های کامل و بدون ابهامی برای نقطه‌مسیرها داشته باشید. راهنمای روال‌های مطلوب زمین‌کدیابی را ببینید.

• از جستجوی نوشتار Places API برای پیدا کردن شناسه مکان برای نشانی داده‌شده استفاده کنید. اگر نشانی‌های ناقص یا مبهمی برای نقطه‌مسیرها دارید، Places API به‌خوبی کار می‌کند. راهنمای روال‌های مطلوب زمین‌کدیابی را ببینید.