Installation

Join the Mapbox Developers Discord Communityarrow-right

To use the Vision SDK you'll need to configure the 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 preferred 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>

If you ever need to rotate YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN, you will need to update the token value in your xml file.

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>

guide

Access token best practices

Learn how to keep access tokens private in mobile apps.

chevron-right

Add the dependency

Mapbox provides the Vision SDK via Maven.

To add the Vision SDK as a dependency, you will need to configure your build to download the Vision SDK from Mapbox directly. This requires a valid username and password.

1. Open your project in Android Studio.
2. Open up your module-level build.gradle file.
3. The Vision SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions:

android {
  ...
  // Configure only for each module that uses Java 8
  // language features (either in its source code or
  // through dependencies).
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"
  }
}

4. Make sure that your project's minSdkVersion is at API 23 or higher.

android {
  ...
  defaultConfig {
      minSdkVersion 23
  }
}

5. Add Vision dependencies under dependencies:

   dependencies {
     implementation "com.mapbox.vision:mapbox-android-vision:0.13.0"
     implementation "com.mapbox.vision:mapbox-android-vision-ar:0.13.0"
     implementation "com.mapbox.vision:mapbox-android-vision-safety:0.13.0"
   }
   

6. Open up your project-level build.gradle file. Declare the Mapbox Downloads API's v2/releases/maven endpoint in the repositories block. To download the Vision SDK, you must authenticate your request with a valid username and password. In the previous section, you added your secret token as a password in the gradle.properties file in your Gradle user home folder.

allprojects {
  repositories {
    maven {
      url '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 = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
      }
    }
  }
}

7. Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

SDK configuration

After downloading or importing the SDK into your project, you have to configure it.

Create an application

Create a new class, initialize VisionManager, and pass it the public Mapbox access token you added to your strings.xml file:

Java

Kotlin

class VisionApp : Application() {
	fun onCreate() {
		super.onCreate()
		VisionManager.init(this, getResources().getString(R.string.mapbox_access_token))
	}
}

Configure permissions

The Mapbox Vision SDK requires several permissions as well as location permission required by other Mapbox SDKs. Add the following permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

These should all be granted before calling the SDK.

Add VisionView to the activity layout (optional)

VisionView will render the image that was produced by Vision SDK. You can add it with the following snippet:

<com.mapbox.vision.view.VisionView
  android:id="@+id/vision_view"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  app:visualization_mode="detection" />

app:visualization_mode specifies what will be rendered on VisionView: clear video source, segmentation, or detections.

Lifecycle methods

Call lifecycle methods of VisionManager. To listen for events that Vision SDK produces, pass an instance of VisionEventsListener to the VisionManager.

Java

Kotlin

override fun onResume() {
	super.onResume()
	VisionManager.create()
	vision_view.setVisionManager(VisionManager)
	vision_view.onResume()
	VisionManager.visionEventsListener = visionEventsListener
	VisionManager.start()
}

override fun onPause() {
	super.onPause()
	vision_view.onPause()
	VisionManager.stop()
	VisionManager.destroy()
}

Local testing setup

Read more about setting up your development environment for testing the capabilities of the Vision SDK in the Testing and development guide.

Vehicle setup

After installing the framework, you will need to set up the device in the vehicle. Some things to consider when choosing and setting up a mount:

• Generally, shorter length mounts will vibrate less. Mounting to your windshield or to the dashboard are both options.
• Place the phone near or behind your rearview mirror. Note that your local jurisdiction may have limits on where mounts may be placed.
• Make sure the phone’s camera view is unobstructed (you will be able to tell with any of the video screens open).

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?