Get Started with the Navigation SDK for Android | Navigation SDK | Android Docs (original) (raw)

This guide describes the steps to install the latest version of the Mapbox Navigation SDK for Android, configure your Android app to use the SDK, and run a minimal example showing turn-by-turn navigation.

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.
• Gradle: Make sure you have Gradle installed.

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:

1. Go to your account's tokens page.
2. Click the Create a token button.
3. Name your token, for this example we've used InstallTokenAndroid.
4. Scroll down to the Secret Scope section and check the Downloads:Read scope box.
5. Click the Create token button at the bottom of the page to create your token.
6. Enter your password to confirm the creation of your token.
7. 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.

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 3: Configure your public token​

Your app must have a public access token configured to associate its usage of Mapbox resources with your account.

Follow these steps to add a public access token from your Mapbox account as an Android string resource.

1. 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.

1. Locate the resource folder:

• In the project explorer, open your resource folder located at app/res/values.

1. Create a new resource file:

• Left click on the resource folder
• Select New > Values Resource File
• Name the file mapbox_access_token.xml
• Click the Ok button.

1. In the new file, copy and paste the code snippet below.

• Make sure you are signed in to docs.mapbox.com. This will insert your default public token into the code snippet (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.

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

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 4: Understand permissions​

Real-time navigation requires access to the user's location, access to the network, and access to notify the user of updates. The SDK already includes all necessary permissions in its AndroidManifest.xml file, and these will be merged with any permissions you have in your app's manifest file via Manifest Merging.

You do not need to add any additional permissions to your app's manifest file, but you should make sure that your app requests the necessary permissions at runtime. The SDK provides a PermissionsManager class to help you manage permissions. You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager.

The permissions used by the SDK are listed below:

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 Mapbox dependencies, you must add the Maven repository's URL to your project.

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

This configuration accesses the secret access token you configured in Part 1 to authenticate with the Mapbox Maven repository.

Step 2: Add Nav SDK dependencies​

Next, add the Nav SDK modules to your project to start using the Mapbox Navigation SDK for Android:

1. In Android Studio, open your module-level build.gradle file.
2. Add the Navigation SDK dependency under dependencies.
   • This will allow you to access base navigation services, like creating a route. Additional Navigation Services - Limiting dependencies in the SDK

There are other navigation modules you can add to your implementation, based on your app's requirements. See the list below:

1. Make sure that your project's minSdk is 21 or higher:

Part 3: Run a Navigation Example​

To confirm that the Navigation SDK dependencies are correctly installed and your tokens are configured properly, create a turn-by-turn navigation with simulated user locations.

The code below displays a scaled-down navigation experience with a map, route line, and location puck.

1. Add the sample code below to your MainActivty.kt file to run the simulation:
2. Click File > Sync Project with Gradle Files
3. Click the play button to build the app and run it on an emulator or device. After the map loads, you will see simulated navigation begin, with the camera following the user's location along the route.

You can experiment with the code to customize the navigation experience. For example, you can change the route's origin and destination points, or add custom logic to handle user location updates.

Troubleshooting​

If your implementation is not working as expected, view the following troubleshooting solutions:

Black screen

If when you run simulator your screen displays black, here are some possible solutions:

• Make sure both your secret token and public token are both valid and present
  • If you see YOUR_MAPBOX_ACCESS_TOKEN in your code, your map will not render.
• If you are also seeing this error onmaploaderror: style, message: failed to load style: couldn't connect to server: exception in croneturlrequest: net::err_name_not_resolved, you will need to wipe your simulator data.
  • This error could be caused by your simulator losing access to the internet. To fix this problem, try the following:
    * Make sure you have access to the internet.
    * If you have internet access, next click Tools > Device Manager.
    * Then click options and select Wipe Data.
    * Wait until your simulator loads back up, and then try running the simulator again.

Route does not appear

If your map appears but the route does not appear on the map, here are some possible solutions:

• If this is the first time running the simulator after setting location permissions, try restarting the simulator and running it again.
• Make sure you are using a valid secret token.
  • This token must use the Downloads:Read scope.
• Make sure your token is assigned in your gradle.properties file.
• Make sure the settings.gradle.kts file inside the credentials struct, the username is mapbox and not your username.

Maximum method count My application is crashing on start or won't build

• Make sure the package line in your MainActivity.kt matches your project name and does not read package com.example.myapplication.
• Make sure you configure the Mapbox maven repository inside dependencyResolutionManagement and not inside pluginManagement in your settings.gradle.kts file.

General Tips

Make sure your always click Save All and Sync Project with Gradle Files when making changes to your application.

Next Steps​

Congratulations! You've gotten your application up and running with the Mapbox Navigation SDK for Android.

What we've covered​

• Created a secret token
• Added secret and public tokens to your project.
• Added a maven dependency to install the Mapbox Navigation SDK for Android
• Learned about how permissions work in Android
• Ran a minimal example showing turn-by-turn navigation

Learn more​

Explore other learning related to Mapbox Navigation SDK for Android:

Additional Developer Resources