> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/ux/llms.txt) # Get Started with the Navigation SDK for Android UX Framework This guide describes the steps to install the latest version of the **Mapbox Navigation SDK for Android UX Framework**, configure your Android app to use the framework, and initialize the navigation UX in an Android View. > **Note: 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](https://www.mapbox.com/legal/nav-sdk-eval-terms). ## Prerequisites - **A Mapbox account**: Sign up or log into a free account on [Mapbox](https://account.mapbox.com/auth/signup/). - **Android Studio**: This guide includes details specific to the latest version of [Android Studio](https://developer.android.com/studio/install). - **Gradle**: Make sure you have [Gradle](https://gradle.org/install/) installed. ## Part 1: Configure credentials ### Step 1: Create a secret token A [secret access token](https://docs.mapbox.com/help/dive-deeper/access-tokens/#secret-tokens) 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](https://console.mapbox.com/account/access-tokens/). 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](https://console.mapbox.com/account/access-tokens/), 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**. Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/create-secret-token-compressed-823407693dc7c7f3351fb5c23377d5bf.mp4). > **Note (warning): 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](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_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, but is also available in Android Studio's project explorer under `Gradle Scripts/gradle.properties (Global Properties)` 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. ```text MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN ``` Your secret token is now configured and will be used to authenticate with the Mapbox maven server when you add the SDK dependency to your project. ### 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](https://developer.android.com/guide/topics/resources/string-resource#String). 1. Locate the resource folder: - In the project explorer, find and expand your resource folder located at `app/res/values`. 2. Create a new string resource file : - Right click on the `values` folder - Select **New > Values Resource File** - Name the file `mapbox_access_token.xml` - Click the **OK** button. 3. 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](https://console.mapbox.com/account/access-tokens/). ```xml YOUR_MAPBOX_ACCESS_TOKEN ``` Your Mapbox public access token is now available for use in your Android project. The Maps SDK for Android automatically looks for the `mapbox_access_token` string resource when you initialize a map, so you don't need to do anything else to use the token in your app. Details **Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime** > **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/troubleshooting/private-access-token-android-and-ios/)** > > 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](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/). ## 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 the project explorer, find and open `Gradle Scripts/settings.gradle.kts`. 2. Add a new `maven {...}` definition inside `dependencyResolutionManagement.repositories`. **Groovy** ```groovy dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // Mapbox Maven repository maven { url = uri("https://api.mapbox.com/downloads/v2/releases/maven") authentication { basic(BasicAuthentication) } 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() } } } } ``` **Kotlin** ```kotlin dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // Mapbox Maven repository maven { url = uri("https://api.mapbox.com/downloads/v2/releases/maven") authentication { create("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() } } } } ``` This configuration uses the **secret access token** you configured in **Part 1** to authenticate with the Mapbox Maven repository. > **Note (warning): Add the Mapbox Maven repository in the correct location** > > Make sure you configure the Mapbox maven repository inside `dependencyResolutionManagement` and not inside `pluginManagement`. While in beta, the Navigation SDK UX Framework requires additional maven configuration to download some snapshot dependencies. Add the following to your project-level `settings.gradle` file, after the main Mapbox Maven repository configuration: ```kotlin ... maven { url = uri("https://api.mapbox.com/downloads/v2/snapshots/maven") credentials { username = "mapbox" password = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get() } authentication { create("basic") } } ... ``` ### Step 2: Add the UX Framework dependency Next, add the Navigation SDK UX Framework module to your project. 1. In Android Studio, open your *module-level* `build.gradle` file. 2. Add the UX Framework module under `dependencies`. **Groovy** Title: `build.gradle` ```groovy dependencies { ... implementation 'com.mapbox.navigationux:android:1.29.0' ... } ``` **Kotlin** Title: `build.gradle.kts` ```kotlin dependencies { ... implementation("com.mapbox.navigationux:android:1.29.0") ... } ``` ## Part 3: Implement the UX Framework ### Step 1: Initialize the Framework You must initialize the UX Framework in your `Application` class. You can extend the `Application` class and override the `onCreate` method. 1. Create a new file `MyApplication.kt` in the same directory as your other activities and add the following code: ```kotlin package com.example.navproject; import android.app.Application; import com.mapbox.dash.sdk.Dash class MyApplication : Application() { override fun onCreate() { super.onCreate() // Initialize the framework Dash.init( context = this, accessToken = getString(R.string.mapbox_access_token) ) } } ``` 2. Update your `AndroidManifest.xml` file to use the `MyApplication` class as the application class: ```xml ... ... ``` ### Step 2: Add a navigation fragment You must add a navigation fragment provided by the UX Framework to your application to tell it where to display the navigation UI. You can do this by adding a `FragmentContainerView` to your activity layout file, or by adding the fragment via the standard Android fragment manager. **FragmentContainerView** In your main activity's xml layout file, add a `FragmentContainerView` with the `android:name` attribute set to `com.mapbox.dash.sdk.DashNavigationFragment`. ```xml ``` Be sure that your main activity is referencing this layout file in its `setContentView` method: ```kotlin package com.example.navproject; import android.os.Bundle import androidx.appcompat.app.AppCompatActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Use the XML layout } } ``` **Android Fragment Manager** In your activity class, add the navigation fragment using the Android fragment manager. ```kotlin class MainActivity : 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() } } } ``` ### Step 3: Run your app Sync your project with Gradle and run your app on a device or emulator. You will see the navigation UI displayed in the `FragmentContainerView` or the activity layout. ![The Navigation SDK UX Framework initialized and running on an android device.](https://docs.mapbox.com/android/assets/ideal-img/navigation-ux-hello-world.2b62827.480.png) ## Troubleshooting ### 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`. ```Kotlin // build.gradle.kts android { packagingOptions { resources { excludes += setOf( // To compile the current version of UX Framework you need to add only these three lines: "META-INF/DEPENDENCIES", "META-INF/INDEX.LIST", "dash-sdk.properties", ) } } } ``` 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. ```Kotlin // build.gradle.kts configurations.all { exclude(group = "com.google.guava", module = "listenablefuture") } ``` ## Next Steps With a minimal implementation working, you can now explore the Navigation SDK UX Framework's features and customize the navigation experience in your app. - See the [Configuration API documentation](https://docs.mapbox.com/android/navigation/ux/guides/configuration/) to learn how to configure the navigation experience, including themes, voices, UI settings, and more. - See the [Customization API documentation](https://docs.mapbox.com/android/navigation/ux/guides/customization/) to learn how to customize the navigation UI, including colors, fonts, and custom UI elements. - Familiarize yourself with the [API Reference Documentation](https://docs.mapbox.com/android/navigation/ux/api-reference/) to learn about the classes and methods available in the Navigation SDK UX Framework.