Installation
This document describes the steps to install the Public Preview version of the UX Framework. The steps described in this guide allow you to build a fully functional navigation application using the Mapbox UX Framework.
Before developing your application with the UX Framework, 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.
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.
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. 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 theOk
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 placeholderYOUR_MAPBOX_ACCESS_TOKEN
with a token from your account's tokens page.
<?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
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 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:
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
If your app targets Android 13 or higher, the POST_NOTIFICATIONS
permission is required to show notifications to the user. The SDK shows the notifications during both Free Drive and Active Guidance if you don't explicitly disable the foreground service launch by calling MapboxNavigation#startTripSession(false)
.
The notification contains some useful trip progress information and UI controls, so it is highly recommended that you request the permission in runtime.
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 insidedependencyResolutionManagement.repositories
.
Step 2: Add the UX Framework dependency
- Add the following line to your module-level Gradle file to include the UX Framework dependency:
// build.gradle.kts
dependencies {
implementation("com.mapbox.navigationux:android:1.0.0-beta.44")
}
Known Issues
When building an Android application, dependencies can bring along duplicate resource files or the same libraries. This can lead to conflicts when trying to compile the project.
Duplicate resource files in various libraries.
Many libraries include files like LICENSE, NOTICE, etc. If two or more libraries in your project contain the same files, it will cause a file duplication error when packaging the APK. To resolve this issue, you can exclude these files using the packagingOptions
.
// build.gradle.kts
android {
packagingOptions {
resources {
excludes += setOf(
// To compile the current version of UX Framework you need to add only these two lines:
"META-INF/DEPENDENCIES",
"META-INF/INDEX.LIST",
)
}
}
}
Another dependency issue you may see related to the ListenableFuture
library. That Guava's library might be included both directly and via other libraries. If this happens, you might experience build errors due to duplicate classes or incompatible versions. To address this issue, you can exclude conflicting libraries or versions using the configurations
section.
// build.gradle.kts
configurations.all {
exclude(group = "com.google.guava", module = "listenablefuture")
}
Initialize the UX Framework
Inside the android.app.Application
class, you need to initialize the UX Framework with the initial configuration. Here is an example of the simplest way to initialize SDK:
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Dash.init(
applicationContext = applicationContext,
accessToken = getString(R.string.mapbox_access_token)
)
}
}
Add a navigation fragment
Last step to complete installation and make UX Framework UI visible in your application is to add a navigation fragment provided by the UX Framework to your application. For this purpose you may want to use one of the two standard options:
Specify UX Framework navigation fragment inside the XML file. To make it you will need to declare DashNavigationFragment
in your activity layout using a <fragment/>
tag:
<?xml version="1.0" encoding="utf-8"?>
<androidx.fragment.app.FragmentContainerView
android:id="@+id/container"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:name="com.mapbox.dash.sdk.DashNavigationFragment" />
Add UX Framework navigation fragment via standard Android fragment manager. For this purpose you may want to add the Navigation fragment to your Activity
class:
class MyNavigationActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_my_navigation)
if (savedInstanceState == null) {
supportFragmentManager.beginTransaction()
.replace(R.id.container, DashNavigationFragment.newInstance())
.commitNow()
}
}
}
That’s it! You have successfully set up the UX Framework for creating a navigation Android application. Run it on your phone, tablet, or head unit with Android Lollipop or newer.