By integrating the Navigation SDK for Android, your app can go beyond linking
to an external map view. With Google Maps navigation, your app can offer dynamic
retrieval and single-look reporting of data about a user's journey. This guide
explains how to run the Navigation SDK demo apps, which
are available on GitHub.

## Get ready

To get started with the Navigation SDK, be sure to have
the following items.

- An API key provisioned for use with Navigation SDK. See [Using API Keys](https://developers.google.com/maps/documentation/navigation/android-sdk/get-api-key) for more information about creating and restricting keys.
- The SDK artifact. Verify that your [project is configured](https://developers.google.com/maps/documentation/navigation/android-sdk/set-up-project#using_maven_for_v45_and_later_recommended) to use Maven for the Navigation SDK.
- One or more of the [demo apps](https://developers.google.com/maps/documentation/navigation/android-sdk/try-demo#get_the_demo_apps).
- [Android Studio](https://developer.android.com/studio/intro/), the recommended development environment for building an app with the Navigation SDK.

This documentation is designed for people familiar with Android development and
object-oriented programming concepts. You should also be familiar with Google
Maps from a user's point of view.

> [!NOTE]
> **Note:** If your app already uses the [Maps SDK](https://developers.google.com/maps/documentation/android-sdk), the Navigation SDK replaces the Maps SDK for both map layer and navigation features. You can't use the Navigation SDK and Maps SDK in the same app.

### Get the demo apps

Google provides two apps to help you understand what the
Navigation SDK offers on top of the
Google Maps APIs, depending on your level of experience.
Developers familiar with the Google Maps APIs
can focus their attention on the GoogleNavigation demo. Developers new to both
projects will find both apps helpful.

As of Navigation SDK for Android v4.1, the following demo apps are both
available on [GitHub](https://github.com/googlemaps-samples/android-navigation-samples) to download.

- **GoogleNavigation demo** : Showcases the integration of API behaviors and
  views as they pertain to the user's experience *while in a guided-navigation
  session*.

- **GoogleMap demo** : showcases individual behaviors of the [`GoogleMap`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/GoogleMap)
  interface to customize the feel and presentation of maps.

## The GoogleNavigation demo

The latest GoogleNavigation demo is available on
[GitHub](https://github.com/googlemaps-samples/android-navigation-samples).

### Build

1. In **Android Studio**, import the demo app and allow Gradle to run.

   > [!NOTE]
   > **Note:** The app fails to load the map until you update `local.defaults.properties` with the provisioned API key.

2. Open `local.defaults.properties` and update the value of the `MAPS_API_KEY`
   property:

         MAPS_API_KEY=YOUR_API_KEY

3. Click **build** and examine the SDK implementation details.

   - In the Java class, note the implementation code.

   - In the layout XML, note the layout design and text.

   - In the `build.gradle` file, note the SDK in the dependencies.

See the [Secrets Gradle
plugin](https://developers.google.com/maps/documentation/android-sdk/secrets-gradle-plugin)
documentation for more information on how the API key is added to the manifest.

### Run

1. Connect an Android device to your computer or use an emulator.

   - **Android device** ---Refer to the [instructions](https://developer.android.com/studio/run/device.html) to enable developer options on your Android device and configure your system to detect the device.
   - **Emulator** ---Use the [Android Virtual Device (AVD)
     Manager](https://developer.android.com/studio/run/managing-avds.html) to configure a virtual device. When choosing an emulator, make sure you pick an image that includes the Google APIs.
2. In **Android Studio** , click the **Run** menu option (or the play button
   icon); and then choose a deployment target.

When built and launched, the app presents the user with a landing page of a list
of options.

### NavViewActivity and NavFragmentActivity options

**New adopters of the NavSDK will likely find these two options to be the most
useful.**

![](https://developers.google.com/static/maps/documentation/navigation/android-sdk/images/nav-api.png)

**Option 1** : `NavViewActivity` showcases behaviors using the [`NavigationView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationView)
in conjunction with the
[`Navigator`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/Navigator).

**Option 2** : The second option, titled `NavFragmentActivity`, showcases
behaviors using the
[`NavigationFragment`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationFragment)
alongside the
[`Navigator`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/Navigator).

> [!NOTE]
> **Note:** In most cases, we recommend using [`NavigationFragment`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationFragment), which is a wrapper for [`NavigationView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationView), instead of interacting directly with `NavigationView`. For more information, see [Navigation map interaction best practices](https://developers.google.com/maps/documentation/navigation/android-sdk/nav-map-interactions-best-practices).

When you click one of these options, you'll be presented with the following:

- the navigation UI
- a "Set Destination" button in the app's menu
- an overlay that you can interact with to dynamically invoke methods on the API
- an overflow menu with more options

To get started, click **Set Destination** and pick an address. The app then
simulates a trip from your current location to that address. Use the control
panels overlay to see what happens when you call an API. For example,
click **View Methods** to try forcing the SDK into night-mode to see what it
looks like.

### SwappingMapAndNavActivity option

> [!NOTE]
> **Note:** This option assists you in your transition from v1 to v4. We encourage using `NavigationView` exclusively where possible, but provide this as an example for how to use both hand-in-hand.

The `SwappingMapAndNavActivity` showcases the following common patterns:

- displaying a [`MapView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/MapView)
- swapping to a [`NavigationView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationView) when navigation begins
- returning to a [`MapView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/MapView) when navigation ends

## The GoogleMap demo

The latest GoogleNavigation demo is available on
[GitHub](https://github.com/googlemaps-samples/android-navigation-samples).

> [!NOTE]
> **Note:** For more information about interacting with the `GoogleMap` object in your app, see [`GoogleMap` interaction best
> practices](https://developers.google.com/maps/documentation/navigation/android-sdk/googlemap-interactions-best-practices).

### Build

1. In **Android Studio**, import the demo app and allow Gradle to run.

   > [!NOTE]
   > **Note:** The app fails to load the map until you update `local.defaults.properties` with the provisioned API key.

2. Open `local.defaults.properties` and update the value of the `MAPS_API_KEY`
   property:

         MAPS_API_KEY=YOUR_API_KEY

3. Click **build** and examine the SDK implementation details.

   - In the Java class, note the implementation code.

   - In the layout XML, note the layout design and text.

   - In the `build.gradle` file, note the SDK in the dependencies.

For more information about how the API key is added to the manifest, see the
[Secrets Gradle
plugin](https://developers.google.com/maps/documentation/android-sdk/secrets-gradle-plugin).

### Run

![](https://developers.google.com/static/maps/documentation/navigation/android-sdk/images/googlemap_demo_landing_screen.png)

1. Connect an Android device to your computer or use an emulator.

   - **Android device** Refer to the [instructions](https://developer.android.com/studio/run/device.html) to enable developer options on your Android device and configure your system to detect the device.
   - **Emulator** Use the [Android Virtual Device (AVD) Manager](https://developer.android.com/studio/run/managing-avds.html) to configure a virtual device. When choosing an emulator, make sure you pick an image that includes the Google APIs.
2. In **Android Studio** , click the **Run** menu option (or the play button
   icon); and then choose a deployment target.

When built and launched, the app presents the user with a landing page of a list
of demos.

![](https://developers.google.com/static/maps/documentation/navigation/android-sdk/images/googlemap_basic_demo.png)

This presentation pattern and the corresponding structure of the source code
should be familiar to users of the Google Maps SDK demos. This is because the
GoogleMap demo is designed to be similar to the [Maps API demo
app](https://developers.google.com/maps/documentation/android-sdk/code-samples). The primary
difference is that the Navigation SDK demo lets the user choose which view class
they'd like to test-run a demo on:
[`NavigationView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationView)
or
[`MapView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/MapView),
where applicable.

Google generally encourages adopters to use the
[`NavigationView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/libraries/navigation/NavigationView).
This demo provides the flexibility to try these behaviors on both versions in
our demo app and choose whichever works for you. For example, it may still be
necessary to use a `MapView` in situations where you are using a third-party
library that expects to interact with that class.

> [!IMPORTANT]
> **Important:** The [`MapView`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/MapView), [`MapFragment`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/MapFragment) and [`SupportMapFragment`](https://developers.google.com/maps/documentation/navigation/android-sdk/reference/com/google/android/gms/maps/SupportMapFragment) classes require that devices have the Google Play services application installed. If you start a fresh emulator, or factory reset a very old device, the Android image may come with a very stale Google Play services preinstalled. In such cases, you'll have to wait for it to automatically pull a newer version, or manually update Play services through the Google Play Store.