> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/ja/llms.txt) # 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](https://docs.mapbox.com/android/maps/). This tutorial shows the steps necessary to get the demo app running on an android emulator via Android Studio so you can view and interact with the examples. To start building your own app using the Maps SDK, see our [Get Started with the Maps SDK for Android](https://docs.mapbox.com/android/maps/guides/install/) guide. ## Prerequisites Before you begin, make sure you have the following installed: - **Android Studio** — Download the latest version from the [Android Studio website](https://developer.android.com/studio). - A **Mapbox account** — [Sign up](https://account.mapbox.com/auth/signup) or [log in](https://console.mapbox.com). Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/ja/help/ja/assets/medias/tutorials--maps-sdk-anrdoid-examples-app--launch-90e9afedacb8dd9888d3803e53e89a7f.webm). ## 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](https://account.mapbox.com/auth/signup) and or [log in to your existing account](https://console.mapbox.com). ### 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](https://console.mapbox.com/account/access-tokens/) 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. **Mac/Linux** To set 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. ```sh ... export MAPBOX_ACCESS_TOKEN=pk.12345... ... ``` 3. Save your `.zshrc` file and open a new terminal. **If you are using `Bash` instead of `Zsh` as your shell, edit `~/.bashrc` instead.** **Windows** To set the environment variable on a Windows computer, follow these steps: - Open System Properties 1. Press `Win + S`, type **Environment Variables**, and select **Edit the system environment variables**. 2. In the **System Properties** window, click the **Environment Variables** button. - Add a New User or System Variable 1. In the **Environment Variables** window, under **User variables** (for the current user) or **System variables** (for all users), click **New**. 2. In the **New Variable** dialog: - Enter `MAPBOX_ACCESS_TOKEN` as the **Variable name**. - Enter your public token as the **Variable value**. 3. 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. ```sh $ echo $MAPBOX_ACCESS_TOKEN pk.12345... ``` ## Clone the `mapbox-maps-android` repository The examples app lives in the `app` module of the **Maps SDK for Android** code repository, [available on GitHub](https://github.com/mapbox/mapbox-maps-android). Use git to clone the repository on your development machine. ```nix $ 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. After opening the project, Android Studio will automatically begin syncing and downloading dependencies in the background. This may take several minutes the first time. You can check progress in the **Build** panel at the bottom of the screen. If it is not open, you can open it via **View > Tool Windows > Build**. 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. ![Screenshot of the file picker showing which file to open](https://docs.mapbox.com/help/ja/assets/ideal-img/tutorials--maps-sdk-android-examples-app--studio.f6ac083.480.png) ### 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](https://docs.mapbox.com/android/maps/guides/user-location/), [markers and annotations](https://docs.mapbox.com/android/maps/guides/annotations/), [camera control and animation](https://docs.mapbox.com/android/maps/guides/camera-and-animation/), and [offline use](https://docs.mapbox.com/android/maps/guides/offline/). Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/help/ja/help/ja/assets/medias/tutorials--maps-sdk-anrdoid-examples-app--launch-90e9afedacb8dd9888d3803e53e89a7f.webm). When opening a map example on Android 15 or newer, you may see a warning about 16 KB page size compatibility. This is expected — the default Maps SDK artifacts do not include 16 KB page size support. You can dismiss the warning and continue using the examples app. 16 KB compatible artifacts are available for use in your Android apps, see [Get Started with the Maps SDK for Android](https://docs.mapbox.com/android/maps/guides/install/#part-2-add-the-dependency) for instructions on how to include them in your project. 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 and try running the app again. ![](https://docs.mapbox.com/help/ja/assets/ideal-img/tutorials--maps-sdk-ios-examples-app--black-screen.5d2d3f4.480.png) 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 YOUR_MAPBOX_ACCESS_TOKEN ``` 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`, ![Screenshot from Xcode showing example source code](https://docs.mapbox.com/help/ja/assets/ideal-img/tutorials--maps-sdk-android-examples-app--code.5a0dff9.480.png) ## 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](https://docs.mapbox.com/android/maps/) to level up, and share questions and lessons learned in the [Mapbox Developer Discord](https://discord.com/invite/uMpcC5RmJh). ### Jetpack Compose Examples App This tutorial shows how to load the **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. ### What we covered - Verifying prerequisites (Android Studio and JDK 11+) - Configuring your public access token as an environment variable - Cloning the `mapbox-maps-android` repository - Opening the `mapbox-maps-android` project in Android Studio - Running the Maps SDK for Android Examples app - Exploring the source code and customizing the examples ### Relevant Links See our guides and examples below to learn more about the Maps SDK for Android. > **Related content (guide): [Get Started with the Maps SDK for Android](https://docs.mapbox.com/android/maps/guides/install/)** > > This guide walks you through integrating the Maps SDK for Android into your application, configuring your credentials and adding a map to your app. > **Related content (example): [Add a marker to the map](https://docs.mapbox.com/android/maps/examples/default-point-annotation/)** > > This example shows you how to add a marker to a Point of Interest (POI), using a `default point annotation`. > **Related content (guide): [User location](https://docs.mapbox.com/android/maps/guides/user-location/)** > > This guide shows you how to access the user's location from your app.