Develop your first map app with Java

This tutorial guides you through the process of creating a basic mapping app with the ArcGIS Runtime SDK for Android, that displays a map using a specific initial map extent, using the Android Studio integrated development environment (IDE).

This tutorial was written for Android Studio version 3.1.2—different Android Studio versions may differ slightly in the names of user interface captions or choices. Esri recommends using the latest stable release of Android Studio.

You will use the Java language to develop the app. Alternatively, you can follow the same tutorial using Kotlin.

You can view the completed code as a sample in the Display a Map sample.

Prerequisites

Before you start, make sure you've done the following:

Create a new project in Android Studio

When you start Android Studio, the Welcome screen is displayed. From here, you can create a new Android app project.

  1. Click Start a new Android Studio project.

    If you already have a project open, you can click File > New > New Project.

  2. In the Application name text box, type Display map.

    Make sure the Include Kotlin support box is unchecked. (To use Kotlin instead of Java in your map app, see Develop your first map app with Kotlin.)

    If you wish, change the Company domain and Project location, and click Next.

    Create New Project dialog box in Android Studio
  3. In the Target Android Devices dialog, leave the Phone and Tablet option selected, and choose API 19: Android 4.4 or later from the Minimum SDK drop-down list, then click Next.
  4. In the Add an Activity to Mobile dialog, click Empty Activity, then click Next.
  5. Leave the default options in the remainder of the wizard, then click Finish.

    A new Android app project opens, showing a default layout.

You have now successfully created an Android project containing an app module. Next you'll add the ArcGIS Runtime SDK for Android dependency.

Add the ArcGIS Runtime SDK for Android AAR dependency

Here you'll update the gradle build script to add the ArcGIS Runtime SDK for Android dependency to your app module. This will automatically download the Android Archive (AAR) package from the Esri public Bintray Maven repository when you build your app.

Android is a permissions-separated operating system. You'll also add permissions for the functionality your app requires.

  1. In the Android project view window, under Gradle Scripts, double-click build.gradle (Project: <project name>).

    This opens the top-level build file that applies to all modules in your project. If you are unfamiliar with the Gradle build system, see Build System Overview.

  2. In the allprojects/repositories block of the script, add a new maven block as shown, with a value url 'https://esri.bintray.com/arcgis'. The full section should now look like the code below:
    allprojects {
      repositories {
        google()
        jcenter()
        
        // Add the Esri public Bintray Maven repository
        maven {
            url 'https://esri.bintray.com/arcgis'
        }
      }
    }

    This directive tells Gradle where to look for the ArcGIS Runtime SDK for Android dependencies, by specifying a Maven repository URL.

  3. In the Android project view window, under Gradle Scripts, double-click build.gradle (Module: <module name>).

    This opens the module-level build file that applies to the single application module in your project. If you are unfamiliar with the Gradle build system, see Build System Overview.

  4. In the dependencies block of the script, add a new line "implementation 'com.esri.arcgisruntime:arcgis-android:100.3.0'". The dependencies block should now look like the code below—the exact list of dependencies present will depend on the version of Android Studio and the project settings chosen:
    dependencies { 
      implementation 'com.esri.arcgisruntime:arcgis-android:100.3.0' 
      implementation fileTree(dir: 'libs', include: ['*.jar'])
      [more dependencies...]
    }

    (Prior to Android Studio version 3.0, you would have used a compile value instead of implementation.)

  5. In the Android Studio toolbar, click Sync Project with Gradle Files. Alternatively, when you see the Gradle files have changed since last project sync message at the top of the gradle script window, click Sync Now.
    Sync now gradle message in Android
  6. In the Android project view window, under app > manifests, double-click AndroidManifest.xml.

    This opens the manifest file for your app.

  7. Add the following XML elements as children of the existing manifest:
    <uses-permission android:name="android.permission.INTERNET" /> 
    <uses-feature android:glEsVersion="0x00020000" android:required="true" />

    This informs the Android launcher that your app requires permission to access the Internet. If an app is running on Android API level 23 or above, normal permissions are requested at install time—internet access is a normal permission, so no additional work is required to enable this permission. It also indicates that your app requires the OpenGL version 2.0 software feature for the app to run and display a map view. Most apps you develop with the ArcGIS Runtime SDK for Android will need this feature and a minimum of this permission. For more information, see the Android Developers topics Android Permissions and Uses Feature Element.

You've added a dependency to the ArcGIS Runtime SDK for Android AAR to your app module. Next, you'll add a map showing a map service to the app and set up an initial extent for that map.

Use Java 8 language features

Android Studio 3.0 introduced support for a subset of Java 8 language features that vary by platform version. For example, lambda expressions and method references can be used in Android Studio 3.0 modules with any minSdkVersion value. These language features are used throughout the ArcGIS Runtime SDK for Android documentation and samples, so to ensure these code examples compile if used in your app, you will set the compatibility of your module to use Java 8 language features.

  1. In the Android project view window, under Gradle Scripts, double-click build.gradle (Module: <module name>) to open the app module gradle build script again.
  2. Add the following instruction to the existing android block.
    android {
      [...]
      // Add below lines to set compatibility with Java 8 language features for an Android app module.
      compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
      }
    }

    You may now need to sync the gradle script again.

