Install and set up

Before installing ArcGIS Runtime for Android, make sure your development machine meets the system requirements. A minimum Android API version is required for any target device on which your app will run. For more information, see system requirements.

We recommend installing with Gradle, which will install the needed dependencies and SDK binaries from Esri's Maven repository. If you are unable to make use of Gradle, you can instead download the SDK and then add dependencies to your project manually by including the AAR library and dependency artifacts.

Get the API with Gradle

Perform the following set up steps in an existing Android Studio project, or create a new project.

1. In your settings.gradle file, within the repositories block of the dependencyResolutionManagement block, add a maven block and specify the URL of Esri's Maven repository. Esri's repository is not open source and therefore not available from google() or mavenCentral(), so you must specify this URL.

   settings.gradle

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           maven {
               url 'https://esri.jfrog.io/artifactory/arcgis'
           }
       }
   }

2. In your module-level build.gradle file, within the dependencies block, add the ArcGIS Runtime SDK for Android dependency to your app.

   build.gradle

   Use dark colors for code blocks

   1
   2
   3
   4
   dependencies {
       . . .
       implementation 'com.esri.arcgisruntime:arcgis-android:100.15.4'
   }

3. In your module-level build.gradle file, within the android block, make sure you have the following directive to set compatibility with Java 8 language features:

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   android {
     . . .
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
     . . .
   }

4. In your module-level build.gradle file, within the android block, make sure you have a buildFeatures block that enables view binding. For more information on view binding, see https://developer.android.com/topic/libraries/view-binding.

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   android {
       . . .
       buildFeatures {
           viewBinding true
       }
       . . .
   }

5. In your module-level build.gradle file, within the android block, make sure you have a packagingOptions block that excludes duplicates of the META-INF\DEPENDENCIES file. This setting will prevent a compiler error that occurs if you try to include the same file in the META-INF directory more than once in the output. For more information on packaging options, see https://developer.android.com/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions.

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   android {
       . . .
       packagingOptions {
           exclude 'META-INF/DEPENDENCIES'
       }
       . . .
   }

Get the API manually

If you are unable to make use of the public Gradle repository, you can instead download the SDK and add the dependencies to your project manually by including the local AAR and all dependency artifacts. On the Downloads page, you can also download a separate PDF of the Guide documentation.

1. Click the downloads link, and select the latest version of ArcGIS Runtime SDK for Android.
2. Unzip the downloaded archive to a location on your development machine.

Manually add dependencies to the ArcGIS Runtime SDK for Android or use other resources contained in the download. The Android library module (.aar), found in the libs folder, contains the API jar libraries arcgis-android-api and its third-party dependencies and core native libraries.

Setting up ArcGIS Android API to work with local Maven repository

The following setup steps assume that you are working in a development environment that is disconnected from the internet. For example, behind a firewall that doesn't allow access to Maven repositories that are hosted on the internet. If you are developing with internet access, please follow Get the API with Gradle instead.

The following steps describe the setup with a Maven repository that is on your local machine; however, they can be applied in a similar way if you have a Maven server set up on your network.

Deploy SDK and its dependencies to your computer

1. Obtain the arcgis-runtime-sdk-android-100.15.4.zip file in whatever way is compatible with the security measures at your work environment.

2. Extract the contents of the archive to a location on disk.

3. From the extracted location, copy the contents of the libs/aar directory to the following location on your disk. (Note that your local Maven repo is the directory tree rooted at .m2\repository in your user directory.)

   mac: /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.4/

   Windows: %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.4\

4. Your full directory path should resemble the following:

   mac (2 files):

   /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.4/arcgis-android-100.15.4.aar

   /Users/[user-name]/.m2/repository/com/esri/arcgisruntime/arcgis-android/100.15.4/arcgis-android-100.15.4.pom

   Windows (2 files):

   %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.4\arcgis-android-100.15.4.aar

   %USERPROFILE%\.m2\repository\com\esri\arcgisruntime\arcgis-android\100.15.4\arcgis-android-100.15.4.pom

