Get Started with the Maps SDK for Android | Maps SDK | Android Docs (original) (raw)

This guide describes the steps to install the most recent version of the Mapbox Maps SDK for Android, configure your Android app to use the SDK, and initialize a map.

Prerequisites​

Part 1: Configure your credentials​

Before starting to develop your application with the Maps SDK, you'll need to create and configure your credentials.

Step 1: 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.

  1. Open your project folder or create a new project in Android Studio.
  1. Locate the resource folder:
  1. Create a new resource file:
  1. In the new file, copy and paste the code snippet below.

Your public access token is now available for use in your Android project. You will access it via the string resource you created in your implementation code.

Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime

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 2: (Optional) Configure permissions​

If you need to access the user's location to show it on the map, follow the steps below. If you do not need to access the user's location, skip to Part 2: Add the dependency.

  1. Open the Android Manifest.
    • In the project explorer, go to app > manifests > AndroidManifest.mxl.
  2. Determine the level of location access you need.
    • If you only need general user location access, copy the first line of code below - the ACCESS_COARSE_LOCATION permission.
    • If you also need access to more precise location data, copy the entire code snippet, including the ACCESS_FINE_LOCATION permission. The ACCESS_FINE_LOCATION will not work without also requesting ACCESS_COARSE_LOCATION access.
  3. Add the permissions you copied to the Android Manifest.
    • This code should be added to the top of AndroidManifest.xml, below the opening manifest tag and above the opening <application> tag.

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​

Step 1: Add the Mapbox Maven Repository​

Now that you have your credentials, add the dependency to your 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 by following these steps:

  1. In the project explorer, go to Gradle Scripts > settings.gradle file under the Gradle Scripts section and open the 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:

Step 2: Add Maps SDK Dependencies​

  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:
  2. Add the Mapbox SDK for Android dependency in the same module-level (for example app > GradleScripts > build.gradle.kts) Gradle configuration file and add the following line to the dependencies section:
  3. (Optional) If you are using Jetpack Compose to build your app, you will need to add the following to your app/build.gradle.kts configuration file:
  1. Because you've edited your Gradle files, click File > Sync Project with Gradle Files in Android Studio.

Part 3: Add a map​

Now add a map to your application. This can be accomplished by either using Jetpack Compose or in Android View:

Jetpack Compose

Android View

With the Maps SDK for Android compose extension, you can add a map to your composable:

  1. Make sure you added the Mapbox compose extension to your dependencies (see optional Step #6 above)
  2. Go to app > kotlin+java and open the top folder.
  3. Inside the folder, open the MainActivity.kt file.
  4. Delete everything inside the file except the package import on the first line.
  5. Lastly, copy and paste the following code block from below and delete the package import line from the example.

This code will create an interactable globe centered over the United States and set the view's zoom level to 2.

Now save your work and start the emulator. Once the emulator is finished loading, you should see an interactable globe:

If your implementation is not working as expected, view the following troubleshooting section:

Next Steps​

With the Maps SDK installed and a minimal map rendering in your app, you can explore additional features of the SDK:

You can also explore example code and tutorials:

Additional Developer Resources