Skip To Content ArcGIS for Developers Sign In Dashboard


You will learn: how to build a simple app that displays a 2D map.

With the ArcGIS Runtime SDK for Android, it is easy to create a web mapping app that displays a basemap. In this tutorial, you will use the ArcGIS Runtime SDK for Android to build a simple mapping app to use as a starting template for the other Android tutorials. This tutorial demonstrates the basic SDK setup for Android Studio projects. We recommend developing with Android Studio, the official IDE for Android development from Google. We also recommend installing the SDK dependencies with Gradle, from Esri's Bintray repository. For a more detailed walk-through of these steps, see Develop your first map app.

Before you begin

Make sure you have installed the latest version of Android Studio.


Create a starter project

  1. Run Android Studio and create a new Android Studio project. Set the application name to Starter Project.

  2. Update the project Gradle repositories in the Project view under Gradle Scripts > build.gradle (Project:...) to Esri's Bintray maven repository URL.

    allprojects {
      repositories {
        // *** ADD ***
        maven {
          url ''
  3. Update the app module Gradle dependencies in the Project view under Gradle Scripts > build.gradle (Module: app) to include the ArcGIS Runtime SDK for Android dependency.

    dependencies {
      // *** ADD ***
      implementation 'com.esri.arcgisruntime:arcgis-android:100.8.0'

    Add the Java 8 compile options in the android block:

    android {
      // *** ADD ***
      compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
  4. After updating the Gradle scripts, you will be required to sync the changes. Click the Sync now prompt or click the refresh icon (Sync Project with Gradle Files) in the toolbar.

  5. Update the android manifest file to allow network access, and also to indicate the app uses OpenGL 2.0 or above. The Android manifest file is located in the project hierarchy under app > manifests > AndroidManifest.xml. Be sure to insert these new elements within the <manifest> element.

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-feature android:glEsVersion="0x00020000" android:required="true" />

Add a map to your app

  1. Open the file app > res > layout > activity_main.xml and replace the entire TextView element with a MapView element. If the XML code does not appear, select the Text tab to switch out of design mode to display the XML code in the editor.

      android:layout_height="match_parent" >
  2. Open the file app > java > {} > and create a MapView private member variable.

    public class MainActivity extends AppCompatActivity {
        // *** ADD ***
        private MapView mMapView;
  3. Android Studio will highlight in red the MapView class, which must be imported into the class. Place the pointer on the text highlighted in red and press Alt + Enter on Windows (Option + Enter on Mac) to resolve the symbol.

  4. Add a new setupMap method to your MainActivity class definition. Use Alt + Enter on Windows (Option + Enter on Mac) to resolve the missing symbols Basemap and ArcGISMap.

        private void setupMap() {
          if (mMapView != null) {
              Basemap.Type basemapType = Basemap.Type.STREETS_VECTOR;
              double latitude = 34.0270;
              double longitude = -118.8050;
              int levelOfDetail = 13;
              ArcGISMap map = new ArcGISMap(basemapType, latitude, longitude, levelOfDetail);
  5. Add the following code to the existing onCreate method, after the call to setContentView.

     protected void onCreate(Bundle savedInstanceState) {
         // *** ADD ***
         mMapView = findViewById(;
  6. Override the onPause, onResume, and onDestroy methods of the MainActivity class:

    protected void onPause() {
        if (mMapView != null) {
    protected void onResume() {
        if (mMapView != null) {
    protected void onDestroy() {
        if (mMapView != null) {
  7. Run your app and test the code in the Android emulator to see the map.

Congratulations, you're done!

Your app should run and display the basemap. Compare your solution with our completed solution project. We will refer back to this project as the starting template for many of the Android tutorials.


License your Runtime app

During development you will see a watermark on your map. Before you deploy your ArcGIS Runtime app into production, you're required to license it.

  1. Log into your ArcGIS Developer Account and go to your dashboard.

  2. Find your Runtime Lite license key and copy it.

  3. Create an app_settings.xml resource file to hold your license key. It is a good app development practice to separate configuration from the code. It is also a best practice to not include sensitive information in your source code repository, so you may want to exclude this file from source control.

    1. In the Project view, right-click app and choose New > Android resource file.
    2. Set the File name to app_settings.xml.
    3. In Resource type choose Values.
    4. Leave the other options as default (Source set as main, Directory name as values) and click OK.
    5. In the new values file you created, add the following string elements:
    <?xml version="1.0" encoding="utf-8"?>
      <!-- *** ADD *** -->
      <string name="arcgis_license_key">YOUR_LICENSE_KEY</string>
    • Replace YOUR_LICENSE_KEY with the value copied from your dashboard.
  4. In file app > java > {} >, find the setupMap method and add a call to ArcGISRuntimeEnvironment.setLicense with a reference to the string resource added in the prior step.

        private void setupMap() {
          if (mMapView != null) {
          // *** ADD ***
  5. Run your app and test the code in the Android emulator to see the map rendered without the developer watermark.

Explore basemaps

ArcGIS Online hosts a wide variety of basemaps that you can use in your applications. Many of these can be referenced with type constants. Try setting the basemapType variable to one of the other options available, such as STREETS_NIGHT_VECTOR.

    Basemap.Type basemapType = Basemap.Type.STREETS_NIGHT_VECTOR;

Change viewpoint

Try different settings for the initial viewpoint by changing the latitude, longitude, and level of detail.

Create a 3D starter app

To create a 3D app, replace MapView with SceneView. Scenes require configuring a Camera to set the viewpoint. Try setting up a camera to create an aerial perspective that matches your 2D view point.

  1. Open the file app > res > layout > activity_main.xml and replace the MapView element with SceneView. Change the ID to sceneView.

      android:layout_height="match_parent" >
  2. In file app > java > {} >, replace MapView with SceneView and rename the mMapView variable to mSceneView everywhere in your code.

        private SceneView mSceneView;
  3. Replace the entire setupMap method with the code below to construct a 3D scene with a camera that presents a perspective similar to your 2D map.

    private void setupMap() {
        if (mSceneView != null) {
            double latitude = 33.8610;
            double longitude = -118.8080;
            double altitude = 25000.0;
            double heading = 0.1;
            double pitch = 45.0;
            double roll = 0.0;
            ArcGISScene scene = new ArcGISScene();
            Camera camera = new Camera(latitude, longitude, altitude, heading, pitch, roll);
  4. Update the onCreate method to connect the mSceneView variable with the SceneView layout element.

         // *** UPDATE ***
         mSceneView = findViewById(;
  5. Update the android manifest file to use OpenGL 3.0. The Android manifest file is located in the Project view under app > manifests > AndroidManifest.xml.

    <uses-feature android:glEsVersion="0x00030000" android:required="true" />
  6. Run your app and test the code in the Android emulator to see the map rendered in 3D. Compare your solution with our completed solution project.