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.

Prerequisites

A Mapbox account: Sign up or log into a free account on Mapbox.
Android Studio: This guide includes details specific to the latest version of Android Studio.

Part 1: Configure credentials

Step 1: Create a secret token

A secret access token is required to download the SDK dependencies in your Android project. This token is used by gradle to authenticate with the Mapbox maven server where the SDK packages are hosted.

To create a secret token, follow these steps:

Go to your account's tokens page.
Click the Create a token button.
Name your token, for this example we've used InstallTokenAndroid.
Scroll down to the Secret Scope section and check the Downloads:Read scope box.
Click the Create token button at the bottom of the page to create your token.
Enter your password to confirm the creation of your token.
Now, you'll be returned to your account's tokens page, where you can copy your created token. Note, this token is a secret token, which means you will only have one opportunity to copy it, so save this token somewhere secure.

Protect secret access tokens

You should not expose secret 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.

Step 2: Configure your secret token

Next, add your secret token to your global gradle.properties file. The global gradle.properties file is located in your Gradle user home folder.

If you don't have a gradle.properties file, create one. Add your secret token to the gradle.properties file as shown below, replacing the placeholder YOUR_SECRET_MAPBOX_ACCESS_TOKEN with your secret token.

~/.gradle/gradle.properties


MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN

Step 4: Configure your public token

Your app must have a public access token configured to associate its usage of Mapbox resources with your account. Add a public access token from your Mapbox account as an Android string resource.

To do this, follow these steps:

Open your project folder or create a new project in Android Studio.

If creating a new project, we recommend using the Empty Activity project type.

Go to the folder structure in the left side of Android Studio and open your resource folder located at app/res/values.
Create a new resource file, by left clicking on the folder, selecting New > Values Resource File
Name the file mapbox_access_token.xml and click the Ok button.
In the new file, copy and paste the code snippet below. If you are signed in, this snippet will already contain your default public token (a long string that starts with pk.). If you are not signed in, you will need to replace the placeholder YOUR_MAPBOX_ACCESS_TOKEN with a token from your account's tokens page.

app/res/values/mapbox_access_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>

Your public access token is now available for use in your Android project. You will access it via the string resource you created in your implementation code.

Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime

GUIDE

Access token best practices

Learn how to keep access tokens private in mobile apps.

Adding Tokens at Runtime

You can also implement tokens at runtime, but this requires you to have a separate server to store your tokens. This is helpful if you want to rotate your tokens or add additional security by storing your tokens outside of the APK, but is a much more complex method of implementation.

If you do choose to follow this method, we recommend calling MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN before inflating the MapView, otherwise the app will crash.

Rotating Tokens

For more information on access token rotation, consult the Access Tokens Information page.

Step 5: Configure permissions

If you need to access user's location on the map or get the user's location information you will need to do the following:

Open app > manifests > AndroidManifest.mxl
Determine the permissions you need. If you only need general user location access, add the ACCESS_COARSE_LOCATION permission. If also need access to a more precise location you will need to also call ACCESS_FINE_LOCATION.

Note: You must call ACCESS_COARSE_LOCATION to access location at all, while ACCESS_FINE_LOCATION is only needed for more specific access.

Add the permissions you need as seen in the code snippet to the AndroidManifest.xml.

This should be added at the top of the manifest, below the opening manifest tag and above the opening <application> tag.


 
<!-- Include this permission to grab user's general location -->
 
<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" />

You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager.

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.

Part 2: Add the Dependency

Step 1: Add the Mapbox Maven repository

Mapbox provides the Maps SDK dependencies via a private Maven repository. To download dependencies, you must add the Maven repository's URL to your project.

In Android Studio, under Gradle Scripts, open the settings.gradle file.
Add a new maven {...} definition inside dependencyResolutionManagement.repositories.

Groovy

Kotlin

settings.gradle

Groovy

Kotlin


 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
            authentication {

settings.gradle.kts

Groovy

Kotlin


 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
            authentication {
 
                create<BasicAuthentication>("basic")
 
            }
 
            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 = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
 
            }
 
        }

Step 2: Add Nav SDK dependencies

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.6.0"
}
```
- 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.6.0"
}
```
- 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.6.0"
}
```
- Voice component allows users to access Voice API
```
dependencies {
	implementation "com.mapbox.navigationcore:voice:3.6.0"
}
```
- 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.6.0"
}
```
- Android component provides all the listed above components
```
dependencies {
	implementation "com.mapbox.navigationcore:android:3.6.0"
}
```
- UI components module provides pre-built UI widgets
```
dependencies {
	implementation "com.mapbox.navigationcore:ui-components:3.6.0"
}
```
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.

追加の開発者リソース

この{Type}は役に立ちましたか？