Skip to main content

Get Started with the Maps SDK for Android

Additional Developer Resources

This document describes the steps to install the latest stable version of the Maps SDK, add the Mapbox dependency to your map and quickly get a map up and running in your android application.

Prerequisites​

  • Mapbox account: Sign up or log into a free account on Mapbox.
  • IDE for Android Development: A program to edit and build your Android application, like Android Studio.

Part 1: Create and configure your credentials​

Before starting to develop your application with the Maps SDK, you'll need to create and configure your 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.

You can sign up or sign in by clicking the buttons in the top right corner of your browser or going to https://account.mapbox.com/sign-up.

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

Step 2: 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 snippet below. If you are signed in, this snippet will already contain your default public token (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.
<?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 3: 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.

Part 2: Add the dependency​

Now that we have our credentials, let's add the dependency to our project.

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 maven repository directly.

Access to the Mapbox repository requires a valid username and password. In the previous section, you added the password to your gradle.properties file (see Part 1: Create and configure your credentials ) so now let's access the remote repository with that token:

  1. On the left side of Android Studio, in the file hierarchy, go to your project's settings.gradle file under the Gradle Scripts section and open your top level settings.gradle.kts file.
  2. Add a new maven {...} definition inside the dependencyResolutionManagement.repositories. The hidden sections of the snippet below mimic the settings.gradle.kts file so you can see exactly where to place the snippet below:
 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
            // Do not change the username below. It should always be "mapbox" (not your username).
 
            credentials.username = "mapbox"
 
            // Use the secret token stored in gradle.properties as the password
 
            credentials.password = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
 
            authentication { basic(BasicAuthentication) }
 
        }
  1. Open up your module-level (for example app > GradleScripts > build.gradle.kts) Gradle configuration file and make sure that your project's minSdk is 21 or higher:
android {
  ...
  defaultConfig {
      minSdk 21
      ...
  }
}
  1. Add the Mapbox SDK for Android dependency in the same module-level (for example app > GradleScripts > build.gradle.kts) Gradle configuration file:
dependencies {
  ...
  implementation 'com.mapbox.maps:android:11.8.0'
  ...
}
About Google Play Services

Starting from v11.8.0, the Mapbox Maps SDK for Android brings a transitive dependency on Google Play Services, from which the SDK gets an HTTP client that supports HTTP/3.

The Google Play Services dependency can be removed, and then the SDK will work without support for HTTP/3. For details about how to manage this dependency, follow the instructions below.

  1. (Optional) If you are using Jetpack Compose to build your app, add the Mapbox SDK Jetpack Compose Extension dependency in your module-level (for example app/build.gradle.kts) Gradle configuration file:
android {
  buildFeatures {
    compose true
  }
  composeOptions {
    kotlinCompilerExtensionVersion = "1.3.2"
  }
}
dependencies {
  ...
  implementation 'com.mapbox.maps:android:11.8.0'
  // If you're using compose also add the compose extension
  implementation 'com.mapbox.extension:maps-compose:11.8.0'
  ...
}
  1. Because you've edited your Gradle files, click File > Sync Project with Gradle Files in Android Studio.
Troubleshooting
  • You might have conflicting transitive dependencies. If necessary, you can use exclude group to remove certain dependencies (see Exclude transitive dependencies)
  • The username field in the settings.gradle.kts file should always be "mapbox".
  • Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.

Part 3: Add a map​

Let's add a map to our application. This can be accomplished one of 3 ways:

Jetpack Compose

Jetpack Compose​

You can use Mapbox Maps compose extension to add a map to your composable.

To do make sure the following line is included in your dependencies in the build.gradle.kts file:

implementation ("com.mapbox.extension:maps-compose:11.6.0")

Then add the following code block to your MainActivity.kt file.

package com.mapbox.maps.demo

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.geojson.Point
import com.mapbox.maps.extension.compose.MapboxMap
import com.mapbox.maps.extension.compose.animation.viewport.rememberMapViewportState

public class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
      MapboxMap(
        Modifier.fillMaxSize(),
        mapViewportState = rememberMapViewportState {
          setCameraOptions {
            zoom(2.0)
            center(Point.fromLngLat(-98.0, 39.5))
            pitch(0.0)
            bearing(0.0)
          }
        },
      )
    }
  }
}
Working with Jetpack Compose Extension

The Mapbox Jetpack Compose Extension wraps the MapView. Since not all APIs are exposed through the Jetpack Compose Extension, you can get a reference to the MapView to access the full API surface within a MapEffect.

Use MapEffect with caution
Using MapView APIs within a MapEffect can introduce internal state changes that may conflict with Compose states, potentially leading to unexpected or undefined behavior.

