Run the Maps SDK for Android Examples App
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:
-
Open your
~/.zshrcfile in a text editor. (.zshrcis located in your home directory.) -
Add a new
exportstatement, settingMAPBOX_ACCESS_TOKENto your public token.
...
export MAPBOX_ACCESS_TOKEN=pk.12345...
...
- Save your
.zshrcfile and open a new terminal.
If you are using Bash instead of Zsh as your shell, edit ~/.bashrc instead.
To set the environment variable on a Windows computer, follow these steps:
- Open System Properties
- Press
Win + S, type Environment Variables, and select Edit the system environment variables. - In the System Properties window, click the Environment Variables button.
- Add a New User or System Variable
- In the Environment Variables window, under User variables (for the current user) or System variables (for all users), click New.
- In the New Variable dialog:
- Enter
MAPBOX_ACCESS_TOKENas the Variable name. - Enter your public token as the Variable value.
- Enter
- Click OK to save the new variable.
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
- Launch Android Studio.
- Click the Open button on the splash screen or choose File > Open... in the menu.
- Use the file picker to navigate to and select the
mapbox-maps-androidrepository you cloned earlier. - 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.
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.
<?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.