ArcGIS Runtime SDK for Android

Develop your first map app with Kotlin

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.

You will use Kotlin, an official language for Android development. Alternatively, you can follow the same tutorial using Java.

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

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.
  3. Check the Include Kotlin support check box.

    Optionally, change the Company domain and Project location, and click Next.

    Create New Project dialog box in Android Studio
  4. 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.
  5. In the Add an Activity to Mobile dialog, click Empty Activity, then click Next.
  6. 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. The app module contains an Activity written using Kotlin. 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.

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 Kotlin code defining the default activity of your app. (Kotlin code is still contained in a subfolder of a java folder).

  2. Add the following code to the onCreate method, after the existing call to setContentView:
    // create a map with the BasemapType topographic
    val map = ArcGISMap(Basemap.Type.TOPOGRAPHIC, 34.056295, -117.195800, 16)

    This code creates an ArcGISMap with a specific predefined Basemap.Type displaying a general-use topographic map, centered at a specific set of coordinates, and zoomed to a specific level of detail.

  3. Android Studio will highlight in red the ArcGISMap and Basemap classes, which must be imported into the activity class. Place the pointer on the ArcGISMap text highlighted in red and press Alt+Enter to resolve the symbol. Choose import. Repeat this step to import Basemap.
    You should now have the following import statements at the top of your class.
    import com.esri.arcgisruntime.mapping.ArcGISMap
    import com.esri.arcgisruntime.mapping.Basemap
  4. Add the following code to the onCreate method, after the previous line you added:
    // set the map to be displayed in the layout's MapView
    mapView.map = map

    This code sets the ArcGISMap you created into the MapView you defined in the layout.

  5. Android Studio will highlight mapView. Place the pointer on mapView and press Alt+Enter to resolve the symbol. This time you should see more than one option to import. Choose kotlinx.android.synthetic.main.activity_main.mapView.

    The kotlin android extensions plugin (part of your project by default when you add Kotlin support) generates synthetic properties, so you can access views in the layout XML as if they were properties of the class. Android Studio will import all of the named views in the layout by adding a general import.

    import kotlinx.android.synthetic.main.activity_main.*

  6. 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 fun onPause() {
        super.onPause()
        mapView.pause()
    }
    
    override fun onResume() {
        super.onResume()
        mapView.resume()
    }
    
    override fun onDestroy() {
        super.onDestroy()
        mapView.dispose()
    }

You have now completed the steps to add an ArcGIS Runtime SDK for Android map to your new Android Kotlin 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 with Kotlin.