Overview

You will learn: how to create a simple starter app that displays a basemap. This template project will be used in subsequent labs.

With the ArcGIS Runtime SDK for Android, it is easy to create a web mapping app that displays a basemap. In this lab, 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 labs. This lab 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.

Download and install the ArcGIS Runtime SDK for Android by following the instructions at Install the SDK.

You will need a developer subscription to download the SDK. If you haven't already, sign up for free.

Steps

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 'https://esri.bintray.com/arcgis'
        }
    
  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.4.0'
    

    Add the Java 8 compile options:

    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.

    <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>
    
  2. Open the file app > java > {your.package.name} > MainActivity.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.09042;
              double longitude = -118.71511;
              int levelOfDetail = 11;
              ArcGISMap map = new ArcGISMap(basemapType, latitude, longitude, levelOfDetail);
              mMapView.setMap(map);
          }
        }
    
  5. Add the following code to the existing onCreate method, after the call to setContentView.

     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_main);
         // *** ADD ***
         mMapView = findViewById(R.id.mapView);
         setupMap();
    
  6. Override the onPause, onResume, and onDestroy methods of the MainActivity class:

    @Override
    protected void onPause() {
        if (mMapView != null) {
            mMapView.pause();
        }
        super.onPause();
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        if (mMapView != null) {
            mMapView.resume();
        }
    }
    
    @Override
    protected void onDestroy() {
        if (mMapView != null) {
            mMapView.dispose();
        }
        super.onDestroy();
    }
    
  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 labs.

Challenge

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

    <com.esri.arcgisruntime.mapping.view.SceneView
      android:id="@+id/mapView"
      android:layout_width="match_parent"
      android:layout_height="match_parent" >
    </com.esri.arcgisruntime.mapping.view.SceneView>
    
  2. In file app > java > {your.package.name} > MainActivity.java, replace MapView with SceneView and rename the mMapView variable to mSceneView everywhere in your code.

        private SceneView mSceneView;
    
  3. Update the setupMap method to construct a 3D scene with a camera the presents a perspective similar to your 2D map.

    private void setupMap() {
        if (mSceneView != null) {
            double latitude = 33.8210;
            double longitude = -118.6778;
            double altitude = 44000.0;
            double heading = 0.1;
            double pitch = 30.0;
            double roll = 0.0;
    
            ArcGISScene scene = new ArcGISScene();
            scene.setBasemap(Basemap.createStreets());
            mSceneView.setScene(scene);
            Camera camera = new Camera(latitude, longitude, altitude, heading, pitch, roll);
            mSceneView.setViewpointCamera(camera);
        }
    }