Develop your first map app

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).

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. Under Quick Start, 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.

    Optionally, change the Company Name and Project Location, and click Next.

    Create New Project dialog box in Android Studio
  3. Leave the default Phone and Tablet option selected, choose API 16: Android 4.1 or later from the Minimum SDK drop-down list, and click Next. (Note that different Android Studio versions may have different default Android SDK versions.)
  4. Click Empty Activity, and click Next.
  5. Leave the default names in the remainder of the wizard and 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 gradle build script for the whole project.

    This opens the gradle build script for your application module. If you are unfamiliar with the Gradle build system, see Build System Overview.

  2. In the repositories section of the script, add a new section maven, with a value url 'https://esri.bintray.com/arcgis'. The full section should now look like the code below:
    allprojects {
        repositories {
            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>).
  4. In the dependencies section of the script, add a new value "compile 'com.esri.arcgisruntime:arcgis-android:100.1.0'". The dependencies section 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 { 
      compile 'com.esri.arcgisruntime:arcgis-android:100.1.0' 
      compile fileTree(dir: 'libs', include: ['*.jar'])
      [more dependencies...]
    }
  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. 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.

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, and 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 RelativeLayout. 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 Relative Layout and User Interface documentation from Google.
    • The second is a TextView, a child of the relative 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="fill_parent"
      android:layout_height="fill_parent" >
    </com.esri.arcgisruntime.mapping.view.MapView>

For a more comprehensive understanding of the declarative approach to user interface (UI) design, see Declaring Layout.

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 = (MapView) 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. 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 code to override the onPause and onResume methods of the activity, and pause and resume the MapView when those methods are called:
    @Override 
    protected void onPause(){
      mMapView.pause();
      super.onPause();
    }
    
    @Override 
    protected void onResume(){
      super.onResume();
      mMapView.resume();
    }

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. On the Android Studio toolbar, click Run.
  2. On the Choose Device dialog box, choose the device or emulator you're going to use, and 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:

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.