Skip to main content

Run the Maps SDK for Android Examples App

Additional Developer Resources

Mapbox provides a robust Examples app to show various best practices and techniques for building with the Maps SDK for Android. This tutorial shows the steps necessary to get the demo app running on an android emulator via Android Studio in your development environment.

Configure 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 or log in to your existing account.

Step 2: Configure your public token​

The examples app requires a Mapbox access token, which is compiled into the app and used to request Mapbox resources over the network when the app is running. You can use your default public token for this value.

This token must be configured as an environment variable in your development environment before running the examples app.

The steps for configuring environment variables vary between platforms. The steps to create and set an environment variable may vary depending on your development environment.

To set these the environment variable on a Mac or Linux computer, follow these steps:

  1. Open your ~/.zshrc file in a text editor. (.zshrc is located in your home directory.)

  2. Add a new export statement, setting MAPBOX_ACCESS_TOKEN to your public token.

.zshrc
...
export MAPBOX_ACCESS_TOKEN=pk.12345...
...
  1. Save your .zshrc file and open a new terminal.

If you are using Bash instead of Zsh as your shell, edit ~/.bashrc instead.

Confirm the environment variable​

Confirm that the environment variable is properly configured by using echo in your terminal.

You will see your public access token starting with pk if MAPBOX_ACCESS_TOKEN is properly configured.

$echo $MAPBOX_ACCESS_TOKEN
pk.12345...

Clone the mapbox-maps-android repository​

The examples app lives in a the Apps/Examples directory of the Maps SDK for Android code repository, available on GitHub. Use git to clone the repository on your development machine.

$git clone git@github.com:mapbox/mapbox-maps-android.git

Open mapbox-maps-android in Android Studio​

  1. Launch Android Studio.
  2. Click the Open button on the splash screen or choose File > Open... in the menu.
  3. Use the file picker to navigate to and select the mapbox-maps-android repository you cloned earlier.
  4. Click the trust button in the prompt that appears.

The Mapbox Maps Android project includes several configurations, the Examples app is referred to as app. Be sure that app is selected in the configuration dropdown.

Run the App​

Be sure you have an Android emulator selected in the device menu, then click the ▶️ (Run) button. Android Studio will build and run the Maps SDK for Android examples app on your emulator.

You will see a listing with the title and description for each example, grouped by category. Tap each example to explore and learn the capabilities of the Mapbox Maps SDK for Android, including user location, markers and annotations, camera control and animation, and offline use.

Check your public access token if you see a black screen

If the app loads but you see a black background where the map should be, this means that the public access token was not properly configured and network requests for Mapbox resources are failing.

Confirm that you have configured your public access token correctly in app/res/values/mapbox_access_token.xml and try running the app again.

A build script reads the MAPBOX_ACCESS_TOKEN environment variable you set in Configure Credentials and creates a file at app/res/values/developer-config.xml. Try opening this file to confirm that it contains your public token.

app/res/values/developer-config.xml
<?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 it does not contain your public token, manually add it, save the file, and try building the app again.

Explore the source code​

Each example has a separate source code file, and you can explore the source code as you preview the examples in the emulator to learn how each example works. You may also want to change values and hot reload the app to change the functionality.

A good first customization might be to update the initial camera settings in SimpleMapActivity.kt, the source code for the Display a map view example. See if you can make the map initialize on a different location by updating the center coordinates in CameraOptions.Builder(). You can also experiment with different values for zoom, bearing, and pitch,

Next steps​

With the Examples app running locally, you're ready to start exploring all the possibilities of the Maps SDK for Android as you build maps into your Android apps. Be sure to explore the SDK's documentation to level up, and share questions and lessons learned in the Mapbox Developer Discord.

Jetpack Compose Examples App​

The examples app presented in this guide includes Android View examples. Jetpack Compose examples are included under another app the mapbox-maps-android repository named compose-app. You can run this app with the same instructions as the default examples app.

Additional Developer Resources
Was this page helpful?