> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/v2/llms.txt)

# Installation

Before starting to develop your application with the Navigation SDK, you'll need to configure your credentials and add the SDK as a dependency.

## Configure credentials

Before installing the SDK, you will need to gather the appropriate credentials.

The SDK requires two pieces of sensitive information from your Mapbox account (or [sign up](https://account.mapbox.com/auth/signup/) to create one):

-   **A public access token**: From your account's [tokens page](https://console.mapbox.com/account/access-tokens/), you can either copy your *default public token* or click the **Create a token** button to create a new public token.
-   **A secret access token with the `Downloads:Read` scope**.
    1.  From your account's [tokens page](https://console.mapbox.com/account/access-tokens/), click the **Create a token** button.
    2.  From the token creation page, give your token a name and make sure the box next to the `Downloads:Read` scope is checked.
    3.  Click the **Create token** button at the bottom of the page to create your token.
    4.  The token you've created is a *secret token*, which means you will only have one opportunity to copy it somewhere secure.

You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and take advantage of [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties) to make sure they're only added when your app is compiled (see next section).

### Configure your secret token

To avoid exposing your secret token, add it as an environment variable:

1.  Find or create a `gradle.properties` file in your [Gradle user home folder](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home). The folder is located at `«USER_HOME»/.gradle`. Once you have found or created the file, its path should be `«USER_HOME»/.gradle/gradle.properties`. More details about Gradle properties in the [official Gradle documentation](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties).
2.  Add your secret token your `gradle.properties` file:

```
MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
```

### Configure your public token

The preferred way to provide your public token to Mapbox SDK is by adding it as an [Android string resource](https://developer.android.com/guide/topics/resources/string-resource#String).

To do so create a new string resource file in your app module (for example `app/src/main/res/values/developer-config.xml`) with your public Mapbox API token:

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string>
</resources>
```

If you ever need to [rotate YOUR_MAPBOX_ACCESS_TOKEN](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/), you will need to update the token value in your xml file.

### Configure permissions

If you plan to display the user's location on the map or get the user's location information you will need to add the `ACCESS_COARSE_LOCATION` permission in your application's `AndroidManifest.xml`. You also need to add `ACCESS_FINE_LOCATION` permissions if you need access to precise location. You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the [`PermissionsManager`](https://docs.mapbox.com/android/maps/guides/user-location/permissions/).

```xml
<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>
```

If your app targets Android 13 or higher, [`POST_NOTIFICATIONS`](https://developer.android.com/guide/topics/ui/notifiers/notification-permission) permission is required to show notifications to the user. Navigation SDK shows the notification during both Free Drive and Active Guidance, if you don't explicitly disable the foreground service launch by calling `MapboxNavigation#startTripSession(false)`. That's why the Navigation SDK declares this permission in its `AndroidManifest.xml` (starting from v2.8.0):

```xml
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

The notification contains some useful trip progress information and UI controls. For more information see [the notification section](https://docs.mapbox.com/android/navigation/v2/guides/ui-components/notifications/). So it's highly recommended that you [request the permission in runtime](https://developer.android.com/training/permissions/requesting#request-permission). The Navigation SDK will continue working and receiving location updates when minimized even if the permission is not granted, but there will be no trip notification displayed.

> **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/troubleshooting/private-access-token-android-and-ios/)**
> 
> Learn how to keep access tokens private in mobile apps.

> **Note: Handle location permissions**
> 
> The Navigation SDK makes use of the Android manifest merge feature. [The Navigation SDK's manifest file already has both the course and fine location permission lines](https://github.com/mapbox/mapbox-navigation-android/blob/main/navigation/src/main/AndroidManifest.xml), which means you don't have to declare any location permissions inside your project's manifest file or in some other way.If your project targets Android API 23 or higher, make sure to check the user location permission in runtime using [the Mapbox Core Library for Android's `PermissionsManager` interface](https://docs.mapbox.com/android/maps/guides/user-location/permissions/).

## Add the dependency

Mapbox provides the Navigation SDK via **Maven**.

To add the Mapbox Navigation SDK as a dependency, you will need to configure your build to download the Navigation SDK from Mapbox directly. This requires a valid username and password.

1.  Open your project in Android Studio.
    
2.  Declare the Mapbox Downloads API's `releases/maven` endpoint. To download the Navigation SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added the password to a `gradle.properties` file in your Gradle user home folder. **The username field should always be `"mapbox"`**. It should not be your personal username used to create the secret token. Where you make these declarations depend on the versions of Android Studio and Gradle your project is using:
    
    -   **Android Studio less than Arctic Fox (2020.3.1) and Gradle less than v6.0:** Open up your *project-level* `build.gradle` file, and add the code below to declare the endpoint in the `repositories` block:
        
        ```groovy
        allprojects {
            repositories {
                maven {
                      url 'https://api.mapbox.com/downloads/v2/releases/maven'
                      authentication {
                          basic(BasicAuthentication)
                      }
                      credentials {
                        // Do not change the username below.
                        // This should always be `mapbox` (not your username).
                          username = "mapbox"
                          // Use the secret token you stored in gradle.properties as the password
                          password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
                      }
                  }
            }
        }
        ```
        
    -   **Android Studio Arctic Fox (2020.3.1) or later and Gradle v6.0 or later:** You may need to make these declarations in your `settings.gradle` file instead. If you see build errors with the `build.gradle` process described above, then instead declare the Mapbox's Maven repository in your `settings.gradle` file like below:
        
        ```groovy
        dependencyResolutionManagement {
            repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
            repositories {
                google()
                mavenCentral()
                maven {
                  url 'https://api.mapbox.com/downloads/v2/releases/maven'
                  authentication {
                    basic(BasicAuthentication)
                  }
                  credentials {
                    // Do not change the username below.
                    // This should always be `mapbox` (not your username).
                    username = "mapbox"
                    // Use the secret token you stored in gradle.properties as the password
                    password = MAPBOX_DOWNLOADS_TOKEN
                  }
                }
            }
        }
        ```
        
3.  Open up your *module-level* `build.gradle` file.
    
4.  The Navigation SDK uses Java 8 features. To enable Java 8 in your project, add the following `compileOptions`.
    
    ```groovy
    android {
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
        // Add the block below if you're using Kotlin
        kotlinOptions {
        	jvmTarget = "1.8"
    	}
        ...
    }
    ```
    
5.  Make sure that your project's `minSdkVersion` is at API 21 or higher.
    
    ```groovy
    android {
        ...
        defaultConfig {
            minSdkVersion 21
        }
    }
    ```
    
6.  Add the dependency under *dependencies*. Go to [Choose an approach](https://docs.mapbox.com/android/navigation/v2/guides/get-started/choose-an-approach/) section to learn more about available integration paths.
    
7.  Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.
    

> **Note: Use nightly builds and beta versions**
> 
> You can also use a SNAPSHOT version of the Navigation SDK if you want access to bug fixes or features that have not been packaged in an official release yet. Find more information about how to do this inside [the Navigation SDK's GitHub repository](https://github.com/mapbox/mapbox-navigation-android/#using-snapshots).

> **Note (warning): Method limit**
> 
> If you've added the Navigation SDK, finished all the installation steps above, and see an Android Studio error saying that you've reached maximum method count, try enabling Multidex following the official Android guides to using [multidex](https://developer.android.com/studio/build/multidex) and [optimizing your code](https://developer.android.com/studio/build/shrink-code).

## Display a navigation UI

To simulate your first navigation experience using our UI components, use the [Add a complete turn-by-turn experience](https://docs.mapbox.com/android/navigation/v2/examples/turn-by-turn-experience/) example.

> **Related content (example): [Add a complete turn-by-turn experience](https://docs.mapbox.com/android/navigation/v2/examples/turn-by-turn-experience/)**
> 
> Render a complete turn-by-turn experience using all relevant Navigation SDK APIs and pre-built UI components.