The following example showcases how to turn on debug features using MapEffect:

 
      MapboxMap(modifier = Modifier.fillMaxSize()) {
 
        // Get reference to the raw MapView using MapEffect
 
        MapEffect(Unit) { mapView ->
 
          // Use mapView to access the Mapbox Maps APIs not in the Compose extension.
 
          // Changes inside `MapEffect` may conflict with Compose states.
 
          // For example, to enable debug mode:
 
          mapView.debugOptions = setOf(
 
            MapViewDebugOptions.TILE_BORDERS,
 
            MapViewDebugOptions.PARSE_STATUS,
 
            MapViewDebugOptions.TIMESTAMPS,
 
            MapViewDebugOptions.COLLISION,
 
            MapViewDebugOptions.STENCIL_CLIP,
 
            MapViewDebugOptions.DEPTH_BUFFER,
 
            MapViewDebugOptions.MODEL_BOUNDS,
 
            MapViewDebugOptions.TERRAIN_WIREFRAME,
 
          )
 
        }
Breaking Changes When Using the Jetpack Compose Extension
When using the Mapbox Jetpack Compose Extension, some map plugins—including Compass, Scalebar, Logo, Attribution, and Lifecycle—are replaced by their Jetpack Compose counterparts. As a result, APIs such as mapView.compass, mapView.scalebar, mapView.logo, mapView.attribution, and mapView.lifecycle will not function and may result in runtime exceptions. To avoid these issues, use the corresponding Compose APIs instead.
Layouts in views: Using XML

XML Layout​

Open the activity's XML layout file and add the com.mapbox.maps.MapView element inside your layout:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:mapbox_cameraTargetLat="39.5"
        app:mapbox_cameraTargetLng="-98.0"
        app:mapbox_cameraZoom="2.0"
        app:mapbox_cameraPitch="0.0"
        app:mapbox_cameraBearing="0.0" />

</FrameLayout>
Layouts in views: Instantiating at runtime

Runtime Layout​

Open the activity you'd like to add a map to and use the code below:

 
        // Create a map programmatically and set the initial camera
 
        mapView = MapView(this)
 
        mapView.mapboxMap.setCamera(
 
            CameraOptions.Builder()
 
                .center(Point.fromLngLat(-98.0, 39.5))
 
                .pitch(0.0)
 
                .zoom(2.0)
 
                .bearing(0.0)
 
                .build()
 
        )
 
        // Add the map view to the activity (you can also add it to other views as a child)
 
        setContentView(mapView)

After following on of the methods above, you should be able to press the play button above your code to start the emulator. After spinning up, the emulator should show a map like so:

If your implementation is not working as expected, check our troubleshooting section:

Troubleshooting
  • The username field in the settings.gradle.kts file should always be "mapbox".
  • Click on File > Save All to make sure you haven't missed any changes.
  • Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.
  • If the mapbox library isn't being imported, check the following:
    • Check app/res/values/mapbox_access_token.xml has a token and does not say YOUR_MAPBOX_ACCESS_TOKEN.
    • Make sure you've added the required dependencies to the settings.gradle.kts file and build.gradle.kts match the example snippets seen in Part 2: Add the dependency.
  • Check you've imported the right libraries into the MainActivity file as seen in the example code.
  • Switch virtual devices if you can't get your map to show on the default pixel fold.
  • Check if you have conflicting transitive dependencies. If necessary, you can use exclude group to remove certain dependencies (see Exclude transitive dependencies)_

Next Steps​

Now that you have your map up and running, read our other Android content:

GUIDE
Add a marker to the map

Learn how to add default markers to your map.
GUIDE
How to find a user's location

Learn how to find a user's location, understand privacy rights, and how to add user location features to your app.

Managing the Google Play dependency​

Starting from v11.8.0, the Mapbox Maps SDK for Android depends on Chromium's HTTP client Cronet to enable HTTP/3, and will bring a transitive dependency on Google Play Services, which is used as a provider to get Cronet.

If your application will be deployed in an environment where Google Play Services is not available, it is possible to remove the dependency on Google Play Services from the build through an exclusion, by using this code when adding the dependency:

dependencies {
  implementation('com.mapbox.maps:android:11.8.0') {
    exclude group: 'com.google.android.gms', module: 'play-services-cronet'
  }
}

After doing this there are two alternatives:

  • (Recommended) Have the application depend on cronet-embedded, which will bundle Cronet along with the application during compilation. This will allow the SDK to bring the benefits of HTTP/3, although it will increase the application size.

  • Let the SDK use its fallback HTTP client (no action needed, it will be automatically selected at runtime when Cronet is not available). The fallback HTTP client is still highly performant, but supports only up to HTTP/2.

Additional Developer Resources
Was this page helpful?