5. A list of these dependencies and the URLs from where they may be downloaded is below. You should obtain them in whatever way is compatible with the security measures at your work environment.

   • gson 2.9.0: https://search.maven.org/artifact/com.google.code.gson/gson/2.9.0/jar
   • androidx.browser 1.4.0: https://maven.google.com/web/index.html?q=browser#androidx.browser:browser:1.4.0
   • androidx.localbroadcastmanager 1.1.0: https://maven.google.com/web/index.html?q=localbroadcastmanager#androidx.localbroadcastmanager:localbroadcastmanager:1.1.0
   • httpcore5 5.0.4: https://search.maven.org/artifact/org.apache.httpcomponents.core5/httpcore5/5.0.4/jar
   • httpcore5-h2 5.0.4: https://search.maven.org/artifact/org.apache.httpcomponents.core5/httpcore5-h2/5.0.4/jar
   • slf4j-api 1.7.32: https://search.maven.org/artifact/org.slf4j/slf4j-api/1.7.32/jar
   • commons-codec 1.15: https://search.maven.org/artifact/commons-codec/commons-codec/1.15/jar
   • conscrypt-openjdk-uber 2.2.1 https://search.maven.org/artifact/org.conscrypt/conscrypt-openjdk-uber/2.2.1/jar
   • spymemcached 2.12.3 https://search.maven.org/artifact/net.spy/spymemcached/2.12.3/jar
   • ehcache-api 3.4.0 https://search.maven.org/artifact/org.ehcache.modules/ehcache-api/3.4.0/jar

6. Deploy the dependencies you downloaded in the previous step. You use Maven to install the dependencies in your local Maven repo.

   • Install the mvn Maven tool.

     mac:

     brew install mvn

     Windows:

     See https://maven.apache.org/guides/getting-started/windows-prerequisites.html for information about installing the mvn Maven tool.

   • For androidx dependencies (browser and localbroadcastmanager), run:

     mvn install:install-file -Dfile=<relative path to aar> -DgroupId=<group ID> -DartifactId=<artifact id> -Dversion=<version> -Dpackaging=aar -DgeneratePom=true

   • For all other dependencies, run:

     mvn install:install-file -Dfile=<relative path to aar> -DgroupId=<group ID> -DartifactId=<artifact id> -Dversion=<version> -Dpackaging=jar -DgeneratePom=true

7. Your local Maven repo should be set. We will modify the build files to use your local Maven repo in the next section.

Edit Gradle build settings and scripts

1. You should edit your project gradle.settings file to look at your local Maven repository. To do this, add mavenLocal() as follows:

   gradle.settings

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           mavenLocal()
       }
   }

2. In your module-level build.gradle file, add the following dependencies:

   build.gradle

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   dependencies {
       	. . .
       implementation 'com.esri.arcgisruntime:arcgis-android:100.15.4'
       implementation 'com.google.code.gson:gson:2.9.0'
       implementation 'androidx.browser:browser:1.4.0'
       implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.1.0'
       implementation 'org.apache.httpcomponents.core5:httpcore5:5.0.4'
       implementation 'org.apache.httpcomponents.core5:httpcore5-h2:5.0.4'
       implementation 'org.slf4j:slf4j-api:1.7.32'
       implementation 'commons-codec:commons-codec:1.15'
       implementation 'org.conscrypt:conscrypt-openjdk-uber:2.2.1'
       implementation 'net.spy:spymemcached:2.12.3'
       implementation 'org.ehcache.modules:ehcache-api:3.4.0'
   
   }

3. In your module-level build.gradle file, within the android block, make sure you have the following directive to set compatibility with Java 8 language features:

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   android {
       . . .
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
       . . .
   }

4. In your module-level build.gradle file, within the android block, make sure you have a buildFeatures block that enables view binding. For more information on view binding, see https://developer.android.com/topic/libraries/view-binding.

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   android {
       . . .
       buildFeatures {
           viewBinding true
       }
       . . .
   }

5. In your module-level build.gradle file, within the android block, make sure you have a packagingOptions block that excludes duplicates of the META-INF. This setting will prevent a compiler error that occurs if you try to include the same file in the META-INF directory more than once in the output. For more information on packaging options, see https://developer.android.com/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions.

   build.gradle

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   android {
       . . .
       packagingOptions {
           exclude 'META-INF/DEPENDENCIES'
       }
       . . .
   }

Required permissions and features

Android is a permissions-separated operating system. Depending on which ArcGIS capabilities you use in your app, you may need to add permissions to your manifest. Make sure that you do not include permissions for capabilities that are not included in your app.

If an app is running on Android API version 22 or earlier, all permissions are requested (and granted or denied), at installation time. If an app is running on Android API version 23 or newer, permissions are requested and automatically granted at installation time. Potentially dangerous permissions, however, must be requested at run time, and you need to add code to your app to do so. The Android framework or Android Support library is used to check for and request permissions if not already granted. For more information, see Declaring Permissions and Requesting Permissions at Run Time.

ArcGIS Runtime API capabilities requiring permissions

