Installation
Before starting to develop your application with the Maps SDK, you'll need to configure your credentials and add the SDK as a dependency. This document describes the steps to install the stable version of the Maps SDK, but you can also use the nightly build (as in SNAPSHOT) or the beta version, if one is available. Find more information about how to do this inside the project’s GitHub repository.
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:Readscope.- From your account's tokens page, click the Create a token button.
- From the token creation page, give your token a name and make sure the box next to the
Downloads:Readscope is checked. - Click the Create token button at the bottom of the page to create your token.
- 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:
- Find or create a
gradle.propertiesfile 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. - Add your secret token your
gradle.propertiesfile:
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 (for example 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_MAPBOX_ACCESS_TOKEN</string>
</resources>
If you ever need to rotate YOUR_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>
Learn how to keep access tokens private in mobile apps.
Add the dependency
Mapbox provides the Maps SDK via Maven.
To add the Mapbox Maps SDK as a dependency, you will need to configure your build to download the Maps SDK from Mapbox directly. This requires a valid username and password.
- Open your project in Android Studio.
- Open up your module-level
build.gradlefile. - Make sure that your project's
minSdkVersionis at API 14 or higher.
android {
...
defaultConfig {
minSdkVersion 14
}
}
- Under dependencies, add a new build rule for the latest
mapbox-android-sdk.
dependencies {
implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.7.1'
}
- Open up your project-level
build.gradlefile. Declare the Mapbox Downloads API'sv2/releases/mavenendpoint in the repositories block. To download the Maps SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added these to a 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'] ?: ""
}
}
}
}
- Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.
Note: You might have mismatching Gradle dependencies once you add the Mapbox Maps SDK for Android. If necessary, you can use exclude group to remove certain dependencies:
implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:9.7.1'){
exclude group: 'group_name', module: 'module_name'
}
Additionally, running gradle app_module_name_here:dependencies in your command line will print a list of dependencies. ./gradlew app:dependencies works if you have a Gradle wrapper. They are helpful for troubleshooting nimble Gradle configurations when various libraries are included in a single project. You can see the dependencies that specific libraries are bringing and where conflicts might be happening.
Add a map
Open the activity you’d like to add a map to and use the code below.
private MapView mapView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Mapbox.getInstance(this, getString(R.string.mapbox_access_token));
setContentView(R.layout.activity_main);
mapView = (MapView) findViewById(R.id.mapView);
mapView.onCreate(savedInstanceState);
mapView.getMapAsync(new OnMapReadyCallback() {
@Override
public void onMapReady(@NonNull MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
@Override
public void onStyleLoaded(@NonNull Style style) {
// Map is set up and the style has loaded. Now you can add data or make other map adjustments
}
});
}
});
}
private var mapView: MapView? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
Mapbox.getInstance(this, getString(R.string.mapbox_access_token))
setContentView(R.layout.activity_main)
mapView = findViewById(R.id.mapView)
mapView?.onCreate(savedInstanceState)
mapView?.getMapAsync { mapboxMap ->
mapboxMap.setStyle(Style.MAPBOX_STREETS) {
// Map is set up and the style has loaded. Now you can add data or make other map adjustments
}
}
}
Open the activity’s XML layout file and add the following:
<com.mapbox.mapboxsdk.maps.MapView
android:id="@+id/mapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
/>
The MapView contains its own lifecycle methods for managing Android's OpenGL lifecycle, which must be called directly from the containing Activity. For your app to correctly call the MapView's lifecycle methods, you must override the following lifecycle methods in the Activity that contains the MapView and call the respective MapView method. The following lifecycle methods must be overridden and include the matching MapView method. If you're using a fragment, call mapview.onDestroy() inside the fragment's onDestroyView() method rather than inside onDestroy().
@Override
protected void onStart() {
super.onStart();
mapView.onStart();
}
@Override
protected void onResume() {
super.onResume();
mapView.onResume();
}
@Override
protected void onPause() {
super.onPause();
mapView.onPause();
}
@Override
protected void onStop() {
super.onStop();
mapView.onStop();
}
@Override
protected void onSaveInstanceState(Bundle outState) {
super.onSaveInstanceState(outState);
mapView.onSaveInstanceState(outState);
}
@Override
public void onLowMemory() {
super.onLowMemory();
mapView.onLowMemory();
}
@Override
protected void onDestroy() {
super.onDestroy();
mapView.onDestroy();
}
override fun onStart() {
super.onStart()
mapView?.onStart()
}
override fun onResume() {
super.onResume()
mapView?.onResume()
}
override fun onPause() {
super.onPause()
mapView?.onPause()
}
override fun onStop() {
super.onStop()
mapView?.onStop()
}
override fun onSaveInstanceState(outState: Bundle) {
super.onSaveInstanceState(outState)
mapView?.onSaveInstanceState(outState)
}
override fun onLowMemory() {
super.onLowMemory()
mapView?.onLowMemory()
}
override fun onDestroy() {
super.onDestroy()
mapView?.onDestroy()
}
onDestroyView() method:override fun onDestroyView() {
super.onDestroyView()
mapView?.onDestroy()
}