Tip:

You can also configure this in the Module Properties tab of the Project Structure dialog box (click File, then Project Structure).

If you have problems using supported Java 8 language features, make sure you have the latest Android Studio updates, and your project uses the Android plugin version 3.0.0 or higher. This is specified in the com.android.tools.build.gradle dependency in the top level gradle build script.

Add a MapView to your layout

Now that you've created an app with an ArcGIS Runtime SDK for Android AAR dependency, the next step is to add a MapView to the activity layout.

  1. In the Android project view window, under app, click res > layout, then double-click activity_main.xml.

    This opens the Preview view of the central content for the main activity layout. Note that depending on the exact Android Studio version you are using and the initial activity template you chose, the project may contain multiple layout XML files—for example if you chose the Basic Activity template, you may need to instead open the content_main.xml layout.

  2. At the lower left of the window, click Text to show the XML view of the layout if it's not already shown.

    By default, there are two tags in the layout XML file.

    • The first is an Android ConstraintLayout. This is a view that can show other views inside itself. It arranges its children views relative to each other. For more information, see the Constraint Layout and User Interface documentation from Google.
    • The second is a TextView, a child of the constraint layout, displaying the text "Hello world!".

  3. Select the entire TextView XML element and replace it with a MapView element as follows:
    <com.esri.arcgisruntime.mapping.view.MapView
      android:id="@+id/mapView"
      android:layout_width="match_parent"
      android:layout_height="match_parent" >
    </com.esri.arcgisruntime.mapping.view.MapView>

For a more comprehensive understanding of the declarative approach to user interface (UI) design, see Declaring Layout. Additionally, there are different types of layout constraint attributes that are commonly used with the ConstraintLayout; refer to the Constraint Layout documentation for more information.

Set a map on the MapView

By default, a MapView does not display anything, so the next step is to define a map to be displayed. You will specify that the map shows a worldwide topographic basemap from ArcGIS Online. As it's often more useful for an app to initially display a specific region rather than its entire extent, you'll also set the map to zoom in to a specific center point—showing the Esri campus in Redlands, California.

  1. In the Android project view window, under app, click java > [package name], and double-click MainActivity.

    This opens the Java code defining the default activity of your app.

  2. Add the following class variable declaration to the top of the MainActivity class:
    private MapView mMapView;
  3. Android Studio will highlight in red the MapView class, which must be imported into the class. Place the pointer at the line with text highlighted in red and press Alt+Enter to resolve the symbol. Choose to import com.esri.arcgisruntime.mapping.view.MapView.
    import com.esri.arcgisruntime.mapping.view.MapView;
  4. Add the following code to the onCreate method, after the existing call to setContentView:
    mMapView = findViewById(R.id.mapView);
    ArcGISMap map = new ArcGISMap(Basemap.Type.TOPOGRAPHIC, 34.056295, -117.195800, 16); 
    mMapView.setMap(map);
    Note:

    You'll need to import com.esri.arcgisruntime.mapping.ArcGISMap and com.esri.arcgisruntime.mapping.Basemap.

    This code gets a reference to the MapView defined in the layout. (Prior to Android Studio version 3.0, the object returned from findViewById must be explicitly cast to the MapView type.) An ArcGISMap is created with a specific predefined Basemap.Type, centered at a specific set of coordinates, and zoomed to a specific level of detail. The ArcGISMap is then set into the MapView.

  5. Add the following methods to the MainActivity class, to override the onPause, onResume and onDestroy methods inherited from the parent activity class which pause, resume and dispose the MapView when those methods are called:
    @Override 
    protected void onPause(){
      mMapView.pause();
      super.onPause();
    }
    
    @Override 
    protected void onResume(){
      super.onResume();
      mMapView.resume();
    }
    
    @Override
    protected void onDestroy() {
      super.onDestroy();
      mMapView.dispose();
    }

You have now completed the steps to add an ArcGIS Runtime SDK for Android map to your new Android app. You are now ready to build and test your app.

Build and run the app

To test your app, you need to have either a connected device ready for debugging or an emulator set up and started. To find our more, see the Android documentation Using the emulator or Using hardware devices.

  1. From the Android Studio toolbar, click Run.
  2. In the Connected Devices dialog box, choose the device or emulator you're going to use, then click OK.
  3. When the app opens on your device, it shows a street map centered on Redlands, California. You can double-tap the map to zoom in.

When you create a new project, Android Studio automatically creates a run configuration to launch the app on your device. You'll see something similar to the following screen shot.

Tip:

If the app runs but the map is blank, then check that the android.permission.INTERNET permission was correctly added to the Android manifest.

Display map screen shot showing the map

That's it, you've completed your first ArcGIS Runtime SDK for Android app.

Don't forget that you can view the completed code in our Display a Map sample on GitHub.