Installation Guide | Navigation SDK | Android Docs

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 to create one):

A public access token: From your account's tokens page, 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, 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 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:

Find or create a gradle.properties file in your Gradle user home folder. 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.
Add your secret token your gradle.properties file:

MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN

Configure your public token

The SDK supports multiple ways of providing an access token: through app resources or by setting it at runtime.

Resources

One way to provide your public token to Mapbox SDK is by adding it as an Android string resource.

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

<?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_PUBLIC_MAPBOX_ACCESS_TOKEN</string>
</resources>

In this case, if you want to rotate an access token, you'll need to re-release your app. For more information on access token rotation, consult the Access Tokens Information page.

Runtime

Another way to provide a token is to do it at runtime with this code:

MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN

You will find this option helpful in case you want to rotate your tokens at runtime or want to receive the token from your backend instead of storing it in your apk.

Note that you must set a valid token before any interaction with the SDK, including its initialization, otherwise the SDK will not be able to use your token.

For example, in case of Navigation SDK, first set the token and only then initialize it.

In case of Maps SDK, set the token before inflating the MapView (may be a setContentView invocation in your Activity#onCreate).

But once you change the token at runtime, the new one will be used by all the SDKs from that point on.

For example, if you have a long-living app and want to rotate the token every 48 hours, here is a possible approach you might want to consider:

On the first app start make a network request to your backend for a token.
When you receive a token, load the Navigation component in your app that will instantiate the Navigation SDK, inflate the MapView, etc.
Store the token in your app files.
On the next app launch you can read the token from file.

If it's not available (for example, app data was cleared), make another request to your backend and delay loading the Navigation component.

Every 48 hours make a request to your backend to check the token.
If the token changed, at any point in your app's lifecycle invoke:

MapboxOptions.accessToken = YOUR_NEW_PUBLIC_MAPBOX_ACCESS_TOKEN

From this moment on it will be used by all the Mapbox SDKs.

Store the new token in your app's directory.

For information on how you can create a new value for your token, consult the Access Tokens Information Page.

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.

<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 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:

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

The notification contains some useful trip progress information and UI controls. So it's highly recommended that you request the permission in runtime. 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.

Handle location permissions

The Navigation SDK makes use of the Android manifest merge feature. The SDK's manifest file already has both the course and fine location permission lines, 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 PermissionsManager.

Add Mapbox Repository

Mapbox provides the Navigation SDK via Maven.

To add the 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.

Open your project in Android Studio.

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. The placement of these declarations depends on the versions of Android Studio and Gradle that 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:

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:

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

Open up your module-level build.gradle file.

The Navigation SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions.

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"
	}
    ...
}

Make sure that your project's minSdkVersion is at API 21 or higher.

android {
    ...
    defaultConfig {
        minSdkVersion 21
    }
}

Add dependency

Add the dependency under dependencies. The Navigation SDK offers a range of components, each with its own dependency name:
- Navigation component allows you to access the primary interface for engaging with the Navigation SDK
```
dependencies {
	implementation "com.mapbox.navigationcore:navigation:3.0.2"
}
```
- Mapbox Copilot is a component that collects detailed trace files of navigation sessions together with search analytics data
```
dependencies {
	implementation "com.mapbox.navigationcore:copilot:3.0.2"
}
```
- Maps component provides a set of classes that can enhance the navigation experience for your users, for example, Navigation Camera to simplify management of the map's camera object, or Route Line to render a route line on a map
```
dependencies {
	implementation "com.mapbox.navigationcore:ui-maps:3.0.2"
}
```
- Voice component allows users to access Voice API
```
dependencies {
	implementation "com.mapbox.navigationcore:voice:3.0.2"
}
```
- Trip Data component provides convenient API to request maneuver instructions, route shields, speed limit, and trip progress data.
```
dependencies {
	implementation "com.mapbox.navigationcore:tripdata:3.0.2"
}
```
- Android component provides all the listed above components
```
dependencies {
	implementation "com.mapbox.navigationcore:android:3.0.2"
}
```
- UI components module provides pre-built UI widgets
```
dependencies {
	implementation "com.mapbox.navigationcore:ui-components:3.0.2"
}
```
The detailed documentation about all the Navigation SDK components is coming soon.
Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

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 and optimizing your code.

Was this page helpful?

Configure credentials​

Configure your secret token​

Configure your public token​

Resources​

Runtime​

Configure permissions​

Add Mapbox Repository​

Add dependency​