Installation

Join the Mapbox Developers Discord Communityarrow-right

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.

Evaluation Terms

By downloading UX Framework with MapGPT you agree that you're downloading beta software licensed only on the following terms: https://www.mapbox.com/legal/nav-sdk-eval-terms.

Before developing your application with the UX Framework, 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:

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

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

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

6. Every 48 hours make a request to your backend to check the token.
7. 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.

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

Add SDK dependency

Mapbox provides the UX Framework via Maven. Add the following lines to your root-level Gradle file to include the UX Framework repository:

// build.gradle.kts
repositories {
    maven {
        url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        credentials {
            username = "mapbox"
            password = MAPBOX_DOWNLOADS_TOKEN
        }
        authentication {
            create<BasicAuthentication>("basic")
        }
    }
}

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

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.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?