Skip to main content

Installation

Additional Developer Resources

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​

Step 1: Log in/Sign up for a Mapbox account​

If you haven't done so already, sign up for a Mapbox account and log into it.

Follow these links to sign up or sign in to Mapbox or click the buttons in the top right corner of your browser.

This account will allow you to create tokens and will create a default public token for you upon creation.

Step 2: Create a secret token​

A secret token can enable access to various products/services at Mapbox, including the ability to download an SDK. To allow download access to an SDK, 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.

This video also walks through the steps above:

Protect secret access tokens

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

Step 3: Configure your secret token​

To avoid exposing your secret token, let's add it as an environment variable using gradle:

Installing Gradle

If you do not already have gradle installed, follow the Gradle Install guide to install gradle onto your computer.

To configure your secret token, follow these steps:

  1. Check if you already have a gradle.properties file in your Gradle user home folder.
  • Open the Gradle user home folder at /Users/USERNAME/.gradle.
  • Note that you may not be able to see this folder and need to be reveal it.
    • If on Mac, press Command + Shift + . to show hidden folders.
    • If on Windows, click View in the Explorer Window, and then click Show > Hidden Items.
  • With the folder revealed, you'll be able to open your .gradle folder and check for your gradle.properties file.
  1. If the gradle.properties file doesn't exist, create the file.
    • If you already have this file skip this step and go onto Step 3.
    • For Mac, open a terminal in your .gradle folder and type touch gradle.properties.
    • For Windows, open a command window in your .gradle folder and type echo >> gradle.properties.
  2. Open your gradle.properties file and copy and paste the snippet below into the file:
MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
  1. Grab the secret token you made before and replace the text YOUR_SECRET_MAPBOX_ACCESS_TOKEN with the secret token.
Learn more about Gradle

More details about Gradle properties in the official Gradle documentation.

Step 4: Configure your public token​

Next let's provide an access token to the SDK by adding the token as an Android string resource.

To do this, follow these steps:

  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. Go to the folder structure in the left side of Android Studio and open your resource folder located at app/res/values.
  2. Create a new resource file, by left clicking on the folder, selecting New > Values Resource File
  3. Name the file mapbox_access_token.xml and click the Ok button.
  4. In the new file, copy and paste the code from below.
  5. Make sure your token is included in the code snippet. The token should start with the letter pk. If you see YOUR_MAPBOX_ACCESS_TOKEN in your code, log into your mapbox account and then copy the snippet again.
    • When you're logged into your account, your public mapbox token is automatically added to code snippet. You can also grab your default by going to 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>
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:

  1. Open app > manifests > AndroidManifest.mxl
  2. 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.
  1. 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.

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

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 &lt;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.

Additional Developer Resources
Was this page helpful?