Some of the ArcGIS Runtime API for Android capabilites that you use in your app require Android permissions.

• Access to the Internet (most apps will require this): normal permission in Android API 23 and newer.
• Access to the device's GPS will require fine location permissions: dangerous permission in Android API 23 and newer.

The following code example (for the AndroidManifest.xml file) includes these permissions:

1
2
3
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android storage and permissions

As of Android API Level 30, all apps use scoped storage for accessing the file system of the Android device. With scoped storage, an app can access (1) its own files and (2) shared files in a media store. Declaring the <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> permission is no longer supported.

Storage in Android has changed dramatically since API level 29. Consult the following links to learn more about Android storage and permissions:

• Data and file storage overview
• Android storage use cases and best practices
• Access media files from shared storage
• Manage all files on a storage device

Declaring OpenGL ES version

Adding a uses-feature element to the Android manifest will help the Play store make your app available to the correct type of devices.

Apps that use a MapView (2D) require at least OpenGL ES 2.x:

1
<uses-feature android:glEsVersion="0x00020000" android:required="true" />

Apps that use a SceneView (3D) require OpenGL ES 3.x:

1
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

androidx dependency

The DefaultAuthenticationChallengeHandler now uses Chrome Custom Tabs by default in order to prompt users for credentials for OAuth authentication. This provides a better user experience than prompting for credentials in an external browser window. With support for Chrome Custom Tabs, a new transitive dependency of androidx.browser:browser was introduced. This dependency gets automatically configured when you reference the arcgis-android library from your gradle build script. If you download the API manually, you must configure your project to support the androidx dependency yourself.

If your project still depends on the Android Support libraries, which are no longer supported by Google, you will experience compile or runtime issues with the androidx library. You will need to migrate your project to androidx.

Additional downloads

Additional sources of sample code, data, and tools are available to enhance your ArcGIS Runtime development projects. You can even download this guide as stand-alone developer documentation.

Sample code

Browse the comprehensive list of samples in the documentation or download sample code from the GitHub repository.

Interact with live samples using the sample viewer app. Download an .apk version of the sample viewer app from ArcGIS Online or install it from the Google Play Store.

ArcGIS Runtime API for Android Toolkit

The ArcGIS Runtime SDK for Android Toolkit contains controls and utilities to simplify your app development. For example:

• ArcGISArView: Integrates SceneView with ARCore to enable augmented reality (AR).
• Bookmarks: Displays the bookmarks present in a web map.
• Compass: Shows the current orientation of a map or scene by displaying a compass icon that points towards North.
• Scalebar: Displays the representation of an accurate linear measurement on a map.
• PopupView: Displays a Popup's attribute list.

Stand-alone developer documentation

You can download the developer documentation (for any ArcGIS Runtime API) as an archive from the downloads. The archive contains instructions to serve the documentation from a local web server so you can access it without a connection to the internet. The stand-alone documentation includes the developer guide, API reference, tutorials, and samples documentation. This documentation is designed to run on a local stand-alone computer or on an internal network and not on the public internet.

To serve the documentation locally:

• Download the documentation for the ArcGIS Runtime API(s) you want to use. The downloaded files are in a .zip archive format.
• Extract the archive to a local folder. The extracted archive has two subfolders: public and install.
• Open the README.md file in the install folder and follow the instructions for your chosen web server.

Supplemental data

StreetMap Premium

StreetMap Premium for ArcGIS Runtime provides enriched street data, which powers a high-quality cartographic maps and high-quality search, geocoding, and route analysis. StreetMap Premium maps are consistent across all regions of the world and can be taken offline for disconnected use; they can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your app.

If you want to use StreetMap Premium data (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to a region of your choice for development and testing or to license StreetMap Premium data for deployment.

Projection Engine data

Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.

If your app requires grid-based transformations, you can download supporting Projection Engine files from the downloads page. See the Spatial references topic for more information about working with coordinate systems, projections, and datum transformations.

Electronic Navigational Charts (ENC)

Electronic navigational charts (ENCs) are georeferenced vector datasets for the visualization and analysis of hydrographic and maritime information. ArcGIS Runtime supports ENCs that conform to the International Hydrographic Organization (IHO) S-57 standard.

If you want to work with Electronic Navigational Charts (ENC) download the hydrography directory from the downloads page.

See the Display electronic navigational charts topic for more information about working with ENC data.

Next steps

• Overview

  Learn about the API and its capabilities.

• Get started

  Install and setup the API and get your API key.

• Display a map

  Get started with the display a map tutorial.