> [!IMPORTANT]
> **Important:** This guide pertains ONLY to projects that use Navigation SDK for Android versions 4.99 and earlier. If you have updated your project to version 5.0 or later, follow the [setup instructions](https://developers.google.com/maps/documentation/navigation/android-sdk/set-up-project) for the most recent package install, versions, and dependency details.

This guide lists the build configuration requirements for using the
Navigation SDK for Android. The instructions assume you have an Android IDE
installed and are familiar with Android development.

> [!WARNING]
> **Warning:** Beginning with Navigation SDK (Version 4.0), the API no longer supports Android KitKat or Lollipop (4.4-5.1).

## Minimum requirements for using Navigation SDK

These requirements apply to Navigation SDK for Android version 4.99 and earlier.

- A [Google Cloud console](https://console.cloud.google.com)

  project with the Navigation SDK enabled. For provisioning, ask your
  Google Maps Platform representative.
- Your app must target API level 30 or higher.

- To run an app built with the Navigation SDK, the Android device must
  have [Google Play
  services](https://developers.google.com/android/guides/overview) installed
  and enabled.

- [Attributions and licensing text](https://developers.google.com/maps/documentation/navigation/android-sdk/set-up-project-v4#include_the_required_attributions_in_your_app)
  must be added to the app.

## Set up your projects: Cloud console project and Android project

Before you can build or test an app, you need to create a
Cloud console project and add API key credentials. The project
must have provisioning to access the Navigation SDK. All keys within the
Cloud console project are granted the same access to the
Navigation SDK. A key can have more than one development project
associated with it. If you already have a console project, you can add a key to
your current project.

> [!IMPORTANT]
> **Information you need to set up a project**:
>
> - The name of your Google Maps Platform representative.
> - A name for your Cloud console project.
> - A name for your Android app development project which has a package name you need later.
> - The SHA-1 certificate fingerprint for your development machine.

**To set up**

1. In your favorite **web browser** , sign in to the **Cloud console** and create your [Cloud console](https://console.cloud.google.com) project.
2. In your **IDE**, such as Android Studio, create an Android app development project and note the package name.
3. Contact your Google Maps Platform representative to provide access to the Navigation SDK for your Cloud console project.
4. While on the **Cloud console dashboard** in your web browser, create credentials to generate an API key with restrictions.
5. On the **API key page** , click Android apps in the *Application
   restrictions* area.
6. Click **Add the package name and fingerprint**, and then enter the package name of your development project and the SHA-1 fingerprint for that key.
7. Click **Save**.

## Add the Navigation SDK to your project

The Navigation SDK is available using Maven, or as an [AAR
bundle](https://developer.android.com/studio/projects/android-library.html#aar-contents).
After you create your development project, you can integrate the SDK into it by
using one of the following approaches.

> [!IMPORTANT]
> **Important:** You should use Maven dependencies in your project to link the Navigation SDK for Android. The AAR bundle download won't be available in the future.

### Use Maven for Navigation SDK v4.5 and later (recommended)

The following uses the `google()` Maven repository, which is the simplest and
recommended way to add Navigation SDK to your project

> [!NOTE]
> **Note:** This approach is incompatible with some libraries that depend on Navigation SDK using the prior artifact ID. This includes releases of the Driver SDK v4.4 or earlier.

1. Add the following dependency to your Gradle or Maven configuration,
   substituting the `VERSION_NUMBER` placeholder for the
   version of Navigation SDK for Android.

   ### Gradle

   Add the following to your module-level `build.gradle`:

       dependencies {
       ...
       implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
       }

   If upgrading from the original Maven repository, note that the group and
   artifact names have changed, and the
   `com.google.cloud.artifactregistry.gradle-plugin` plugin is no longer
   necessary.

   And add the following to your top-level `build.gradle`:

       allprojects {
       ...
       // Required: you must exclude the Google Play service Maps SDK from
       // your transitive dependencies to make nsure there won't be
       // multiple copies of Google Maps SDK in your binary, as the Navigation
       // SDK already bundles the Google Maps SDK.
       configurations {
              implementation {
                  exclude group: 'com.google.android.gms', module: 'play-services-maps'
              }
       }
       }

   ### Maven

   Add the following to your `pom.xml`:

       <dependencies>
       ...
       <dependency>
            <groupId>com.google.android.libraries.navigation</groupId>
            <artifactId>navigation</artifactId>
            <version>VERSION_NUMBER</version>
       </dependency>
       </dependencies>

   If you have any dependencies that use the Maps SDK, you have to exclude the
   dependency in each declared dependency that relies on the Maps SDK.

       <dependencies>
       <dependency>
       <groupId>project.that.brings.in.maps</groupId>
       <artifactId>MapsConsumer</artifactId>
       <version>1.0</version>
            <exclusions>
              <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
              <exclusion>  <!-- declare the exclusion here -->
                <groupId>com.google.android.gms</groupId>
                <artifactId>play-services-maps</artifactId>
              </exclusion>
            </exclusions>
       </dependency>
       </dependencies>

### Use Maven for Navigation SDK prior to v4.5, or with Driver SDK

Navigation SDK continues to be available using the original Maven
repository through the remainder of the v4 versions. This is the same library
with all the same updates as the version above, and provides compatibility with
Driver SDK and other libraries during the transition.
Using this dependency requires logging into your cloud project using `gcloud`
when compiling.

1. Set up your environment to access Google's Maven repository as described in the [Prerequisites](https://developers.google.com/maps/documentation/transportation-logistics/on-demand-rides-deliveries-solution/trip-order-progress/consumer-sdk/consumer_sdk_quickstart_android#prerequisites) section of the Consumer SDK documentation. Access to the Navigation SDK is controlled through a workspace group.
2. Add the following dependency to your Gradle or Maven configuration,
   substituting the `VERSION_NUMBER` placeholder for the
   version of Navigation SDK.

   ### Gradle

   Add the following to your module-level `build.gradle`:

       dependencies {
       ...
       implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
       }

   And add the following to your top-level `build.gradle`:

       allprojects {
       ...
       // Required: you must exclude the Google Play service Maps SDK from
       // your transitive dependencies to make sure there won't be
       // multiple copies of Google Maps SDK in your binary, as the Navigation
       // SDK already bundles the Google Maps SDK.
       configurations {
               implementation {
                   exclude group: 'com.google.android.gms', module: 'play-services-maps'
               }
       }
       }

   ### Maven

   Add the following to your `pom.xml`:

       <dependencies>
       ...
       <dependency>
            <groupId>com.google.android.maps</groupId>
            <artifactId>navsdk</artifactId>
            <version>VERSION_NUMBER</version>
       </dependency>
       </dependencies>

   If you have any dependencies that use the Maps SDK, you have to exclude the
   dependency in each declared dependency that relies on the Maps SDK.

       <dependencies>
       <dependency>
       <groupId>project.that.brings.in.maps</groupId>
       <artifactId>MapsConsumer</artifactId>
       <version>1.0</version>
            <exclusions>
              <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
              <exclusion>  <!-- declare the exclusion here -->
                <groupId>com.google.android.gms</groupId>
                <artifactId>play-services-maps</artifactId>
              </exclusion>
            </exclusions>
       </dependency>
       </dependencies>

### Use a downloaded AAR bundle (not recommended)

The Navigation SDK is also available as an [AAR
bundle](https://developer.android.com/studio/projects/android-library.html#aar-contents).
After creating the development project, you can integrate the SDK. These
instructions assume the use of Android Studio for your IDE.

1. Download the latest version of the Navigation SDK from the [shared
   Google Drive](https://drive.google.com/drive/folders/1FLR7wtNgLlbn0nThbLMIMtoRzt4bGOwk) and extract it. If you don't have
   access, contact your representative.

2. In **Android Studio** , open a project and [add the **Google Play services**
   package](https://developer.android.com/studio/intro/update.html#sdk-manager)
   using the **SDK Manager**.

3. From the zip file directory, copy `libs/google_navigation_navmap.aar` into
   your project's `app/libs` directory.

4. Add the following to your module-level `build.gradle`:

       implementation(name: 'google_navigation_navmap', ext: 'aar')

   And add the following to your top-level `build.gradle`:

       allprojects {
          ...
          // Required: you must exclude the Google Play service Maps SDK from
          // your transitive dependencies to make sure there won't be
          // multiple copies of Google Maps SDK in your binary, as the Navigation
          // SDK already bundles the Google Maps SDK.
          configurations {
              implementation {
                  exclude group: 'com.google.android.gms', module: 'play-services-maps'
              }
          }
       }

## Configure the build

After you have created the project, you can configure the settings for a
successful build and use of the Navigation SDK.

### Update local properties

- In the **Gradle Scripts folder** , open the `local.properties` file and add `android.useDeprecatedNdk=true`.

### Update the Gradle build script

- Open the `build.gradle (Module:app)` file and use the following guidelines
  to update the settings to meet the requirements for Navigation SDK
  and consider setting the optimization options as well.

  **Required settings for Navigation SDK**
  1. Set `minSdkVersion` to 23 or above.
  2. Set `targetSdkVersion` to 30 or above.
  3. Add a `dexOptions` setting that increases the `javaMaxHeapSize`.
  4. Set the location for additional libraries.
  5. Add the `repositories` and `dependencies` for the Navigation SDK.
  6. Replace the version numbers in the dependencies with the latest available versions.

  **Optional settings to decrease build time**
  - Enable [code shrinking and resource shrinking](https://developer.android.com/studio/build/shrink-code.html) using R8/ProGuard to remove unused code and resources from dependencies. If the R8/ProGuard step takes too much time to run, consider enabling [multidex](https://developer.android.com/studio/build/multidex) for development work.
  - Reduce the number of language translations included in the build: Set `resConfigs` for one language during development. For the final build, set `resConfigs` for languages you actually use. By default, Gradle includes resource strings for all languages supported by the Navigation SDK.

Below is an example of the Gradle build script for the application. Check the
[sample apps](https://developers.google.com/maps/documentation/navigation/android-sdk/try-demo) for updated sets of dependencies, as the version of
Navigation SDK you are using may be slightly ahead or behind this
documentation.

    apply plugin: 'com.android.application'
    apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

    ext {
        androidxVersion = "1.0.0"
        lifecycle_version = "1.1.1"
    }

    android {
        compileSdkVersion 30
        buildToolsVersion '28.0.3'

        defaultConfig {
            applicationId "<your id>"
            // Navigation SDK supports SDK 23 and later.
            minSdkVersion 23
            targetSdkVersion 30
            versionCode 1
            versionName "1.0"
            // Set this to the languages you actually use, otherwise you'll include resource strings
            // for all languages supported by the Navigation SDK.
            resConfigs "en"
            multiDexEnabled true
        }

        dexOptions {
            // This increases the amount of memory available to the dexer. This is required to build
            // apps using the Navigation SDK.
            javaMaxHeapSize "4g"
        }
        buildTypes {
            // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
            // The configuration is included transitively by depending on the Navigation SDK.
            // If the ProGuard step takes too long, consider enabling multidex for development work
            // instead.
            all {
                minifyEnabled true
                proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
            }
        }
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
    }

    // This tells Gradle where to look to find additional libraries - in this case, the
    // google_navigation_navmap.aar file.
    repositories {
        flatDir {
            dirs 'libs'
        }
        google()

        // Required for accessing the Navigation SDK on Google's Maven repository.
        maven {
            url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
        }
    }

    dependencies {
        // Include the Google Navigation SDK
        implementation 'com.google.android.maps:navsdk:4.4.0'

        // The included AAR file under libs can be used instead of the Maven repository.
        // Uncomment the line below and comment out the previous dependency to use
        // the AAR file instead. Make sure that you add the AAR file to the libs directory.
        // implementation(name: 'google_navigation_navmap', ext: 'aar')

        // These dependencies are required for the Navigation SDK to function
        // properly at runtime.
        implementation 'org.chromium.net:cronet-fallback:69.3497.100'
        // Optional for Cronet users:
        // implementation 'org.chromium.net:cronet-api:69.3497.100'
        implementation 'androidx.appcompat:appcompat:${androidxVersion}'
        implementation 'androidx.cardview:cardview:${androidxVersion}'
        implementation 'com.google.android.material:material:${androidxVersion}'
        implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
        implementation 'androidx.preference:preference:${androidxVersion}'
        implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
        implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
        implementation 'com.github.bumptech.glide:glide:4.9.0'
        implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
        implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
        implementation 'com.android.support:multidex:1.0.3'
        implementation 'com.google.android.datatransport:transport-api:2.2.0'
        implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
        implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
        implementation 'joda-time:joda-time:2.9.9'
        annotationProcessor 'androidx.annotation:annotation:1.1.0'
        annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
    }

### Add the API key to your app

This section describes how to store your API key so that it can be securely
referenced by your app. You shouldn't check your API key into your version
control system, so we recommend storing it in a
`secrets.properties` file in the root directory of your project and
excluding that file from version control. For more information about Gradle
properties files, see
[Gradle properties files](https://developer.android.com/studio/build#properties-files).

To simplify this task, we recommend that you use the
[Secrets Gradle Plugin for Android](https://github.com/google/secrets-gradle-plugin).

To install the Secrets Gradle Plugin for Android and store your API key:

1. In Android Studio, open your top-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` block.

   ### Kotlin

   ```kotlin
   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }
   ```

   ### Groovy

   ```groovy
   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }
   ```
2. Open your module-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` element.

   ### Kotlin

   ```kotlin
   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }
   ```

   ### Groovy

   ```groovy
   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }
   ```
3. If you use Android Studio, [sync your
   project with Gradle](https://developer.android.com/studio/build#sync-files).
4. Open the `secrets.properties` file in your top-level directory, and then add the following code. Replace `YOUR_API_KEY` with your API key. Make sure to add `secrets.properties` to your `.gitignore` file (or otherwise exclude it from your version control system) so that you don't check your API key into version control.

   > [!NOTE]
   > **Note:** If the `secrets.properties` file doesn't exist, create it in the same folder as the `local.properties` file.

   ```
   MAPS_API_KEY=YOUR_API_KEY
   ```
5. Create the `local.defaults.properties` file in your top-level
   directory, the same folder as the `secrets.properties` file, and
   then add the following code.

   > [!NOTE]
   > **Note:** Enter the code as shown. Don't replace `DEFAULT_API_KEY` with your API key.

   ```
   MAPS_API_KEY=DEFAULT_API_KEY
   ```

   The purpose of this file is to provide a backup location for the API key
   if the `secrets.properties` file isn't found so that builds
   don't fail. This can happen if you clone the app from a version control
   system that omits `secrets.properties` and you haven't yet
   created a `secrets.properties` file locally to provide your API
   key.
6. You can either add the API key to your `AndroidManifest.xml` file or provide the API key programmatically.
   - Add your API key to `AndroidManifest.xml`:

     ```html
     <meta-data
         android:name="com.google.android.geo.API_KEY"
         android:value="${MAPS_API_KEY}" />
             
     ```

     **Note:**
     `com.google.android.geo.API_KEY` is the recommended metadata name
     for the API key. A key with this name can be used to authenticate to multiple
     Google Maps-based APIs on the Android platform, including the
     Navigation SDK for Android. For backwards compatibility, the API also
     supports the name `com.google.android.maps.v2.API_KEY`. This legacy
     name allows authentication to the Android Maps API v2 only. An application can
     specify only one of the API key metadata names. If both are specified, the API
     throws an exception.
   - Provide the API key programmatically: The Secrets Gradle Plugin makes the key available in the `BuildConfig` class.
     In your app's initialization (for example, in your `Application.onCreate()` method),
     call the method as follows:

     ### Kotlin

     1. Add the following import statements:

        ```kotlin
        import com.google.android.libraries.navigation.NavigationApi
        ```
     2. Add the following to your `Application.onCreate()` method:

        ```kotlin
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)
        ```

     ### Java

     1. Add the following import statements:

        ```java
        import com.google.android.libraries.navigation.NavigationApi;
        ```
     2. Add the following to your `Application.onCreate()` method:

        ```java
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
        ```
     **Note:** When using `setApiKey()`, keep the following in mind:
     - Provide a non-null, non-empty API key.
     - Call `setApiKey()` only once during your application's lifetime. The method throws an `IllegalStateException` if called more than once.
     - Call `setApiKey()` before initializing any other Navigation SDK components, such as `Navigator`.
     - The key you provide with this method overrides any API key in your `AndroidManifest.xml`.
     - Use Navigation SDK version 7.6 or higher.
7. In Android Studio, open your module-level `build.gradle.kts`
   or `build.gradle` file and edit the `secrets`
   property. If the `secrets` property doesn't exist, add it.

   Edit the properties of the plugin to set `propertiesFileName`
   to `"secrets.properties"`, set
   `defaultPropertiesFileName` to
   `"local.defaults.properties"`, and set any other properties.

   ### Kotlin

   ```kotlin
   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"

       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   ```

   ### Groovy

   ```groovy
   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"

       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   ```

## Include the required attributions in your app

If you use the Navigation SDK for Android in your app, you must include
attribution text and open source licenses as part of your app's legal notices
section.
Key point: To include the attributions, add them as an independent menu item
or an item on an About menu.

You can find the required attribution text and open source licenses in the
Navigation SDK for Android zip file:

- `NOTICE.txt`
- `LICENSES.txt`